Legacy 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 our Android Gradle plugin.

If you’re building an Android project from Unity, the best way to send your shared object and symbol table mapping files to BugSnag is to use our Android Gradle plugin for Unity.

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.

There are two different types of mapping file that can be used to map a stack trace depending on what debug information is available in the shared object file:

• symbol mapping file: Contains all of the debug information required to map back to the original file, line and method.
• symbol table mapping file: Contains the information required to map back to the original method only.

In general the intermediate shared object files generated for an Android NDK build should contain the required details for a symbol mapping file but the shared object files generated for some native Android libraries, for example Unity libraries, will only contain the information for a symbol table mapping file.

Uploading symbol mapping files

To send symbol mapping files to BugSnag, POST them to https://upload.bugsnag.com/so-symbol 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 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-v7a).
• 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 set the com.bugsnag.android.BUILD_UUID value in your AndroidManifest.xml.
• 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 --dwarf=info --dwarf=rawline <path_to_intermediate_so_file> > output_file

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.

Reducing the size of the mapping file

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

cURL example

Here’s an example request with curl:

$ curl --http1.1 https://upload.bugsnag.com/so-symbol \
    -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

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.
• Mapping file does not contain any debug info or lines - indicates that the mapping file is not in the correct format.
• Mapping file does not contain a debug info section - indicates that the debug_info section is missing (normally if --dwarf=info wasn’t passed to objdump).
• Mapping file does not contain a debug lines section - indicates that the debug_line section is missing (normally if --dwarf=rawline wasn’t passed to objdump).

Uploading symbol table mapping files

In some cases the shared object files don’t contain the full debug information required to map back to the original file, line and method but they do contain a symbol table which can be used to map the method. This is normally the case for native Android libraries in Unity.

To send symbol table mapping files to BugSnag, POST them to https://upload.bugsnag.com/so-symbol-table with the following parameters:

• soSymbolTableFile - the path to the shared object symbol table 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-v7a).
• 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 set the com.bugsnag.android.BUILD_UUID value in your AndroidManifest.xml.
• overwrite (optional) - overwrite any existing mappings for this version of your app.

The mapping file

If you are creating the shared object symbol table 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 --sym <path_to_intermediate_so_file>  > output_file

The output should look something like:

SYMBOL TABLE:
0004df48 l     F .text  00000010 __on_dlclose
0004df5c l     F .text  00000004 __on_dlclose_late
0004ebd8 l     F .text  00000018 _ZL24CleanupModule_AndroidJNIv
000524b0 l     F .text  00000614 _ZL12GlobalXToTRS23TransformAccessReadOnlyRN4math4trsXE
00052c50 l     F .text  00000888 _ZL13TRSToGlobalTR15TransformAccessRKN4math4trsXE

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 all 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.

Reducing the size of the mapping file

The API also supports uploading compressed mapping files. For example, to compress the file using gzip:

objdump --sym <path_to_intermediate_so_file> | gzip -c > output_file.gz

cURL example

Here’s an example request with curl:

$ curl --http1.1 https://upload.bugsnag.com/so-symbol-table \
    -F soSymbolTableFile=@/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

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 symbol table 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.
• mapping file does not contain a symbol table - indicates that the mapping file is not in the correct format.
• symbol table within mapping file does not contain function mappings - indicates that the symbol table doesn’t have any appropriate mappings. Often this is due to the symbols not being present in the shared object file.