React Native
Strukturierte Logs, JavaScript-Fehler und Abstürze aus deiner React-Native-App, über die SDKs für Swift und Android.
Das React-Native-SDK ist ein schlankes TurboModule über den SDKs für Swift und Android. Die nativen SDKs halten die Warteschlange auf der Festplatte, senden in Batches, wiederholen fehlgeschlagene Sendungen, führen Sessions und melden native Abstürze. Dieses Paket ergänzt, was nur JavaScript sieht: nicht abgefangene Fehler, unbehandelte Promise-Rejections, Render-Fehler von React und Screens von React Navigation.
Es braucht React Native 0.80 oder neuer mit der New Architecture und React 19. Apps laufen unter iOS 16 oder neuer und Android 7.0 (API 24) oder neuer.
Interne Vorschau: Dieses Paket ist noch nicht veröffentlicht. Bis dahin ist
@lyrelog/react-native nicht auf npm, und die nativen SDKs, auf denen es aufbaut, sind ebenfalls
nicht veröffentlicht.
Installation
pnpm add @lyrelog/react-native
cd ios && pod installUnter iOS bringt der Pod das Swift-Paket Lyrelog über Swift Package Manager mit. Setze das
Deployment Target deiner App (und die Zeile platform :ios im Podfile) auf 16.0 oder höher. Unter
Android lädt Gradle com.lyrelog:lyrelog-android von Maven Central, was die Berechtigung
INTERNET hinzufügt.
Starten
Starte einmal, so früh wie möglich, in index.js vor AppRegistry. Ein zweiter Aufruf behält die
erste Konfiguration. Events, die vor init geloggt werden, werden ignoriert, aber setUser und
setConsent, vor init aufgerufen, bleiben erhalten und werden angewendet, sobald es läuft.
import { AppRegistry } from "react-native";
import { Lyrelog } from "@lyrelog/react-native";
import App from "./src/App";
Lyrelog.init({
apiKey: "lyr_ing_...", // ingest-only: it can append events, never read them
});
AppRegistry.registerComponent("main", () => App);Events gehen an https://ingest.lyrelog.com. Übergib endpoint nur, um sie woanders hinzuschicken.
Er muss https sein; unverschlüsseltes http geht nur für localhost, 127.0.0.1 oder ::1
(den iOS-Simulator) und im Android-Emulator für 10.0.2.2.
Nichts im SDK wirft Exceptions in deine App. In einem Development-Build werden ein fehlender
Schlüssel oder ein fehlendes natives Modul (die App wurde nach der Installation nicht neu gebaut)
einmal mit console.warn gemeldet.
Events loggen
Eine Funktion pro Level: trace, debug, info, notice, warning, error, critical, oder
log(level, message, options).
Lyrelog.info("checkout_done", { attrs: { items: 3, latency_ms: ms } });
Lyrelog.error("payment_declined", {
category: "checkout",
attrs: { code: 51 },
payload: { response },
});Attribute sind kleine Felder zum Filtern und für Diagramme: Strings, Zahlen, Booleans, null,
Arrays und verschachtelte Objekte bis 4 Ebenen. Die Payload ist beliebiges JSON, für die Details,
die du nur liest, wenn du ein einzelnes Event öffnest. minimumLevel (Standard debug) verwirft
niedrigere Level, bevor sie in den nativen Code gelangen.
Logger für jeden Bereich
Ein Logger versieht jedes Event mit seiner category. Er hat jedes Level, dazu log und
captureException.
const sync = Lyrelog.logger("sync");
sync.warning("sync_conflict", { attrs: { records: 2 } });Nutzer
Lyrelog.setUser(playerId); // attached to every following event
Lyrelog.setUser(null); // on sign-outLyrelog.sessionId liefert die ID der aktuellen Session, zum Beispiel zum Anzeigen in einem
Support-Screen. Die Nutzer-ID wird zwischen Starts nicht gespeichert: Rufe setUser bei jedem
Start erneut auf.
Screens
Mit React Navigation verteilst du trackNavigation per Spread auf den Container:
import { NavigationContainer, createNavigationContainerRef } from "@react-navigation/native";
import { trackNavigation } from "@lyrelog/react-native";
const navigationRef = createNavigationContainerRef();
export default function App() {
return (
<NavigationContainer ref={navigationRef} {...trackNavigation(navigationRef)}>
{/* your navigators */}
</NavigationContainer>
);
}Jeder angezeigte Screen loggt screen_viewed (Bereich navigation) mit screen,
previous_screen und seconds_on_previous, und jedes folgende Event wird mit einem Attribut
screen versehen. Als Name dient der Routenname; übergib name: (route) => ..., um einen anderen zu
wählen, oder gib undefined zurück, um eine Route zu überspringen. Deine eigenen onReady und
onStateChange gehören in die Optionen und laufen nach denen von Lyrelog.
Ohne React Navigation rufst du Lyrelog.screen("Settings") auf oder useLyrelogScreen("Settings")
in der Komponente des Screens. Ein erneuter Aufruf von screen mit demselben Namen loggt nichts.
Schalte das Taggen mit attachScreen: false ab.
Abgefangene Fehler
try {
await store.purchase(product);
} catch (error) {
Lyrelog.captureException(error, { category: "store" });
}Es sendet das Event exception, das jedes SDK sendet: Level error, die Attribute error_type
und error_message und eine Payload mit Name, Nachricht, Stack und bis zu 3 Ursachen
(error.cause). attrs fügt eigene hinzu; level ändert das Level. In JavaScript lässt sich
alles werfen: Auch ein String oder ein Objekt wird aufgezeichnet.
Die Stacks sind so, wie Hermes sie meldet. In einem Release-Build zeigen sie in das Bundle: Bewahre die Source Map des Builds auf, um sie zu lesen.
Nicht abgefangene Fehler
Mit captureErrors (standardmäßig an) klinkt sich das SDK in die Fehlerbehandlung von React Native
ein:
| Was passiert | Event | Level, Bereich | mechanism |
|---|---|---|---|
| Ein fataler JavaScript-Fehler, etwa ein throw in einem Timer oder Event-Handler | app_crashed | critical, diagnostics | js_fatal |
| Ein Render-Fehler, den keine Error Boundary abgefangen hat | app_crashed | critical, diagnostics | react_render |
Ein nicht fataler Fehler, an ErrorUtils gemeldet | exception, handled: false | error | js_error |
| Eine unbehandelte Promise-Rejection | exception, handled: false | error | unhandled_rejection |
Ein fataler Fehler wird auf die Festplatte geschrieben, bevor die App beendet wird, mit bis zu
1,5 Sekunden Wartezeit, und dann gesendet, wenn es geht, sonst beim nächsten Start. Er wird
als app_crashed im Bereich diagnostics erfasst, wie die nativen Absturzberichte, sodass JavaScript- und
native Abstürze im Dashboard beieinanderliegen.
Jeder Fehler wird einmal aufgezeichnet. Nicht fatale, nicht abgefangene Fehler werden auf
10 pro Minute begrenzt, und derselbe Fehler höchstens einmal alle 10 Sekunden; Lyrelog.skippedErrors
zählt, was ausgelassen wurde. Die zuvor installierten Handler laufen weiter: die Red Box und
LogBox in der Entwicklung, der Absturz im Release.
Error Boundaries
import { LyrelogErrorBoundary } from "@lyrelog/react-native";
<LyrelogErrorBoundary
category="feed"
fallback={({ error, reset }) => <Retry onPress={reset} />}
>
<Feed />
</LyrelogErrorBoundary>Ein Render-Fehler in den Komponenten darunter wird als exception mit mechanism: error_boundary und dem Component
Stack von React (component_stack in der Payload) aufgezeichnet, und stattdessen wird fallback
angezeigt. onError wird aufgerufen, nachdem er aufgezeichnet wurde. Ohne Fallback rendert die Boundary
nach einem Fehler nichts.
Native Abstürze
Diese kommen von den nativen SDKs (captureCrashes, standardmäßig an) und werden beim nächsten Start
im Bereich diagnostics gesendet: nicht abgefangene JVM-Exceptions unter Android als
app_crashed; unter iOS die Berichte von MetricKit, Abstürze als app_crashed und Hänger als
app_hung. Siehe Abstürze unter Android und
Abstürze und Hänger in Swift.
Unter Android beendet ein fataler JavaScript-Fehler die App mit einer Java-Exception. Sobald das
app_crashed aus JavaScript auf der Festplatte liegt, umgeht diese Exception den Recorder des
Android-SDKs, sodass derselbe Absturz nicht doppelt gemeldet wird.
Umgebungen und Plattform
Die Umgebung ist die des nativen SDKs: unter iOS development in Debug-Builds, testflight in
TestFlight, sonst production; unter Android development, wenn die App debuggable ist, sonst
production. Deine eigenen Debug-Builds senden development, während das Dashboard mit
production öffnet: Wähle development in der oberen Leiste, um sie zu sehen.
Die Plattform ist ios oder android. Beides lässt sich überschreiben:
Lyrelog.init({
apiKey: key,
environment: isBeta ? "beta" : undefined, // undefined = detected
});Events nennen dieses Paket und das native SDK darunter (sdk ist
lyrelog-react-native/0.1.0 lyrelog-swift/0.1.0 oder lyrelog-react-native/0.1.0 lyrelog-android/0.1.0).
Einwilligung
Lyrelog.init({ apiKey: key, consent: "pending" });
// later, when the person chooses:
Lyrelog.setConsent("granted"); // sends, including what was kept while pending
Lyrelog.setConsent("denied"); // deletes everything and stops recordingpending behält Events auf dem Gerät, ohne sie zu senden. Ohne erteilte Einwilligung wird nichts
hochgeladen. Die Einwilligung wird zwischen Starts nicht gespeichert: Speichere die Entscheidung
der Person selbst (zum Beispiel mit AsyncStorage) und übergib sie jedes Mal an init.
Attestierung
attest (standardmäßig an) weist die App unter iOS mit App Attest und unter Android mit Key
Attestation nach, sodass ihre Events als verifiziert gespeichert werden. Siehe
Verifizierte Events.
Optionen
| Option | Standard | Was |
|---|---|---|
apiKey | Der Ingest-Schlüssel des Projekts, lyr_ing_... | |
endpoint | https://ingest.lyrelog.com | Wohin Events gehen |
consent | granted | granted, pending oder denied |
environment | erkannt | Jeder Name |
platform | ios / android | Welcher Teil des Produkts sendet |
minimumLevel | debug | Niedrigere Level werden verworfen |
flushIntervalMs | 15000 | Wie oft Events aus der Warteschlange im Vordergrund gesendet werden |
sessionTimeoutMs | 30 Minuten | Eine neue Session nach so langer Zeit ohne Event |
maxDiskBytes | 20 MB | Was auf dem Gerät warten darf; die ältesten gehen zuerst |
redactKeys | DEFAULT_REDACT_KEYS | Schlüssel in Attributen und Payload, deren Werte ersetzt werden. Deine Liste ersetzt die Standardwerte; [] schaltet es ab |
captureErrors | true | JavaScript-Fehler, die niemand abgefangen hat |
captureCrashes | true | Native Abstürze |
attachScreen | true | Das Attribut screen auf jedem Event |
attest | true | App Attest und Key Attestation |
mirrorToNativeLog | false | Jedes Event zusätzlich in der Konsole von Xcode oder in logcat ausgeben |
Flush und Stopp
Der Wechsel in den Hintergrund sendet bereits, du brauchst es also selten.
await Lyrelog.flush(); // write everything to disk and try to send now
await Lyrelog.close(); // send what's queued (up to 2 seconds), then stopNach close kann init erneut aufgerufen werden.