To upload symbol files, the Memfault CLI must be used.
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.
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
--package, etc.) to specify
the required information directly. You can run
memfault upload-android-app-symbols --help to get more information on the all
Proguard / R8 configuration
If you are using Proguard / R8 minification/obfuscation, it is recommended to
-keepattributes LineNumberTable configuration option in your app's
# Uncomment this to preserve the line number information for
# debugging stack traces:
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