Crash Reporting

Why Crash Reporting Matters

In production, users encounter crashes you cannot reproduce locally. Without crash reporting, you rely on Play Store reviews — which are delayed, vague, and lack stack traces. Crashlytics gives you real-time crash data with full stack traces, device info, and user impact.

Adding Crashlytics to Your Project

Add the Crashlytics dependencies to your module-level build.gradle.kts:

plugins {
    id("com.android.application")
    id("com.google.gms.google-services")
    id("com.google.firebase.crashlytics")
}

dependencies {
    implementation(platform("com.google.firebase:firebase-bom:33.0.0"))
    implementation("com.google.firebase:firebase-crashlytics-ktx")
    implementation("com.google.firebase:firebase-analytics-ktx")
}

Enable automatic crash reporting in the firebase-crashlytics plugin block:

// At the top of build.gradle.kts
firebaseCrashlytics {
    mappingFileUploadEnabled = true
}

Non-Fatal Exception Logging

Not all issues are hard crashes. You can log caught exceptions to track handled errors:

try {
    processData(rawInput)
} catch (e: ParseException) {
    Firebase.crashlytics().log("Parse error on input: ${rawInput.take(50)}")
    Firebase.crashlytics().recordException(e)
}

Non-fatal exceptions appear in the Crashlytics dashboard alongside fatal crashes, giving you visibility into the full error landscape.

Adding Custom Keys and Logs

Attach context to crash reports to aid debugging:

// Add user-specific context
Firebase.crashlytics().setUserId("user_12345")
Firebase.crashlytics().setCustomKey("feature_flag_new_ui", true)
Firebase.crashlytics().setCustomKey("account_tier", "premium")

// Add breadcrumbs leading to the crash
Firebase.crashlytics().log("Navigated to settings screen")
Firebase.crashlytics().log("Changed theme preference")

Why Symbolication is Necessary

When you build a release APK or AAB with ProGuard/R8 enabled, class names, method names, and line numbers are obfuscated. A crash stack trace in production looks like:

java.lang.NullPointerException: 
  at com.a.b.c.a(SourceFile:12)
  at com.a.b.d.b(SourceFile:45)
``

This is unreadable. **Mapping files** reverse the obfuscation, converting minified names back to their original form.

### How Mapping Files Work

When R8 minifies your code, it generates a `mapping.txt` file in `app/build/outputs/mapping/release/`. This file contains:

com.example.ui.SettingsFragment -> com.a.b.c:
void onSaveClicked() -> a
void loadPreferences() -> b
com.example.data.User currentUser -> c

Crashlytics uploads this mapping file and automatically deobfuscates stack traces.

### Ensuring Mapping File Upload

For Gradle builds, the Crashlytics plugin handles upload automatically when `mappingFileUploadEnabled = true`. For CI/CD pipelines, ensure the mapping file is not cleaned before upload:

```kotlin
// In your build script
firebaseCrashlytics {
    mappingFileUploadEnabled = true
}

// The mapping file is at:
// app/build/outputs/mapping/release/mapping.txt

In CI environments, make sure you do not run ./gradlew clean between the build and the Crashlytics upload step.

Verifying Upload

After a release build, check the Firebase console under Crashlytics > Settings > Mapping files to confirm the mapping file was uploaded for your app version.

Crashlytics Dashboard

The Crashlytics dashboard provides:

• Crash-free users — Percentage of sessions without crashes
• Issue grouping — Crashes grouped by stack trace similarity
• Trends — Whether crash rates are improving or worsening
• Device/OS breakdown — Which devices and Android versions are affected
• Breadcrumbs — User actions leading up to the crash

Configuring Alerts

Set up alerts in Firebase Console:

1. Go to Crashlytics > Alerts
2. Create alerts for:
   • Crash rate exceeds threshold — Alert when crash-free users drop below a percentage
   • New issue detected — Get notified when a new crash appears
   • Regression spike — Alert on sudden increases in a known issue

Using the Crashlytics API

For automated monitoring, use the Firebase Admin SDK or REST API:

// Check crash rate programmatically (admin context)
// Firebase REST API or BigQuery export

// BigQuery export query example:
// SELECT
n//   issue_id,
//   issue_title,
//   count(*) as crash_count
// FROM `project.crashlytics.crashlytics`
// WHERE timestamp > TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 1 DAY)
// GROUP BY issue_id, issue_title
// ORDER BY crash_count DESC

Crash Rate Benchmarks

• < 1% crash-free — Critical; halt rollout and fix immediately
• 1-2% — Investigate priority issues, consider rollback
• 2-5% — Monitor trends, schedule fixes for next release
• > 5% — Unacceptable for production; immediate action required

BigQuery Integration

Export Crashlytics data to BigQuery for custom analysis:

1. Enable BigQuery export in Firebase Console
2. Query crash data with SQL
3. Build custom dashboards or integrate with existing monitoring tools
4. Set up alerts via Cloud Functions triggered by BigQuery queries