Android agent crash reporting

By default, New Relic Mobile enables crash reporting for your mobile applications to help track and diagnose crashes. When an Android application crashes, the agent uploads a crash report to the New Relic collector. The crash details will then be processed and de-obfuscated automatically if you are using ProGuard or DexGuard.

You can view detailed information about crashes in New Relic Mobile's Crash analysis UI, or receive crash notifications by email. You can also explore the crash data deeper with New Relic Insights, or integrate with ticketing systems for further investigation.

Upload the ProGuard or DexGuard file

The Android agent for New Relic Mobile supports ProGuard and DexGuard. DexGuard is an extension to ProGuard, and it behaves the same as ProGuard when dealing with crash symbolication and obfuscated code maps.

ProGuard obfuscates your code by renaming classes, fields, and methods with semantically obscure labels. DexGuard adds another additional layer of obfuscation and security, but otherwise behaves identically to ProGuard. If ProGuard or DexGuard is enabled, the stack trace produced by a crash consists only of these obfuscated labels, which are not human-readable.

Follow the SDK installation or upgrade instructions to configure ProGuard or DexGuard and enable crash reporting. Be sure to create the newrelic.properties file containing your application token.

Use mapping.txt file

New Relic Mobile uses the ​mapping.txt file produced during a ProGuard/DexGuard-enabled build. This file consists of the obfuscated label names, and provides reverse mapping between obfuscated and plain text labels. You must use the copy of mapping.txt generated during the build that produced your final application. The application's build ID changes each time an APK is generated, and the build ID in the mapping file must match the ID contained in each uploaded crash report.

After you create a newrelic.properties file containing your New Relic app token in your project, the ProGuard or DexGuard mapping.txt file will be uploaded automatically after each build.

Exception:

  • If the mapping.txt file is renamed using the DexGuard -printmapping option, the Android agent will be unable to locate or upload the stripped names.
  • If you see obfuscated crash reports in the Mobile Crashes page, you may not have a mapping.txt file uploaded.

If either of these situations occur, you must manually upload the mapping.txt replacement file.

Disable crash reporting

If you want to use another crash reporting tool, you can disable New Relic Mobile's crash reporting by calling .withCrashReportingEnabled(false) during agent initialization. For example:

NewRelic
      .withApplicationToken("<appToken>")
      .withCrashReportingEnabled(false)
      .start(this.getApplication());

Debug the crash reporter

Crash reporting for Android is designed to work with other crash reporting frameworks by chaining the uncaught exception handler if it is already registered.

  • If no other framework has been found (or if New Relic is the first framework registered), the debug logs will include:

    Installing New Relic crash handler.
  • If another handler is already registered, debug logs will include:

    Installing New Relic crash handler and chaining previous exception handler.

Every time New Relic catches an exception, it is logged to DEBUG level. For example:

A crash has been detected in <className>.

If New Relic catches an exception but crash reporting has been disabled for any reason, this message is logged:

A crash has been detected but crash reporting is disabled.

If you do not see crash reports in the New Relic Mobile user interface, check the debug logs for messages like this.

Manually upload a ProGuard or DexGuard map file

In some unusual circumstances, it may not be possible to automatically upload the ProGuard or DexGuard mapping file. This is often due to incorrectly creating a newrelic.properties file containing your application token. This will result in build errors or warnings with detailed log messages.

To manually upload a ProGuard or DexGuard map file:

  1. Find the mapping.txt file(s) in the project's build directory For example, the file is located in the <PROJECT_ROOT>/app/build/outputs/mapping/<BUILD_VARIANT> directory for projects that use Android Studio. Generally, a release variant is used when building the final version of the application. The following command is useful for finding map files:
    find <project_root> -name mapping.txt
  2. Using a command terminal, upload the ProGuard or DexGuard mapping file:

    curl -v -F upload=@"mapping.txt" -H "X-APP-LICENSE-KEY:<APPLICATION_TOKEN>" https://mobile-symbol-upload.newrelic.com/symbol

Replace the following in your command:

  • <mapping.txt> is the full path to the ProGuard or DexGuard mapping.txt file.
  • <APPLICATION_TOKEN> is your New Relic Mobile application token.

For more help

Recommendations for learning more: