NDK symbol upload

Upload shared object mapping files to allow Bugsnag to de-obfuscate your Android NDK stack traces.

Overview

For Android applications, when native code is used it will be compiled into shared object files, usually with the symbol names removed.

In order to replace the obfuscated data with a human-readable stack trace, Bugsnag requires a shared object mapping file.

Gradle plugin

If you’re using Android Studio/Gradle to build your Android projects, the best way to send your shared object mapping files to Bugsnag is to use the Bugsnag Android Gradle plugin.

Uploading mapping files

In cases where you cannot use our Gradle plugin, you’ll need to manually upload your mapping file to Bugsnag using our API.

To send mapping files to Bugsnag, simply POST them to https://upload.bugsnag.com with the following parameters:

  • soMappingFile - the path to the shared object mapping file.
  • apiKey - your Bugsnag integration API key for this application.
  • appId - the Android applicationId for this application.
  • versionCode - the Android versionCode for this application release.
  • arch - the architecture of the shared object that the symbols are for (e.g. x86, armeabi).
  • sharedObjectName - the name of the shared object that the symbols are for.
  • versionName (optional) - the Android versionName for this application release.
  • projectRoot (optional) - a path to remove from the beginning of the filenames in the mapping file
  • buildUUID (optional) - a UUID to identify this builds. This is required if you build multiple different apps with the same appId and versionCode. If you use this, you’ll also need to use setBuildUUID() in your app.
  • overwrite (optional) - overwrite any existing mappings for this version of your app.

The mapping file

If you are creating the shared object mapping files without using the Bugsnag Android Gradle plugin then you must run the objdump command with the following parameters, and save the output to a file:

objdump --disassemble --demangle --line-numbers --section=.text <path_to_intermediate_file>

The output should look something like:

000022d6 <crash_priv_inst>:
crash_priv_inst():
/app/src/main/jni/jni entry point.c:72
    22d6:   55                      push   %ebp
    22d7:   89 e5                   mov    %esp,%ebp
/app/src/main/jni/jni entry point.c:75
    22d9:   f4                      hlt
/app/src/main/jni/jni entry point.c:87
    22da:   b8 05 00 00 00          mov    $0x5,%eax

cURL example

Here’s an example request with curl:

$ curl https://upload.bugsnag.com/ \
    -F soMappingFile=@/path/to/mapping.txt \
    -F apiKey=YOUR_API_KEY_HERE \
    -F versionCode=123 \
    -F appId=com.example.android.app \
    -F arch=x86 \
    -F sharedObjectName=libmy-nkd-library.so \
    -F versionName=2.3.0

Response codes

If the file is accepted then an HTTP 200 response will be returned with the body “OK”.

If not, there are several possible problems which will be indicated with an HTTP 4XX response:

  • duplicate shared object file - indicates that Bugsnag already has a file. You can ignore this error by using the buildUUID parameter, or by using the overwrite parameter.
  • invalid apiKey - indicates that the provided apiKey doesn’t correspond to a Bugsnag project.
  • missing param - indicates that the appId or versionCode parameters are missing.