React Native Crash Reporting mit Sentry einrichten

1. Was Crash Reporting in React Native wirklich löst

Eine React Native App lebt in zwei Laufzeiten gleichzeitig: der JavaScript-Engine (Hermes oder JSC) und den nativen iOS- beziehungsweise Android-Schichten. Ein Fehler kann in beiden entstehen, aber ohne Sentry Crash Reporting sieht ein Entwicklerteam davon nichts. Der Nutzer sieht einen roten Bildschirm, schließt die App oder deinstalliert sie. Die Fehlermeldung, der Gerätetyp, die Betriebssystemversion und der genaue Codepfad bleiben unbekannt, es sei denn, jemand meldet den Vorfall manuell im Support.

Genau hier setzt Crash Reporting mit Sentry an: Ein installiertes SDK fängt unbehandelte JavaScript-Exceptions, Promise-Rejections und native Signalabbrüche automatisch ab, reichert sie mit Kontext an und sendet sie an ein zentrales Dashboard. Das Team erfährt in Minuten statt Wochen, dass ein neues Release auf bestimmten Android-Geräten abstürzt, und kann die genaue Zeile im Quellcode identifizieren, statt Symptome zu raten.

Der Unterschied zwischen einer App mit und ohne Sentry Crash Reporting zeigt sich am deutlichsten nach einem Release: Ohne Monitoring bemerkt man Probleme über sinkende Store-Bewertungen und Support-Tickets, oft Tage später. Mit Sentry erscheint ein Anstieg der Fehlerrate innerhalb von Minuten im Dashboard, verknüpft mit der genauen Release-Version, dem betroffenen Gerätemodell und dem Stacktrace, der direkt zur fehlerhaften Codezeile führt.

2. SDK-Setup: @sentry/react-native einrichten

Die Installation von @sentry/react-native beginnt mit dem Sentry-Wizard, der automatisch die native Konfiguration für iOS und Android anpasst, den Metro-Bundler-Hook für Source Maps registriert und die Basiskonfiguration in die App-Einstiegsdatei einträgt. Der Wizard ersetzt manuelle Bearbeitungen von AppDelegate.mm und MainApplication.kt, die in älteren Sentry-Versionen noch nötig waren.

Zentral ist der Aufruf Sentry.init() möglichst früh im App-Lebenszyklus, noch vor dem Rendern der Root-Komponente. Die DSN (Data Source Name) identifiziert das Sentry-Projekt, tracesSampleRate steuert die Performance-Sampling-Rate, und enableNative aktiviert die Verbindung zu den nativen Crash-Handlern von sentry-cocoa und sentry-android. Ohne diese native Kopplung würde Sentry Crash Reporting nur JavaScript-Fehler sehen, aber Abstürze in nativen Modulen komplett verpassen.

// App.tsx — initialize Sentry as early as possible in the app lifecycle
import * as Sentry from '@sentry/react-native';

Sentry.init({
  dsn: 'https://examplePublicKey@o0.ingest.sentry.io/0',
  environment: __DEV__ ? 'development' : 'production',
  tracesSampleRate: 0.2,
  enableNative: true,
  enableAutoSessionTracking: true,
  release: 'my-app@2.4.0+42',
  beforeSend(event) {
    // Strip personally identifiable data before it leaves the device
    if (event.user) {
      delete event.user.email;
    }
    return event;
  },
});

export default Sentry.wrap(function App() {
  return <RootNavigator />;
});

3. Source Maps und lesbare JS-Stacktraces

Ein JavaScript-Bundle im Produktionsbuild ist minifiziert. Ohne Source Maps liefert Sentry Crash Reporting nur kryptische Zeilennummern in einer komprimierten Datei, keine Zuordnung zum tatsächlichen Quellcode. Der Sentry-Metro-Plugin erzeugt beim Bundlen automatisch Source Maps und lädt sie über sentry-cli hoch, verknüpft mit der exakten Release-Version und dem Build.

Entscheidend ist, dass die Release-Kennung im Client identisch mit der Release-Kennung ist, die beim Source-Map-Upload verwendet wird. Weicht sie ab, findet Sentry keine passende Zuordnung und zeigt weiterhin minifizierten Code an. Ein CI-Schritt, der Release-Erstellung, Source-Map-Upload und Deployment automatisch synchron hält, verhindert dieses häufige Fehlerbild zuverlässig.

