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 explore the crash data deeper with New Relic Insights, or integrate with ticketing systems for further investigation.
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.
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.
If either of the following situations occur, you must manually upload the
mapping.txt replacement file:
- If the
mapping.txtfile is renamed using the DexGuard
-printmappingoption, 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
Agent version 5.27.0 introduces changes to the way the agent plugin process maps during 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.
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.
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
Agent version 6.0.0 introduces changes to the way the agent plugin processes crashes at runtime.
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:
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:
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 don't see crash reports, check the debug logs for messages like this.
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:
mapping.txtfile(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
releasevariant 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
Using a command terminal, upload the ProGuard or DexGuard mapping file:
For a US account:
curl -v -F upload=@"<mapping.txt>" -H "X-APP-LICENSE-KEY:<APPLICATION_TOKEN>" https://mobile-symbol-upload.newrelic.com/symbol
For a EU account:
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
<APPLICATION_TOKEN>is your mobile monitoring application token.
If you need more help, check out these support and learning resources:
- Browse the Explorers Hub to get help from the community and join in discussions.
- Find answers on our sites and learn how to use our support portal.
- Run New Relic Diagnostics, our troubleshooting tool for Linux, Windows, and macOS.
- Review New Relic's data security and licenses documentation.