Deobfuscate or symbolicate crash stack traces

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 optimise 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 analyse 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 file

To deobfuscate Java stack traces, you first need to generate a ProGuard mapping file. To learn how, go to the Google Developers site.

Native: Generate a debug symbols file

Android Gradle plug-in 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 plug-in outputs this file in the following project location:

  • app/build/outputs/native-debug-symbols/variant-name/native-debug-symbols.zip

Android Gradle plug-in version 4.0 and earlier (and other build systems)

As part of the build process for an app bundle or APK, the Android Gradle plug-in 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.

  1. Zip up the contents of this directory:
    • $ cd app/build/intermediates/cmake/universal/release/obj
    • $ zip -r symbols.zip .
  2. Manually upload the symbols.zip file to Play Console as described below in Step 2: Upload a deobfuscation or symbolication file.

The 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 plug-in 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 Console

To upload a deobfuscation or symbolication file:

  1. Open Play Console.
  2. Select an app.
  3. On the left menu, select

    Test and release

    > App bundle explorer.
  4. Using the picker in the top right-hand corner, choose the relevant artifact.
  5. Select the Downloads tab, and scroll down to the 'Assets' section.
  6. 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.
Upload files using the Google Play Developer API

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 afterwards will be deobfuscated. You can review deobfuscated stack traces for individual crashes and ANRs on your app's Crashes and ANRs page.

  1. Open Play Console.
  2. Select an app.
  3. On the left menu, select Monitor and improve > Android vitals > Crashes and ANRs.
  4. Select a crash.
  5. 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 symbolise 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.

I’ve uploaded the deobfuscation/symbolication file, so why are my crashes and ANRs still obfuscated?

After you've uploaded a ProGuard mapping file or debug symbols file for a version of your app, only crashes and ANRs that occur afterwards 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.

After uploading the deobfuscation/symbolication file, why are my crashes and ANRs only partially deobfuscated?

This is caused by uploading an incomplete deobfuscation/symbolication file. Make sure that 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.

After uploading the deobfuscation/symbolication file, why do I seem to get fewer but more severe crashes and ANRs?

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.

What happens if I forget to upload the file?

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 afterwards 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 plug-in 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.

What happens if I upload the wrong file?

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:

  1. Open Play Console.
  2. Select an app.
  3. On the left menu, select

    Test and release

    > App bundle explorer
  4. Using the picker in the top right-hand corner, choose the relevant artifact.
  5. Select the Downloads tab, and scroll down to the 'Assets' section.
  6. Click the delete icon next to the incorrect deobfuscation or symbolication file.
  7. 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 afterwards 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 plug-in 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.

I’m currently using APKs. How do I switch to using app bundles?

Visit the Android developers site to get started.

My app contains both native and Java code. Can I upload both a native symbolication file and a Java deobfuscation file?

Yes.

Why do some ANRs not show a stack trace?

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.

Was this helpful?

How can we improve it?
Search
Clear search
Close search
Google apps
Main menu