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.
The following tools are available to perform this upload during your builds:
The BugSnag Gradle plugin is installed in your Gradle configuration and will automatically upload the relevant mapping files when you build your app. See our Gradle Plugin docs to get started.
Our command line tool provides a toolbox of commands for uploading mapping files after your app has been built, rather than as part of the Gradle build. Consider the following when integrating the CLI in your post-build process:
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
With each upload, some version information is required to uniquely identify the mapping file so that it can be matched to the errors you receive in your BugSnag dashboard. Where possible the required information is parsed from the built manifest file. If you have multiple variants built or a non-standard project layout, you might need to provide extra options in order for the CLI to locate your app manifest or to override the values within it. See the upload android-proguard and upload android-ndk command references for full details.
Although not directly related to mapping and symbol upload, when you have a release candidate build, you may wish to create, or augment, a release on your BugSnag dashboard (see Releases & versions), using the create-build command from your project directory:
$ bugsnag-cli create-build --api-key=YOUR_API_KEY --app-version=YOUR_APP_VERSION
If you are using a Git repository, the source control details to link releases and stackframes directly to your code, will be discovered automatically. See the create-build command reference page for available options and overrides.
When using the BugSnag CLI for uploading mappings, the BugSnag Android Gradle Plugin may no longer be required. If so it can be removed from your project.
However it can still be useful to have it installed in your project if you use BugSnag functions in your native (NDK) code, e.g. bugsnag_leave_breadcrumb or bugsnag_notify, as the BugSnag Gradle plugin will extract the bugsnag-plugin-android-ndk plugin package to allow you to link them against your native libraries.
If you choose to keep the BugSnag Android Gradle Plugin in your project then you will need to disable the upload and create build functionality to avoid duplicating it with your CLI commands:
bugsnag {
uploadJvmMappings = false
uploadNdkMappings = false
reportBuilds = false
}
When installed, the BugSnag Gradle plugin also generates build UUIDs and inserts them into your app manifest to provide a unique identifier for each build so that multiple mappings with the same version code can be uploaded. See Unique build identifiers in our CLI reference if you have both the Gradle plugin and CLI active in your build process.
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.