#!/usr/bin/env bash
# Upload source maps for a production release before app store submission
set -euo pipefail

RELEASE="my-app@2.4.0+42"

sentry-cli releases new "$RELEASE"
sentry-cli releases files "$RELEASE" upload-sourcemaps \
  ./dist \
  --dist 42 \
  --rewrite

sentry-cli releases finalize "$RELEASE"
echo "Source maps uploaded and release finalized: $RELEASE"

4. Native Crashes: dSYM und ProGuard-Mapping

Native Abstürze entstehen oft in Drittanbieter-Bibliotheken, in nativen Modulen mit Speicherfehlern oder in Bridging-Code zwischen JavaScript und nativer Ebene. Damit Sentry Crash Reporting hier lesbare Stacktraces liefert, statt nur Speicheradressen, muss auf iOS-Seite die dSYM-Datei jedes Builds hochgeladen werden. Sie enthält die Debug-Symbole, die eine Adresse im kompilierten Binärcode einer Funktion und Zeile zuordnen.

Auf Android-Seite übernimmt das ProGuard- beziehungsweise R8-Mapping-File dieselbe Rolle für obfuskierten Code. Ohne dieses Mapping zeigt ein Absturzbericht nur umbenannte Klassen- und Methodennamen wie a.b.c, was die Fehlersuche praktisch unmöglich macht. Der Sentry-Gradle-Plugin lädt das Mapping-File bei jedem Release-Build automatisch hoch, sofern er korrekt in build.gradle eingebunden ist.

// ios/AppDelegate.mm — Sentry native SDK integration point for symbolicated crashes
// Xcode Build Phase "Upload Debug Symbols to Sentry" runs sentry-cli after archiving:
//   sentry-cli debug-files upload --include-sources ./MyApp.xcarchive.dSYM.zip
//
// Ensure Build Settings > Debug Information Format is "DWARF with dSYM File"
// for both Debug and Release configurations, otherwise no dSYM is produced.

5. Breadcrumbs und Kontext anreichern

Ein Stacktrace allein beantwortet selten die Frage, wie ein Nutzer in den fehlerhaften Zustand gelangt ist. Breadcrumbs protokollieren die letzten Aktionen vor einem Absturz: Navigations-Events, API-Aufrufe, Button-Klicks und Konsolen-Ausgaben. Sentry Crash Reporting sammelt viele dieser Breadcrumbs automatisch, etwa über die React-Navigation-Integration, die jeden Screen-Wechsel protokolliert.

Zusätzlich lassen sich benutzerdefinierte Breadcrumbs und Tags setzen, etwa die Nutzer-ID (pseudonymisiert), das Feature-Flag-Set oder der Warenkorb-Status in einer Shopping-App. Diese Anreicherung verwandelt einen isolierten Stacktrace in eine nachvollziehbare Geschichte: welcher Nutzer, welcher Zustand, welche Aktion unmittelbar vor dem Absturz.

// Enrich crash reports with custom breadcrumbs and user context
import * as Sentry from '@sentry/react-native';

function addToCart(product: Product) {
  Sentry.addBreadcrumb({
    category: 'cart',
    message: `Added product ${product.id} to cart`,
    level: 'info',
  });
  cartStore.add(product);
}

Sentry.setUser({ id: hashUserId(currentUser.id) });
Sentry.setTag('feature_flag.checkout_v2', 'enabled');

6. Release Health und Sessions

Neben einzelnen Abstürzen liefert Sentry Crash Reporting auch aggregierte Kennzahlen: die Crash-Free-Session-Rate zeigt, welcher Prozentsatz der App-Sitzungen ohne Absturz endete, aufgeschlüsselt nach Release-Version. Ein Rückgang dieser Rate nach einem Rollout ist ein zuverlässiges Frühwarnsignal, oft bevor Support-Tickets eintreffen.

Sessions werden automatisch getrackt, sobald enableAutoSessionTracking aktiviert ist. Für schrittweise Rollouts, etwa über Staged Rollouts im Play Store, lässt sich die Crash-Free-Rate pro Rollout-Stufe vergleichen, was eine datengestützte Entscheidung ermöglicht, ob der Rollout gestoppt oder fortgesetzt wird, statt sich auf Bauchgefühl zu verlassen.

7. Performance Tracing über Crash Reporting hinaus

