If you are using ProGuard, DexGuard, or R8 to minify and optimize your app this will cause method and class names to become obfuscated in your stacktraces. Similarly, for applications which use the NDK, native stacktraces from C or C++ code consist of a list of addresses and numeric offsets.
In order for your stacktraces to remain readable in your dashboard, BugSnag requires that you upload your obfuscation mapping file and the symbols from any native code for each release of your app. This page describes how to upload these files as part of your build process.
Our command line tool provides a toolbox of commands for uploading files and creating builds on your dashboard after your app has been built. This is particularly useful for integrating CI and non-Gradle systems.
The simplest approach is to use the upload android-aab command with an Android App Bundle (AAB) as it contains all the necessary files:
$ bugsnag-cli upload android-aab app/build/outputs/bundle/release/app-release.aab
Alternatively you can upload the Proguard/Dexguard/R8 mappings and NDK symbol files separately, pointing at the root of your project directory:
$ bugsnag-cli upload android-proguard /path/to/my-app
$ bugsnag-cli upload android-ndk /path/to/my-app
See the AAB, Proguard and NDK CLI command references for full details.
The BugSnag Android Gradle plugin is installed in your Gradle configuration and will automatically upload the relevant mapping files when you build your app. See our Android Gradle Plugin docs to get started.
The BugSnag Android Gradle plugin supports AGP 4.x-8.x, however in future this tool will be replaced by the BugSnag Gradle plugin: a lighter-weight tool which wraps the CLI tool and has less of a dependency on AGP itself. This new plugin is compatible with AGP 8.x+ and is designed to work best with v6 of the BugSnag Android SDK, so we recommend using the BugSnag Gradle plugin now if you also have v6 of the SDK.
If you prefer, you can upload your mapping files directly to BugSnag using our APIs. For ProGuard, DexGuard, and R8 mapping files see the Android Mapping Upload API reference for more details. For NDK shared object files see the NDK Symbol Upload API reference for more details.
Uploaded mappings will only be applied to new error events. Existing error events will not be deobfuscated/symbolicated retroactively.
If you are using proguard-android-optimize.txt settings then BugSnag will convert the stack traces to a human-readable format, but the original file names might not be available.
If the stack traces provided to BugSnag do not contain a valid file, then we will use the unqualified class name in place of the file name.
The BugSnag Android Gradle Plugin does not automatically upload symbol files for Android library modules (AAR files). Symbol files for library modules can instead be uploaded by extracting the AAR and using the BugSnag CLI, running the android-ndk command either from the root of the library directory or providing a path directly to the symbol file.
The shared object files within a library module (i.e. within the .aar) do not typically contain debug symbols, and therefore you may need to ask the library’s developer to provide debug symbols. Alternatively if you complete the Android NDK build for the library yourself, then the intermediate shared object files will contain the symbols.
To check whether a shared object file contains debug symbols, run the file command with the path to the shared object file. The output will include stripped if the file has been stripped of debug symbols, and debug_info, not stripped if it contains debug symbols.