Android agent crash reporting

By default, mobile monitoring 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 the Crash analysis UI, or receive crash notifications by email. You can also integrate with ticketing systems for further investigation.

Upload the ProGuard or DexGuard file

The Android agent 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

The agent 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 either of the following situations occur, you must manually upload the mapping.txt replacement file:

• 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 Crashes page, you may not have a mapping.txt file uploaded.

Map Processing

Maps are reported for select variant builds

The agent will tag and report only those mapping.txt files generated by Release build-type variants. This behavior can be configured or disabled through the New Relic Gradle Plugin extension.

Variants are assigned unique build IDs

During an execution of a Gradle build, a single unique ID (build ID) was generated to represent all variants of the app built during that invocation. This often led to mismatched crash reports for customers using variants to customize a common app code base.

Each variant is now identified by its own unique ID, which is used when reporting the variant's ProGuard map to New Relic. You can disable this behavior through the New Relic Gradle Plugin extension.

Compress maps prior to upload

As apps get larger, so do their associated maps, which then results in longer upload times when reporting the map. If map reporting time is unreasonably long, the agent can compress the map prior to transfer.

To enable compressed map uploads, add the following to your app's newrelic.properties file:

com.newrelic.compressed_uploads=true

Configure mapping upload host

Add the following to your app's newrelic.properties file to send maps on a redirected server:

# Please only provide the host name as the value without https:// at the beginning or / at the end, for example: xyz.api.com
com.newrelic.mapping_upload_host=xyz.api.com

Deferred crash reporting

In an attempt to address crash report duplication, deferred crash reporting is now the default crash reporting behavior. In this case, crash reports are recorded when they occur, but they're not uploaded until the next application launch.

The previous crash reporting behavior is still available: uploading the crash as soon as it occurs before the application process terminates. You can use the NewRelic.withCrashReportingEnabled(boolean) API method. For example:

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

Disable crash reporting

If you want to use another crash reporting tool, you can disable crash reporting by calling NewRelic.disableFeature(FeatureFlag.CrashReporting) prior to agent initialization. For example:

NewRelic.disableFeature(FeatureFlag.CrashReporting);
NewRelic
      .withApplicationToken("<appToken>")
      .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.

  Copy

• If another handler is already registered, debug logs will include:

  Installing New Relic crash handler and chaining previous exception handler.

  Copy

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 don't see crash reports, 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:

   bash

   Copy

   $
   find <project_root> -name mapping.txt

2. Using a command terminal, upload the ProGuard or DexGuard mapping file:

   • For a US account:

     bash

     Copy

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

   • For a EU account:

     bash

     Copy

     $
     curl -v -F upload=@"<mapping.txt>" -H "X-APP-LICENSE-KEY:<APPLICATION_TOKEN>" https://mobile-symbol-upload.eu.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 mobile monitoring application token.

Android Native Crash Reporting

Starting with New Relic Android agent version 6.7.0, to help track and diagnose native crashes, reporting and analysis has been enhanced to include signal violations and other faults that occur at the native code level during runtime.

Learn more about Android native crash reporting here.