Sentry Crash Reporting und Performance-Monitoring teilen sich dieselbe Infrastruktur. Mit tracesSampleRate aktiviertes Tracing misst App-Start-Zeiten, Navigations-Übergänge und die Dauer von Netzwerk-Requests, ohne zusätzliches SDK. Ein langsamer Screen-Übergang wird oft erst durch diese Traces sichtbar, während er in klassischem Crash Reporting unentdeckt bliebe.

Besonders wertvoll ist die Verknüpfung von Traces mit Fehlerereignissen: Ein Timeout bei einem API-Aufruf, der kurz darauf zu einem Absturz führt, erscheint im selben Dashboard als zusammenhängender Vorgang. Das verkürzt die Ursachenanalyse erheblich, weil Performance-Daten und Fehlerdaten nicht mehr in getrennten Tools zusammengeführt werden müssen.

8. sentry-cli in CI/CD-Pipelines integrieren

Manuelle Source-Map-Uploads und dSYM-Uploads sind fehleranfällig, weil sie leicht vergessen werden. Die robuste Lösung integriert sentry-cli direkt in die Release-Pipeline: Nach jedem erfolgreichen Build wird automatisch ein neues Sentry-Release angelegt, Source Maps und Debug-Symbole hochgeladen und der Release als deployed markiert.

Diese Automatisierung stellt sicher, dass Sentry Crash Reporting ab der ersten Minute nach Rollout vollständige Symbolisierung liefert, statt einer Lücke zwischen App-Store-Freigabe und manuellem Upload. Ein zusätzlicher CI-Schritt kann sogar prüfen, ob für jedes hochgeladene Bundle tatsächlich eine passende Source Map existiert, und den Build fehlschlagen lassen, falls nicht.

{
  "sentryCliConfig": {
    "org": "my-organization",
    "project": "my-app-react-native",
    "urlPrefix": "~/",
    "rewrite": true,
    "ignore": ["node_modules", "android", "ios"]
  }
}

// android/app/build.gradle — Sentry Gradle plugin uploads ProGuard/R8 mapping automatically
// apply plugin: "io.sentry.android.gradle"
//
// sentry {
//     autoUploadProguardMapping = true
//     includeProguardMapping = true
// }
//
// This runs during `./gradlew assembleRelease` and requires SENTRY_AUTH_TOKEN
// to be present as an environment variable in the CI job.

9. Sentry im Vergleich zu Bugsnag und Crashlytics

Sentry ist nicht die einzige Option für Crash Reporting in React Native, aber die Kombination aus offenem Ökosystem, kombiniertem Error- und Performance-Monitoring und ausgereifter React-Native-Integration macht sie zu einer naheliegenden Wahl für Teams, die über reines Crash Reporting hinaus wollen.

Firebase Crashlytics punktet mit einem kostenlosen Einstieg und tiefer Google-Play-Integration, bleibt aber bei Source-Map-Handling und flexibler Kontext-Anreicherung hinter Sentry Crash Reporting zurück. Bugsnag ist funktional näher an Sentry, verlangt aber ein separates Produkt für Performance-Daten. Für Teams, die Crashs, Performance und Releases in einem Werkzeug zusammenführen wollen, bleibt Sentry meist die pragmatischste Wahl.

10. Zusammenfassung

Sentry Crash Reporting verwandelt unsichtbare Abstürze in nachvollziehbare, priorisierbare Fehlerberichte. Die SDK-Installation mit Sentry.init() fängt JavaScript-Fehler ab, die native Kopplung über sentry-cocoa und sentry-android erweitert die Abdeckung auf native Abstürze. Source Maps und dSYM-Uploads sorgen dafür, dass Stacktraces lesbar bleiben, statt minifizierten Code oder Speicheradressen zu zeigen.

Breadcrumbs und Kontext-Tags machen aus einem isolierten Fehler eine nachvollziehbare Nutzergeschichte, Release Health liefert aggregierte Kennzahlen für Rollout-Entscheidungen, und die Integration von sentry-cli in die CI/CD-Pipeline stellt sicher, dass Symbolisierung ab der ersten Sekunde nach Rollout funktioniert. Wer diese Bausteine konsequent kombiniert, reduziert die Zeit zwischen Absturz und Fix von Tagen auf Minuten.

11. FAQ: React Native Crash Reporting mit Sentry