Uploading Android Bugreports & Symbols

Using the Memfault CLI tool to upload

The easiest way to upload Android bugreport and/or symbol files is using the Memfault CLI tool.

The rest of this guide assumes you have the Memfault CLI tool installed. If you have not installed it yet, please follow the installation instructions.

Uploading Android binary symbol files

When processing traces from a bugreport.zip, 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.

Android OS symbol files

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 --email <EMAIL> --password <PASSWORD> --org <ORG_SLUG> \
--project <PROJ_SLUG> upload-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 ...

Android NDK app symbol files

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

The symbol files can be found in the build output folder of the app at:

<APP_SOURCE_ROOT>/build/intermediates/cmake/debug/obj/<ARCH>/libnative-lib.so

The Android NDK builds .so files for various CPU architectures. You only need to upload for the architectures that your (virtual) devices actually use and expect to process bugreports from. However, the easiest is to upload all of them by pointing the memfault tool to the parent folder:

$ memfault --email <EMAIL> --password <PASSWORD> --org <ORG_SLUG> \
--project <PROJ_SLUG> <APP_SOURCE_ROOT>/build/intermediates/cmake/debug

Uploading an Android bugreport.zip

To upload a bugreport.zip file that is located at, for example /path/to/bugreport.zip, run this command:

$ memfault --email <EMAIL> --password <PASSWORD> --org <ORG_SLUG> \
--project <PROJ_SLUG> upload-bugreport /path/to/bugreport.zip

Note: support for passing a Memfault-Project-Key instead of email, password, org and project to the tool is coming soon.

Uploading without the Memfault CLI tool

Uploading is a 3 step process:

  1. "Prepare" the file upload by making a POST request to /api/v0/upload to obtain a upload_url and token.
  2. Make a PUT request to the upload_url to upload the file.
  3. Finally, make a POST request with the token to the appropriate upload processing API. For example, after uploading an Android Bugreport file, POST the token to /api/v0/upload/bugreport.

Please consult the HTTP API documentation for details on each of the requests.