Showing full stacktraces

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:

Using our Gradle plugin

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.

Using the BugSnag CLI

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:

Uploading mappings

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 your build contains multiple variants or has 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.

Creating builds

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.

Configure the BugSnag Android Gradle Plugin

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.

Manually uploading mapping files

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.


Existing error events

Uploaded mappings will only be applied to new error events. Existing error events will not be deobfuscated/symbolicated retroactively.

ProGuard Settings

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.