feat(react-native): Android crash/ANR symbolication, bundle id, and native stack delivery

[yduartep]

Summary

Android release builds can upload R8 mapping.txt and native symbols, but the SDK must send the same bundle id at runtime and ship native Java/Kotlin stack text in a shape the collector can retrace. This PR wires bundle identity, Gradle upload, previous-session crash replay, and ANR reporting end to end.

Runtime bundle id (appBuildIdentity)

• Derives meta.app.bundleId as {applicationId}@{versionCode}@{versionName} from react-native-device-info.
• Metro preamble (__faroBundleId_<appName>) and explicit config.app.bundleId take precedence.
• Plumbed through initializeFaro → makeRNConfig.

Gradle composed source map upload (android/build.gradle)

• Reads bundle id from app/build/faro/bundle-id-release.txt written by faroWriteBundleIdRelease.
• Validates applicationId@versionCode@versionName before upload.
• Uses FARO_SOURCEMAP_* env vars, with sourcemaps.config.json as fallback for endpoint/appId/stackId/apiKey.
• Upload task depends on faroWriteBundleIdRelease when the Faro Gradle plugin is applied.

Previous-session native crashes

Problem: After a fatal crash, ApplicationExitInfo on the next launch often has no traceInputStream (seen on emulators and Android 16). Without a stack, ingest cannot R8-retrace and the plugin shows a generic crash with no useful title.

FaroUncaughtExceptionHandler — installs as the default Thread.UncaughtExceptionHandler. On an uncaught exception it serializes Log.getStackTraceString(throwable) (exception class, message, and at … frames) and writes it to disk before the process is killed, then forwards to the previous handler so crash behaviour is unchanged.

FaroCrashTraceCache — stores that serialized trace plus a timestamp in SharedPreferences using commit() (synchronous) so the write survives immediate process death. On the next launch, FaroCrashReporter matches the cached trace to the matching ApplicationExitInfo row (±10s) when the OS trace is missing or lacks an exception header, then clears the cache after use.

FaroCrashReporter — reads getHistoricalProcessExitReasons for crash exits (not ANRs), builds JSON for CrashReportingInstrumentation, merges OS trace + cached trace, and drops rows that are ANR timeouts or already covered by ANR detection (avoids a second generic crash line for the same incident).

parseAndroidCrashTrace — parses ApplicationExitInfo / Log.getStackTraceString text into:

• native frames with module (R8 retrace input), and
• embedded Hermes/Metro frames (JS source-map input when a fatal JS error includes both).

crashErrorMessage — builds the error title from parsed trace, exception class, or ApplicationExitInfo description; skips rows with no stack and no useful title.

CrashReportingInstrumentation — sends type: 'crash' with parsed stackFrames, nativeExceptionType in context, and error.stack cleared so the JS reporter stack does not override native frames.

Previous-session ANRs

Problem: A live ANR watchdog snapshot can capture the wrong thread (crash-killer frames) or be lost if the process dies before the React bridge sends telemetry.

FaroAnrReporter — on API 30+, reads ApplicationExitInfo with REASON_ANR, pulls traceInputStream, and exports one JSON report per new ANR (deduped by timestamp). Exposed to JS as getHistoricalAnrReports.

AnrThreadDumpParser — extracts the "main" thread at … frames from the multi-thread OS dump (the blocked UI thread, not a background watchdog thread).

FaroAnrCache — when ANRTracker fires, persists the ANR JSON with commit() before the process can be killed; acknowledgeANRs removes entries after Faro sends them; detection timestamps prevent FaroCrashReporter from emitting a duplicate crash for the same ANR.

ANRInstrumentation — on init: drain getHistoricalAnrReports first, then pending tracker cache as fallback; on API 30+ defer live onANRDetected to the next-launch AppExitInfo path; dedupe by timestamp window.

anrStack — filters tracker stacks that contain Android/Faro crash-handler frames (handleApplicationCrash, KillApplicationHandler, FaroUncaughtExceptionHandler) instead of the blocked app code.

Tests

parseAndroidCrashTrace.test.ts, crashErrorMessage.test.ts, appBuildIdentity.test.ts, initialize.test.ts, anrStack.test.ts.

Dependencies

Requires faro-android-gradle-plugin for bundle-id-release.txt and symbol upload, collector Android retrace (androidretrace), and a release app with mapping.txt uploaded.

Verification

cd packages/react-native
yarn quality:test
yarn quality:lint
yarn build

Release build with symbols uploaded: trigger native crash or ANR, relaunch app. Crash rows should show retraced Kotlin/Java frames and a concrete exception title. ANR rows should show type: ANR with retraced main-thread frames and no extra generic crash row for the same trigger.

Screenshots

1. FE O11y Errors — ANR detail with deobfuscated *.kt file:line frames.

2. FE O11y Errors — list with a single ANR row (no paired generic crash).

3. Native RuntimeException with R8-retraced Kotlin frames.

4. Native Crash:

5. Handled Exception

6. Unhandled Exception

[robert-northmind]

Is this android specific crash-error-message logic?
If yes, did we guard it so only applies to Android?

