crash-reporting-strategy

name	crash-reporting-strategy
description	Crash reporting for mobile - symbolication, SLOs, tagging, triage workflow, and comparing Crashlytics, Sentry, Bugsnag, Firebase, and native (APM) reporters. Use when setting up or improving crash reporting.

Crash Reporting Strategy

Instructions

Crash reports are the most reliable signal from real users. Without a disciplined strategy they become noise. Good crash reporting gives you an actionable ranked list, readable stack traces, and an SLO you can hold yourself to.

1. Pick a Reporter (or two)

Reporter	Strengths	Notes
Firebase Crashlytics	Free, deep Android + iOS support	Default for most teams
Sentry	Unified across mobile, web, backend; release health; rich context	Pair with Sentry for tracing/logging
Bugsnag	Release stability scores	Paid
Instabug, Embrace, Shake	Session replay, user-context	Heavier footprint
Xcode Organizer + Play Console	Always-on, no SDK needed	Limited grouping, no pre-release

Running two reporters is reasonable (e.g., Crashlytics for crash signal + Sentry for release health + logs). Two is the max.

2. Symbolication

Unsymbolicated stack traces are useless. Upload debug symbols on every release.

• iOS: upload dSYMs after every archive. Crashlytics and Sentry both have Fastlane plugins. Bitcode is deprecated; modern builds no longer require the bitcode compiler re-symbolication dance.
• Android: upload ProGuard/R8 mapping and native symbol files (.so debug symbols) per build.
• Flutter: upload --split-debug-info symbols.
• React Native: upload Hermes bundle + source map for the JS side, plus native symbols for the native side.

Automate upload in the pipeline; fail the release if upload fails.

3. Release Tagging

Every event carries:

• app.version and app.build.
• env (dev, staging, prod).
• flavor if applicable.
• releaseStage (beta, production).
• deviceModel, osVersion, locale.
• userId as a hashed id, never PII.
• Current screen / feature flag state on crash.

Crashlytics.crashlytics().setUserID(hashedUserId)
Crashlytics.crashlytics().setCustomValue(flags.value("checkout_v2"), forKey: "checkout_v2")

FirebaseCrashlytics.getInstance().setUserId(hashedUserId)
FirebaseCrashlytics.getInstance().setCustomKey("checkout_v2", flags.bool("checkout_v2"))

4. Breadcrumbs and Logs

• Record navigation events, network requests (method + path only, no query strings with secrets), and important state transitions as breadcrumbs.
• Attach the last 20-50 breadcrumbs to each crash.
• Do not log PII, tokens, or message content.
• Use CLS_LOG / SentryBreadcrumb or equivalent; avoid sending every print to the reporter.

5. Handled Exceptions

Not every error is a crash. Handle errors in domain code, report the serious ones:

• FirebaseCrashlytics.recordException(...) or Sentry.captureException(...) for errors that indicate a bug, not user input.
• Tag them with severity so they do not dominate the crash list.
• Never report user-cancelled or offline-expected errors.

6. SLOs

Define crash SLOs and display them on a dashboard.

• Crash-free sessions: 99.8% (typical target for a mature consumer app; higher for fintech/health).
• Crash-free users: 99.5%.
• ANR rate (Android): below 0.47% (Play Console threshold).
• Foreground hang rate (iOS): monitor via Xcode Organizer "Hangs" metric.

Gate rollouts on these (see staged-rollouts).

7. Triage Workflow

• Daily triage during active release. New or regressed issues get an owner within 24 hours.
• Group issues by stack trace fingerprint; the reporter does this, but review for false groups.
• Rank by user impact, not raw count. A crash affecting 0.5% of users in onboarding beats 50 crashes in a settings corner.
• Assign owners per area (payments, sync, onboarding) so issues route fast.
• Version hygiene: do not fight crashes from two versions ago; focus on current + previous.

8. Actionable Rules

• Every new-in-release issue must be acknowledged before the next rollout step.
• Every top-10 issue has an assignee, a hypothesis, and a reproduction attempt.
• Every fix must reference the issue ID in the commit message.
• Crashes that cannot be reproduced get a defensive fix (null check, guard) only if the context justifies it, never a silent swallow.

9. Beware of Blind Spots

• Early-boot crashes: many reporters require the SDK to be initialized before the crash. Pair with a native uncaughtException logger or platform breadcrumbs.
• Background processes: some reporters do not capture crashes in separate processes (widgets, app extensions, isolates). Configure per process.
• ProcessLifecycle on Android differs from Activity lifecycle. Use the broader one for app-level breadcrumbs.
• React Native: JS errors and native errors are different worlds. Capture both.
• Flutter: Dart errors via FlutterError.onError and PlatformDispatcher.instance.onError (async errors) separately.

void main() {
  runZonedGuarded(() {
    FlutterError.onError = (details) => Crashlytics.recordError(details.exception, details.stack);
    PlatformDispatcher.instance.onError = (e, s) { Crashlytics.recordError(e, s); return true; };
    runApp(const MyApp());
  }, (e, s) => Crashlytics.recordError(e, s));
}

10. Anti-Patterns

• Shipping without symbol upload. You will regret it.
• Logging PII or secrets in breadcrumbs.
• Silencing crashes with broad catch blocks to clean up dashboards.
• Chasing old-version tails. Fix current and previous; accept drift beyond that.
• Ignoring ANRs because "they are not crashes". Users see them the same way.
• One reporter with no native-level coverage on a platform.

Checklist

• A primary crash reporter is integrated; optional secondary is justified.
• Symbol uploads happen on every release for every platform.
• Events tagged with version, build, env, flag state, and hashed user id.
• Breadcrumbs record navigation, network, and state transitions; no PII.
• Crash-free session / user SLOs are defined and displayed.
• Triage workflow has named owners and daily cadence during releases.
• Blind spots covered: early-boot, background processes, JS/native split.
• Fixes reference issue IDs in commits for traceability.
• Handled exceptions are reported selectively with severity tags.