Crashes and ANRs on Android produce a stack trace, which is a snapshot of the sequence of nested functions called in your program up to the moment it crashed. These snapshots can help you identify and fix any problems in the source.
If your app or game was developed using Java and you use ProGuard to optimize and obfuscate your app, you can upload a ProGuard mapping file for each version of your app in Play Console. If your app or game was developed using native code, like C++, you can upload a debug symbols file for each version of your app in Play Console. This makes it easier to analyze and fix your crashes and ANRs.
Important: Only ReTrace-compatible mapping files are supported for deobfuscation of apps compiled in Java. This is the same format used by ProGuard or R8.
Step 1: Generate a deobfuscation or symbolication file
To deobfuscate or symbolicate your app's crashes and ANRs for a version of your app, you first need to generate the required files for the same version of your app. You must generate and upload a file for each new version of your app for deobfuscation or symbolication to work.
Java: Generate a ProGuard mapping fileTo deobfuscate Java stack traces, you first need to generate a ProGuard mapping file. To learn how, go to the Google Developers site.
Android Gradle plugin version 4.1 and later
If your project builds an Android App Bundle, you can automatically include the debug symbols file in it. To include this file, add the following to your app's build.gradle file:
android.defaultConfig.ndk.debugSymbolLevel = 'FULL'
Note: The limit for the debug symbols file is 800 MB. If your debug symbols footprint is too large, use SYMBOL_TABLE instead of FULL to decrease the file size.
If your project builds an APK, use the build.gradle build setting above to generate the debug symbols file separately. Manually upload the debug symbols file to the Google Play Console as described below in Step 2: Upload a deobfuscation or symbolication file. As part of the build process, the Android Gradle plugin outputs this file in the following project location:
app/build/outputs/native-debug-symbols/variant-name/native-debug-symbols.zip
Android Gradle plugin version 4.0 and earlier (and other build systems)
As part of the build process for an app bundle or APK, the Android Gradle plugin keeps a copy of the unstripped libraries in a project directory. This directory follows a structure similar to this:
app/build/intermediates/cmake/universal/release/obj
├── armeabi-v7a/
│ ├── libgamenegine.so
│ ├── libothercode.so
│ └── libvideocodec.so
├── arm64-v8a/
│ ├── libgamenegine.so
│ ├── libothercode.so
│ └── libvideocodec.so
├── x86/
│ ├── libgamenegine.so
│ ├── libothercode.so
│ └── libvideocodec.so
└── x86_64/
├── libgameengine.so
├── libothercode.so
└── libvideocodec.so
Note: If you use a different build system, you could modify it to store unstripped libraries in a directory with the required structure above.
- Zip up the contents of this directory:
$ cd app/build/intermediates/cmake/universal/release/obj$ zip -r symbols.zip .
- Manually upload the symbols.zip file to Play Console as described below in Step 2: Upload a deobfuscation or symbolication file.
There limit for the debug symbols file is 800 MB. If your file is too big, it’s likely because your .so files contain a symbol table (function names), and also DWARF debugging info (files names and lines of code). These are not needed to symbolicate your code, and can be removed by running this command:
$OBJCOPY --strip-debug lib.so lib.so.sym
Note: $OBJCOPY points to the specific version for the ABI you're stripping, for example:ndk-bundle/toolchains/aarch64-linux-android-4.9/prebuilt/linux-x86_64/bin/aarch64-linux-android-objcopy
Step 2: Upload a deobfuscation or symbolication file
To deobfuscate or symbolicate your app's crashes and ANRs for a version of your app, you must upload the deobfuscation or symbolication files for each version of your app.
Important: This step is only required for developers using APKs. If you’re using an app bundle and Android Gradle plugin version 4.1 or later, then there's nothing you need to do. We'll automatically grab the deobfuscation file from the bundle and you can skip to Step 3: View deobfuscated crash stack traces. You can learn more about app bundles on the Android Developers site.
Upload files using Play ConsoleTo upload a deobfuscation or symbolication file:
- Open Play Console.
- Select an app.
- On the left menu, select Test and release > App bundle explorer.
- Using the picker in the top-right-hand corner, choose the relevant artifact.
- Select the Downloads tab, and scroll down to the "Assets" section.
- Click the upload arrow for the mapping file or the debug symbols as applicable to upload the deobfuscation or symbolication file for the version of your app.
To upload files using the Google Play Developer API, go to the Google Developers site.
Step 3: View deobfuscated crash stack traces
After you've uploaded a ProGuard mapping file or debug symbols file for a version of your app, crashes and ANRs that occur afterward will be deobfuscated. You can review deobfuscated stack traces for individual crashes and ANRs on your app's Crashes & ANRs page.
- Open Play Console.
- Select an app.
- On the left menu, select Monitor and improve > Android vitals > Crashes & ANRs.
- Select a crash.
- In the "Stack Traces" section, you'll see your deobfuscated and symbolicated stack traces.
Important: Once you've uploaded a mapping file for a version of your app, only future crashes and ANRs for that version of your app will be deobfuscated. Crashes and ANRs for a version of your app that happen before you've uploaded its respective mapping file won't be deobfuscated.
Frequently asked questions
I don’t want to use the Play Console deobfuscation/symbolication. Can I just do it offline?Play Console uses ndk-stack to symbolize stack traces for native apps, and ReTrace for Java crashes. If you choose not to share your deobfuscation files, you can copy the obfuscated crash stacks from Play Console and use the appropriate tool offline to symbolicate them. However, this process must be done manually for each crash stack, making it slow and time-consuming. By providing your deobfuscation files, Play Console will handle this for you.
After you've uploaded a ProGuard mapping file or debug symbols file for a version of your app, only crashes and ANRs that occur afterward will be deobfuscated. You’ll need to allow time for new crashes and ANRs to be reported by users' devices before you see deobfuscated crashes and ANRs in Play Console.
This is caused by uploading an incomplete deobfuscation/symbolication file. Make sure you include the symbolication files for your entire app, especially if you use a complex or multi-stage build process. One of the most common reasons for partial deobfuscation is if you use a third-party library. In this case, you may be able to get the deobfuscation files from the library provider.
Without deobfuscation files, the same crash or ANR on a 32-bit and 64-bit device, or an ARM and an Intel device will be shown separately. By providing deobfuscation files, we can cluster these crashes together, giving you a better perspective of the most impactful crashes and ANRs for your app.
If you forget to upload the file for a new version of your app, crashes and ANRs will revert to being obfuscated. Follow instructions above to upload it now. After you've uploaded a ProGuard mapping file or debug symbols file for a version of your app, only crashes and ANRs that occur afterward will be deobfuscated. You’ll need to allow time for new crashes and ANRs to be reported by users' devices before you see deobfuscated crashes and ANRs in Play Console.
To avoid the risk of forgetting to upload the file, consider changing your build process to use app bundles with Android Gradle plugin version 4.1 or later. In this case, you can automatically include the debug symbols file in the app bundle by following the instructions on the Android Developers site.
If you upload the wrong file for a version of your app, crashes and ANRs will revert to being obfuscated. To upload a corrected version:
- Open Play Console.
- Select an app.
- On the left menu, select Test and release > App bundle explorer
- Using the picker in the top-right-hand corner, choose the relevant artifact.
- Select the Downloads tab, and scroll down to the "Assets" section.
- Click the delete icon next to the incorrect deobfuscation or symbolication file.
- Once the incorrect version is deleted, click the upload icon and upload the correct file for the version of your app.
After you've uploaded the correct ProGuard mapping file or debug symbols file for a version of your app, only crashes and ANRs that occur afterward will be deobfuscated. You’ll need to allow time for new crashes and ANRs to be reported by users’ devices before you see deobfuscated crashes and ANRs in Play Console.
Tip: To avoid the risk of uploading an incorrect version of the file, consider changing your build process to use app bundles with Android Gradle plugin version 4.1 or later. In this case, you can automatically include the debug symbols file in the app bundle by following the instructions on the Android Developers site.
Visit the Android Developers site to get started.
Yes.
Occasionally, the system encounters an ANR but is unable to collect the stack trace. In this event, the ANR is shown to give you a more complete view of your app stability, but the stack trace itself cannot be displayed. ANRs without stack traces are grouped by type and activity, so reviewing and fixing similar ANRs may help to reduce the number without stack traces.