Upload shared object mapping files to allow Bugsnag to de-obfuscate your Android NDK stack traces.
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.
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 our Gradle plugin.
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:
soSymbolFile- the path to the shared object mapping file.
apiKey- your Bugsnag integration API key for this application.
appId- the Android
applicationIdfor this application.
versionCode- the Android
versionCodefor this application release.
arch- the architecture of the shared object that the symbols are for (e.g. x86, armeabi-v7a).
sharedObjectName- the name of the shared object that the symbols are for.
versionName(optional) - the Android
versionNamefor 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
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.
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 --dwarf=info --dwarf=rawline <path_to_intermediate_so_file> > output_file
Locate the correct
objdump binary for a given architecture using
find $ANDROID_HOME/ndk-bundle -iname "*objdump" on macOS, Linux, and Cygwin.
The output should look something like:
Contents of the .debug_info section: Compilation Unit @ offset 0x0: Length: 0x8417 (32-bit) Version: 4 Abbrev Offset: 0x0 Pointer Size: 4 <0><b>: Abbrev Number: 1 (DW_TAG_compile_unit) <c> DW_AT_producer : (indirect string, offset: 0x0): Android (4751641 based on r328903) clang version 7.0.2 (https://android.googlesource.com/toolchain/clang 003100370607242ddd5815e4a043907ea9004281) (https://android.googlesource.com/toolchain/llvm 1d739ffb0366421d383e04ff80ec2ee591315116) (based on LLVM 7.0.2svn) <10> DW_AT_language : 4 (C++) <12> DW_AT_name : (indirect string, offset: 0x107): /app/src/main/source.cpp
If the output does not look like this it may be due to the
objdump command being run on a shared object file where the debug symbols have been stripped. The command needs to be run against an intermediate shared object file that is output from the build process before the symbols are stripped.
The API also supports uploading compressed mapping files. For example, to compress the file using gzip:
objdump --dwarf=info --dwarf=rawline <path_to_intermediate_so_file> \ | gzip -c > output_file.gz
Here’s an example request with curl:
$ curl --http1.1 https://upload.bugsnag.com/ \ -F soSymbolFile=@/path/to/objdump/output \ -F apiKey=YOUR_API_KEY_HERE \ -F versionCode=123 \ -F appId=com.example.android.app \ -F arch=x86 \ -F sharedObjectName=libmy-ndk-library.so \ -F versionName=2.3.0
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:
versionCodeparameters are missing.
--dwarf=infowasn’t passed to
--dwarf=rawlinewasn’t passed to