Uploading Android Symbol Files

To upload symbol files, the Memfault CLI must be used.

info

This guide assumes the Memfault CLI tool installed. If it is not installed it yet, please follow the installation instructions.

Uploading Android OS symbol files

While processing Traces from diagnostic data, Memfault will attempt to provide source file and line numbers for stackframes from native binaries. In order to do this, the symbol files for these native binaries need to be uploaded to Memfault.

When building the Android OS, the final image will contain executables from which the symbols (debug info) has been stripped. Usually, "unstripped" versions of the executables are also kept in the build output. For example, in builds of recent versions of AOSP, they are output in out/target/product/generic/symbols/**. The exact location may be a bit different for your project. To test whether a file contains symbols, check out this article.

To upload all symbol files, run this command:

$ memfault upload-aosp-symbols out/target/product/generic/symbols

It's best to hook this into Continuous Integration when a build is released for internal consumption so that Memfault will immediately have the ability to symbolicate crashes.

The command will run through all files in the given directory. For each file, it will check whether it's a symbol file that has not yet been uploaded and upload it if necessary. The output of the command looks like this:

INFO: /aosp/symbols/out/target/product/vsoc_x86/symbols/init: ELF file with .debug_info and GNU Build ID: 706b026c8cc3e970b409d79c11c182a5
INFO: /aosp/symbols/out/target/product/vsoc_x86/symbols/init: uploaded!
INFO: /aosp/symbols/out/target/product/vsoc_x86/symbols/apex/com.android.adbd/bin/adbd: ELF file with .debug_info and GNU Build ID: 37398ca3d0492ba8b1e708a13ab2f9e0
INFO: /aosp/symbols/out/target/product/vsoc_x86/symbols/apex/com.android.adbd/bin/adbd: uploaded!
INFO: /aosp/symbols/out/target/product/vsoc_x86/symbols/apex/com.android.adbd/lib/libcrypto.so: ELF file with .debug_info and GNU Build ID: a2a7ab7cea9d8c482f31b3ee3a71c5ee
INFO: /aosp/symbols/out/target/product/vsoc_x86/symbols/apex/com.android.adbd/lib/libcrypto.so: skipping, already uploaded.
... etc ...

Uploading Android App symbol & mapping files

For traces in a bugreport.zip that originate from an Android app, Memfault will also attempt to provide source file and line numbers for stackframes from both native/C/C++ (NDK) code as well as Java code.

For Android apps that use the Android NDK or JNI (Java Native Interface), binary symbol files will need to be uploaded for each version of an app.

In case the app has been obfuscated or minimized by R8 (or Proguard), the associated mapping file (mapping.txt) will need to be uploaded as well for each version of an app.

Using the upload-android-app-symbols command

The easiest way to upload all required files in one go, is using the upload-android-app-symbols command, passing the build variant and path to the Android app build output directory:

$ memfault upload-android-app-symbols \
    --build-variant release <APP_SOURCE_ROOT>/build

The command will use the .apk in the build tree to automatically infer the package identifier, the version code and version name. It will then upload the binary symbol files (only applicable if the app uses the NDK) and upload the mapping file (only applicable if the app has R8 or Proguard enabled).

If this automatic behavior does not work in your use case, consider using option flags (i.e. --version-code, --version-name, --package, etc.) to specify the required information directly. You can run memfault upload-android-app-symbols --help to get more information on the all the options.

Proguard / R8 configuration

If you are using Proguard / R8 minification/obfuscation, it is recommended to enable the -keepattributes LineNumberTable configuration option in your app's proguard-rules.pro file:

# Uncomment this to preserve the line number information for
# debugging stack traces:
-keepattributes LineNumberTable

Without this option, the generated mapping.txt file will not contain enough information for Memfault to be able to fully deobfuscate stack traces from the app.