ExpoReact
Home › Technical Guides › Observability
Observability

Cross-Platform Crash Analytics, Symbolication, and Source Maps

Translate stripped addresses and bytecode offsets into readable TypeScript, Swift, and Kotlin stack traces across every release.

Why Cross-Platform Crashes Span Multiple Layers

In a unified runtime, failures originate in three distinct execution layers: uncaught JavaScript exceptions in application code, native platform crashes inside Swift, Objective-C, Kotlin, or Java modules, and low-level C++ faults inside the rendering or JS engine. Without unified correlation, an app termination looks like an opaque native abort while the root cause was an unhandled promise rejection earlier.

Effective crash analytics attach native build numbers, OTA update identifiers, OS versions, device memory class, active route names, and sanitized navigation breadcrumbs to every event—regardless of whether the crash occurred on iOS, Android, or the web target.

Symbolication Pipeline: dSYMs, R8 Mappings, and Source Maps

Production releases strip debug symbols and minify identifiers to reduce binary footprint. Consequently, raw stack traces report hexadecimal memory addresses or obfuscated names like a.b.c. Unless your CI pipeline uploads matching symbol files at build time, engineers cannot diagnose production incidents.

Each target requires its own artifact: Apple .dSYM archives for iOS native frames, Android mapping.txt (ProGuard/R8) and unstripped .so libraries for Android, and composed TypeScript-to-Metro-to-Hermes source maps tagged with matching Debug IDs. Keep web .map files private inside your telemetry collector rather than serving them on public CDNs.

Monitoring Release Health and ANR Thresholds

Raw crash counts fluctuate with daily traffic spikes; percentages reveal true software quality. Track crash-free session rate and crash-free user rate per release channel, alongside Android Application Not Responding (ANR) freezes and iOS watchdog terminations caused by blocked main threads.

Configure automated regression alerts whenever a staged rollout drops below your target stability baseline—such as 99.5% crash-free sessions—so teams can pause rollouts early. Separating expected offline network timeouts from true code defects keeps alert channels actionable and reduces on-call fatigue.

React Error Boundaries for Graceful Recovery

Not every JavaScript rendering error should terminate the entire application process. Wrapping major feature routes and complex third-party widgets in React Error Boundaries intercepts component tree failures, reports the component stack as a non-fatal telemetry event, and renders a localized recovery UI so users can retry or navigate safely.

Pair telemetry hooks with strict payload scrubbing so request bodies, authorization headers, email addresses, and form field values are stripped from crash breadcrumbs before any diagnostic payload leaves the client device.

Symbolication Artifacts Across Target Platforms

Execution LayerProduction ObfuscationRequired Symbol FileCI Upload Timing
TypeScript / JSMinification + Hermes bytecodeComposed JS/Hermes source mapEvery native & OTA build
iOS NativeStripped Mach-O binaries.dSYM debug symbol archiveEvery Xcode archive build
Android JVMR8 / ProGuard shrinkingmapping.txt deobfuscation fileEvery release Gradle build
Android NDKStripped .so librariesUnstripped .so debug symbolsEvery native NDK build
Web BundleMinified ES modulesPrivate .js.map filesEvery web deploy (not public)

Keep web source maps private in your telemetry collector rather than exposing them publicly on CDNs.

Worked Illustration: Triaging a Release Regression via Telemetry

Illustrative scenario: Release 4.2.1 ramps to 25% of users and crash-free session rate dips from 99.82% to 99.35% over two hours.

  1. Step 1 (Illustrative filter): Filter crashes by appVersion=4.2.1 and otaId=ota_8841; 89% cluster on Android 14 devices.
  2. Step 2 (Illustrative symbolication): Uploaded R8 mapping and composed Hermes source map resolve the frame to CheckoutScreen.tsx line 142.
  3. Step 3 (Illustrative breadcrumbs): Breadcrumbs show a null locale object accessed right after returning from app background.
  4. Step 4 (Illustrative recovery): Pause 4.2.1 rollout, deploy a guarded fallback via OTA ota_8842, and confirm crash-free rate returns to 99.84%.

Engineering Takeaway: Automated symbolication with matching Debug IDs turns an opaque native crash into a two-hour targeted fix.

Crash Telemetry & Symbolication Checklist

  • Embed matching Debug IDs into JS bundles and composed source maps at build time.
  • Automate .dSYM, ProGuard mapping.txt, and .so symbol uploads inside CI.
  • Upload web .map files privately to telemetry collectors, never to public CDNs.
  • Tag every crash event with native version, OTA ID, platform, and active route.
  • Wrap feature routes in React Error Boundaries with non-fatal crash reporting.
  • Alert on crash-free session drops and Android ANR threshold breaches.

Frequently Asked Questions

Why do Hermes stack traces look broken even after uploading a Metro source map?

Hermes bytecode compilation applies an extra transform pass. You must compose the bundler source map with the Hermes compiler map so offsets align.

Should web source maps be hosted publicly alongside JS bundles?

No. Upload web source maps privately to your error collector and strip sourceMappingURL comments on public production assets.

What is the difference between a JS crash and an Android ANR?

A JS crash is an unhandled JavaScript exception, whereas an ANR happens when the Android UI thread blocks for roughly 5 seconds.

How do you prevent sensitive user inputs from appearing in crash breadcrumbs?

Configure telemetry hooks to scrub request bodies, auth headers, email addresses, and form input values before events leave the device.

Primary References & Standards

  • Apple Developer Documentation — Diagnosing Issues Using Crash Reports and Device Logs
  • Android Developers Documentation — Shrink, Obfuscate, and Optimize Your App (R8) & ANRs
  • TC39 / Source Map Revision 3 Specification

Related Technical Guides