[yduartep]

Good question! This logic is Android-specific and is only invoked from Android native modules. The CrashReportingInstrumentation class is only instantiated on Android (via FaroCrashReporter.getCrashReports() in native Java code). iOS uses a different crash reporting path. The functions are in shared TS files for easier testing, but the entry point is platform-gated at the native module level.

[robert-northmind]

Like, it looks like we also call this for iOS. Or maybe I am missing something

[yduartep]

You're right to check! The parseAndroidCrashTrace function is Android-specific and is only called from the Android code path. The CrashReportingInstrumentation is only instantiated when FaroCrashReporter.getCrashReports() (Android native module) returns crash data. iOS doesn't call into this instrumentation at all - it uses a different crash reporting mechanism. The Android-specific parsing stays in shared TS for testing convenience, but the native module layer acts as the platform guard.

[robert-northmind]

Again here, looks like we assume this is only going to run for Android

[yduartep]

Correct observation! This warning message is Android-specific because it references Android's ApplicationExitInfo traceInputStream and the UncaughtExceptionHandler cache. This code path is only reached when processing Android crash reports from FaroCrashReporter.getCrashReports() (Android native module). iOS doesn't call into this instrumentation - it has a separate crash reporting implementation. The platform guard happens at the native module level where getCrashReports() only exists on Android.

[yduartep]

Platform-Specific Crash Reporting Refactor

@robert-northmind Thank you for the excellent feedback on code organization! I've refactored the crash reporting instrumentation to address your concerns about platform-specific code clarity.

What Changed

Before: Single instrumentation.ts with conditional Platform.OS checks scattered throughout the code, making Android-specific logic (like parseAndroidCrashTrace) appear generic.

After: Clean separation using the Strategy Pattern:

crashReporting/
├── BaseCrashReportingInstrumentation.ts  ← Abstract base class
├── android/
│   └── AndroidCrashReportingInstrumentation.ts
└── ios/
    └── IosCrashReportingInstrumentation.ts

Key Improvements

1. No more if/else platform checks - Each platform has its own implementation class
2. Clear file organization - Android-specific code lives in android/, iOS in ios/
3. Easier to extend - Adding iOS crash reporting just means implementing the abstract methods
4. Better maintainability - Each platform can evolve independently
5. Type safety - Platform-specific parsed trace types are properly separated

Implementation Details

• BaseCrashReportingInstrumentation extends BaseInstrumentation and defines abstract methods for platform-specific behavior
• AndroidCrashReportingInstrumentation implements Android-specific logic (ApplicationExitInfo, R8 retracing, Java stack parsing)
• IosCrashReportingInstrumentation implements iOS-specific logic (PLCrashReporter format, signal mapping) with comprehensive tests
• Main index.ts exports the correct implementation based on Platform.OS at module load time
• Usage for consumers remains unchanged: new CrashReportingInstrumentation()

Testing

• ✅ All quality checks pass (lint, tests, build, circular deps)
• ✅ Added comprehensive test coverage for iOS crash error messages
• ✅ Tested in React Native demo app - crash reporting still works correctly

This architecture makes it explicit which code is platform-specific and provides a clear path for future iOS crash reporting implementation.

[aranhave]

Retested the latest head locally. Release build works, runtime bundle id is coming through and native crash + ANR payloads both include the expected fatal=true signal and source stack. I only left two small questions: one around passing the API key as a CLI arg, and one around repeated ANR detections for the same blocked period. Everything else I checked looks good to me :)

[aranhave]

should we avoid passing the API key as a CLI arg here? Gradle --info / process listings can expose command-line args. env forwarding would keep the key out of the command line.

[aranhave]

in my local run one long ANR replayed as multiple ANR exception payloads plus an anr_count measurement. Should we collapse repeated tracker detections for the same blocked period?

[benjoseph-grafana]

This timeout object seems to be inited to a 5 second value and never updated. Is this what we want?

[benjoseph-grafana]

Having a nearby ANR does not mean app crashed for the same reason. Not a blocker, but worth tracking it somewhere.

[robert-northmind]

Nice 🤩
I left some minor comments. But all of mine are optional.
I think thought that maybe you should tackle the feedback from Ben and Vishwan. They know Andorid the best

[robert-northmind]

I think this class has no unit tests? Should we consider adding some?
Seems like a good way to ensure it works as expected.

[robert-northmind]

I'm not sure though how easy it is to add tests for kotlin code in a RN project.

[robert-northmind]

I think same here. This seems like a pretty testable class. Maybe we would need to break out some dependencies and pass them in. Not sure how to best write/setup tests for Kotlin

[robert-northmind]

Does ReactNative more or less only run on Android and iOS/iPadOS etc?
If not, should we be a bit careful here any maybe do something like:

if (Platform.OS === 'android') {
    return AndroidCrashReportingInstrumentation;
} else if (Platform.OS === 'ios') {
    // RN reports both iOS and iPadOS under the "ios" name
    return IosCrashReportingInstrumentation;
} else {
     return NoOpCrashReportingInstrumentation;
}