Android Error Reporting#
Overview#
This document introduces the Flashcat Android RUM SDK's error capture mechanism, including Java/Kotlin crashes, NDK native crashes, ANR (Application Not Responding) reporting, manual error reporting, and obtaining deobfuscated stack traces.Error Types#
Flashcat Android RUM can monitor the following types of errors:Java/Kotlin Crashes#
The SDK automatically captures unhandled Java/Kotlin exceptions, including:Runtime exceptions (such as NullPointerException, IndexOutOfBoundsException)
NDK Crashes (Native Crash)#
If your application uses native code (C/C++), the SDK supports capturing NDK crashes and including them in error tracking.ANR (Application Not Responding)#
The SDK can detect and report ANR issues, helping you identify user experience problems caused by main thread blocking.Custom Errors#
In addition to automatically captured errors, you can manually report custom errors using the RUM SDK to track specific issues such as business logic errors.Basic Configuration#
Ensure you have completed basic SDK integration following the SDK Integration Guide. Crash reporting is enabled by default, and the SDK will automatically capture unhandled exceptions in your application.Add NDK Crash Reporting#
If your application contains native code (C/C++), you need to add the NDK crash reporting module to capture native crashes.Step 1: Add Dependency#
Add the NDK crash reporting dependency to your app module's build.gradle file:Step 2: Enable NDK Crash Reporting#
Enable NDK crash reporting after SDK initialization:Add ANR Reporting#
ANR (Application Not Responding) refers to situations where the application's main thread is blocked for an extended period, causing the app to become unresponsive to user input.Enable ANR Detection#
Enable ANR detection in your RUM configuration:ANR detection monitors main thread responsiveness. When main thread blocking exceeding the threshold is detected, the SDK automatically records an ANR event.
Manual Error Reporting#
Through the addError API, you can manually report handled exceptions, custom errors, or other errors not automatically captured.Example: Reporting Errors#
Error Source Types#
RumErrorSource available values:| Value | Description |
|---|
RumErrorSource.NETWORK | Network error |
RumErrorSource.SOURCE | Source error |
RumErrorSource.CONSOLE | Console error |
RumErrorSource.LOGGER | Logger error |
RumErrorSource.AGENT | Agent error |
RumErrorSource.WEBVIEW | WebView error |
RumErrorSource.CUSTOM | Custom error |
Example: Reporting Network Errors#
Get Deobfuscated Stack Traces#
If your application has code obfuscation enabled (ProGuard/R8), reported crash stacks will be obfuscated. By uploading mapping files, obfuscated stacks can be restored to original class names, method names, and line numbers.Step 1: Add Plugin Dependency#
Add the Flashcat Gradle plugin to your project's root build.gradle file:Step 2: Apply Plugin#
Apply the plugin in your app module's build.gradle file:Configure the Flashcat plugin in your build.gradle file:Upload Mapping Files#
After configuration, the plugin will automatically upload mapping files during the build process. You can also manually run the upload task:For example, for the release variant:Upload NDK Symbol Files#
If you're using NDK crash reporting, you also need to upload NDK symbol files to get readable native stacks:Plugin Configuration Options#
| Property | Description |
|---|
versionName | App version name (defaults to version declared in android block) |
serviceName | Service name (defaults to app package name) |
site | Data reporting site |
checkProjectDependencies | Controls whether the plugin checks for Flashcat SDK dependency. Options: none (ignore), warn (warning), fail (fail, default) |
Mapping File Size Limit#
Mapping file size is limited to 500 MB. If the file is too large, you can use the following options to reduce file size:When using mappingFilePackageAliases, stacks in Flashcat error tracking will use aliases instead of original package names. It's recommended to only use this option for third-party dependencies.
Track Background Events#
By default, only crashes that occur while a view is active are tracked. If you want to track crashes when the app is in the background, enable background event tracking:Tracking background events may generate additional sessions, which could affect billing. If you have questions, please contact the Flashcat support team.
Limitations and Considerations#
Crash Detection Limitations#
SDK initialization timing: Crashes can only be detected after SDK initialization. It's recommended to initialize the SDK as early as possible in Application.onCreate().
View association: Crashes must be associated with a RUM view. If a crash occurs before a view is displayed or after the app is backgrounded, it may not be reported. This can be mitigated by using trackBackgroundEvents(true).
Sampling rate impact: Only crashes in sampled sessions are retained. If the session sampling rate is not 100%, some crashes may not be reported.
Symbolication Limitations#
Ensure mapping files are correctly uploaded with each new version release.
Different build variants (such as debug/release) require uploading their respective mapping files.
NDK symbol files must contain debug information for correct symbolication.
Test Verification#
Verify Java/Kotlin Crashes#
1.
Add test code to trigger a crash in your application:
2.
Run the application and trigger the crash
3.
Restart the application and wait for the SDK to upload the crash report
4.
View the crash report in the Flashcat console's Error Tracking module
Verify NDK Crashes#
1.
Add a test crash in native code:
2.
Call this native method from Java/Kotlin code
3.
Restart the application and wait for the SDK to upload the crash report
4.
Confirm the stack has been correctly symbolicated (showing function names, file names, and line numbers)
Verify ANR#
1.
Execute a time-consuming operation on the main thread:
2.
After triggering, try to interact with the application
3.
Check if the Flashcat console received an ANR report
Error Data Structure#
Each error record contains the following properties:| Property | Type | Description |
|---|
error.source | string | Error source (such as source, network, custom) |
error.type | string | Error type or error code (such as NullPointerException) |
error.message | string | Error message |
error.stack | string | Error stack trace |
error.is_crash | boolean | Whether it's a crash |
context | Object | Custom context information, passed through addError's attributes |
Best Practices#
1.
Initialize SDK early: Initialize the SDK in Application.onCreate() to ensure as many crashes as possible are captured.
2.
Enable background event tracking: If your application has significant background operations, consider enabling trackBackgroundEvents.
3.
Upload symbol files correctly:Upload corresponding mapping files for each release version
If using NDK, also upload NDK symbol files
Integrate symbol file upload in your CI/CD pipeline
4.
Enrich error context: Attach business-related context information (such as user ID, operation type) when manually reporting errors.
5.
Filter irrelevant errors: Use setErrorEventMapper to filter errors from third-party SDKs or irrelevant errors to reduce noise.
Next Steps#
微信扫码交流