Report Crashes on Android

Firebase Crash Reporting creates detailed reports of the errors in your app. Errors are grouped into issues based on having similar stack traces, and triaged by the severity of impact on your users. In addition to receiving automatic reports, you can log custom events to help capture the steps leading up to a crash.

Set up Crash Reporting

Do the following to set up Crash Reporting on Android:

  1. If you haven’t already, set up Firebase for your Android project.
  2. In the Firebase console, add your app to your Firebase project.
  3. Add the dependency for Crash Reporting to your app-level build.gradle file:
    compile 'com.google.firebase:firebase-crash:10.2.6'

Create your first error

Firebase Crash Reporting automatically generates reports for fatal errors (or uncaught exceptions). However, you can also generate reports in instances where you catch an exception but still want to report the occurrence. To report such an error, you can follow these steps:

  1. Add a call to the static report method in the main activity:
    FirebaseCrash.report(new Exception("My first Android non-fatal error"));
  2. Launch the app.
  3. In adb logcat or Android Studio logs, look for the message confirming that Crash Reporting is enabled.
  4. Check the Crash Reporting section of the Firebase console to see the error. Note that it takes 1-2 minutes for errors to show there.

Create custom logs

You can use Crash Reporting to log custom events in your error reports and optionally the logcat. If you wish to log an event and don't want logcat ouput, you only need to pass a string as the argument, as shown in this example:

FirebaseCrash.log("Activity created");

If you want to create logcat output, you must also supply the log level and a tag.

Deobfuscate ProGuard labels

ProGuard generates a mapping.txt file that maps ProGuard-obfuscated symbols to their original names. If you have ProGuard enabled, uploading your mapping files allows you to see deobfuscated stack traces in the Crash Reporting interface.

For testing purposes, you can configure ProGuard for debug build types, and then build with the ./gradlew assembleDebug command as shown below:

debug {
   minifyEnabled true
   proguardFiles getDefaultProguardFile('proguard-android.txt'),
     'proguard-rules.pro'
}

Uploading ProGuard mapping files with Gradle

To view deobfuscated stack traces in the Firebase console, you can use a Gradle task created by the Crash Reporting plugin to upload your ProGuard mapping file to Firebase.

To configure the Crash Reporting plugin:

  1. Add rules to your root-level build.gradle file to include the Crash Reporting plugin:
        buildscript {
          repositories {
            jcenter()
            // ...
          }
    
          dependencies {
            // ...
            classpath 'com.google.firebase:firebase-plugins:1.0.5'
          }
        }
    
  2. In your app project's Gradle file (usually app/build.gradle), add the line shown below, under `ADD THIS`, to enable the Crash Reporting plugin:
        apply plugin: 'com.android.application'
        // ADD THIS
        apply plugin: 'com.google.firebase.firebase-crash'
    
        android {
          // ...
        }
    
        dependencies {
          // ...
        }
    
  3. Next, create a service account and a private key:

    Download a service account key to authenticate your uploads. From the Firebase console, select your project, and then click Generate New Private Key.

  4. Add a property called FirebaseServiceAccountFilePath with the file path to $HOME/.gradle/gradle.properties, or specify another path on the command line using the -P flag. You can later update the FirebaseServiceAccountFilePath property to run a task with a different service account file.

    Alternatively, you can specify the path of the mapping file on the command line using the -P flag to set the property like this:

    ./gradlew -PFirebaseServiceAccountFilePath=/usr/ServiceAccount/MyApp-a287fsd34.json ...
  5. From your project directory, you can run a gradlew command to both build the APK and upload its mapping file. For example:

    ./gradlew :app:firebaseUploadReleaseProguardMapping

    The exact name of the upload task varies depending on your build variant name, following this pattern: firebaseUpload<VariantName>ProguardMapping. For a complete list of possible upload task names, run the following gradlew command:

    ./gradlew :app:tasks

    You can also specify Grade properties to use when uploading a ProGuard mapping file using the firebaseUploadArchivedProguardMapping task. You can use this task to specify the Gradle properties for FirebaseCrashMappingFilePath, FirebaseCrashVersionCode, and FirebaseCrashPackageName, as shown in the following example:

    FirebaseCrashMappingFilePath=path/to/mapping/file
    FirebaseCrashVersionCode=2
    FirebaseCrashPackageName=example.package.name
    
    In this example, your project uses the default google-services.json file located in your project's module folder, typically app/. If you prefer not to use a google-services.json file, you should also specify Gradle properties for both FirebaseCrashApiKey and FirebaseCrashAppId.

Working with apps that build multiple APKs

The plugin also works for applications that utilize Multiple APK Support. For each build variant task, the task will upload mapping files for all the APKs of that variant.

For example, suppose you have a build variant called fullRelease and multiple APKs such as app-full-armeabi-v7a-release.apk and app-full-armeabi-release.apk to support different architectures, shown in the following Gradle example.

    productFlavors {
        full {
            applicationId "com.google.firebase.sample.testapp"
            versionName "1.0-full"
        }
    }

    splits {
        abi {
            enable true
            reset()
            include 'armeabi', 'armeabi-v7a'
            universalApk true
        }
    }

Running the ./gradlew :app:firebaseUploadReleaseProguardMapping task uploads ProGuard mapping files for app-armeabi-v7a-release.apk and app-armeabi-release.apk to the server. The output to the console shows the following for these uploads:

Successfully uploaded proguard mapping file for app fullArmeabiRelease with versionCode: 1!
Successfully uploaded proguard mapping file for app fullArmeabi-v7aRelease with versionCode: 2!

Uploading ProGuard mapping files manually

Alternatively, you can manually upload a mapping.txt file to the Firebase console by browsing to Crash Reporting, then choosing the Mapping Files tab.

You can find the file to upload at a file path that is similar to the following, but specific to your app:

<project root>/<module name>/build/outputs/mapping/<build type>/<appname>-proguard-mapping.txt

For example:

app/build/outputs/mapping/debug/app-proguard-mapping.txt

Next Steps

To learn about configuring email alerts when new issues or regressions are reported, see Configure Email Alerts.

Send feedback about...

Need help? Visit our support page.