Android mapping support

Upload your Android mapping files to Bugsnag.

Overview

If you are using ProGuard or the Jack Toolchain to shrink your app, this will cause method and class names to become obfuscated, which makes debugging harder as the original file names, line numbers, and method names are not available.

In order to replace the obfuscated data with a human-readable stack trace, Bugsnag can use a mapping file.

ProGuard or Jack

By default Android applications are shrunk/obfuscated using ProGuard which has been the primary Android optimizer for some time. It is possible to control the way that ProGuard operates by using ProGuard configuration files.

Jack is a new Android toolchain that compiles Java source directly into Android dex bytecode. There are a few advantages to using Jack including the ability to use Java 8 Language Features. The Jack toolchain optimizes code in a similar way to ProGuard, using the same configuration files (but it does not support all of the options), and producing similar mapping files.

Gradle plugin

If you’re using Android Studio/Gradle to build your Android projects, the best way to send your mapping files to Bugsnag is to use the Bugsnag Android Gradle plugin.

Please note that you will need to set minifyEnabled to true, if you wish the gradle plugin to upload your mapping file automatically.

android {
  buildTypes {
    release {
      minifyEnabled true
    }
  }
}

ProGuard settings

We use the line numbers of crashes to help with error grouping. You’ll need explicitly to tell ProGuard to not strip this information by adding the following line to your ProGuard configuration:

-keepattributes LineNumberTable,SourceFile
-keep class com.bugsnag.android.NativeInterface { *; }
-keep class com.bugsnag.android.Breadcrumbs { *; }
-keep class com.bugsnag.android.Breadcrumbs$Breadcrumb { *; }
-keep class com.bugsnag.android.BreadcrumbType { *; }
-keep class com.bugsnag.android.Severity { *; }
-keep class com.bugsnag.android.ndk.BugsnagObserver { *; }

If you are using our Gradle plugin, this will automatically be added to your ProGuard config.

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 (class name will be used instead of file name in this case).

Jack settings

When configuring using Jack add the following lines to your gradle configuration:

jackOptions {
    enabled true
    additionalParameters("jack.dex.debug.lines": "true")
    additionalParameters("jack.dex.debug.source": "true")
}

and the following to your ProGuard configuration:


-keepattributes LineNumberTable,SourceFile

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.

Manually uploading mapping files

In cases where you are not using Gradle, you’ll need to manually upload your mapping file to Bugsnag using our API. See the Android Mapping Upload API reference for more details.