React Native
Structured logs, JavaScript errors and crashes from your React Native app, over the Swift and Android SDKs.
The React Native SDK is a thin TurboModule over the Swift and Android SDKs. The native SDKs keep the queue on disk, send in batches, retry, keep sessions and report native crashes. This package adds what only JavaScript sees: uncaught errors, unhandled promise rejections, React render errors and React Navigation screens.
It needs React Native 0.80 or later with the New Architecture, and React 19. Apps run on iOS 16 or later and Android 7.0 (API 24) or later.
Internal preview: this package isn't published yet. Until it is, @lyrelog/react-native isn't
on npm, and the native SDKs it builds on aren't published either.
Install
pnpm add @lyrelog/react-native
cd ios && pod installOn iOS the pod brings the Lyrelog Swift package through Swift Package Manager. Set your app's
deployment target (and the platform :ios line in the Podfile) to 16.0 or later. On Android,
Gradle fetches com.lyrelog:lyrelog-android from Maven Central, which adds the INTERNET
permission.
Start
Start once, as early as possible, in index.js before AppRegistry. A second call keeps the
first configuration. Events logged before init are ignored, but setUser and setConsent
called before init are kept and applied when it runs.
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 go to https://ingest.lyrelog.com. Pass endpoint only to send them somewhere else. It
must be https; plain http works only for localhost, 127.0.0.1 or ::1 (the iOS
simulator), and on the Android emulator for 10.0.2.2.
Nothing in the SDK throws into your app. In a development build, a missing key or a missing
native module (the app wasn't rebuilt after installing) is reported once with console.warn.
Log events
One function per level: trace, debug, info, notice, warning, error, critical, or
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 },
});Attributes are small fields to filter and chart by: strings, numbers, booleans, null, arrays
and nested objects up to 4 levels. The payload is any JSON, for the detail you only read when
you open one event. minimumLevel (default debug) drops lower levels before they cross to
native code.
Loggers for each area
A logger stamps its category on every event. It has every level, plus log and
captureException.
const sync = Lyrelog.logger("sync");
sync.warning("sync_conflict", { attrs: { records: 2 } });Users
Lyrelog.setUser(playerId); // attached to every following event
Lyrelog.setUser(null); // on sign-outLyrelog.sessionId gives the current session id, for example to show in a support screen. The
user id isn't saved between launches: call setUser again on each launch.
Screens
With React Navigation, spread trackNavigation on the 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>
);
}Each screen shown logs screen_viewed (area navigation) with screen, previous_screen and
seconds_on_previous, and every following event is tagged with a screen attribute. The name is
the route's; pass name: (route) => ... to choose another, or return undefined to skip a
route. Your own onReady and onStateChange go in the options and run after Lyrelog's.
Without React Navigation, call Lyrelog.screen("Settings"), or useLyrelogScreen("Settings")
in the screen's component. Calling screen again with the same name logs nothing. Turn the
tagging off with attachScreen: false.
Errors you catch
try {
await store.purchase(product);
} catch (error) {
Lyrelog.captureException(error, { category: "store" });
}It sends the exception event every SDK sends: level error, the attributes error_type and
error_message, and a payload with the name, message, stack and up to 3 causes
(error.cause). attrs adds your own; level changes the level. Anything can be thrown in
JavaScript: a string or an object is recorded too.
Stacks are as Hermes reports them. In a release build they point into the bundle: keep the build's source map to read them.
Errors nobody caught
With captureErrors (on by default), the SDK hooks into React Native's error handling:
| What happens | Event | Level, area | mechanism |
|---|---|---|---|
| A fatal JavaScript error, such as a throw in a timer or an event handler | app_crashed | critical, diagnostics | js_fatal |
| A render error no error boundary caught | app_crashed | critical, diagnostics | react_render |
A non-fatal error reported to ErrorUtils | exception, handled: false | error | js_error |
| An unhandled promise rejection | exception, handled: false | error | unhandled_rejection |
A fatal error is written to disk before the app goes, waiting up to 1.5 seconds, and is sent
then if it can be, otherwise on the next launch. It is app_crashed in the diagnostics area,
like the native crash reports, so JavaScript and native crashes sit together in the dashboard.
Each error is recorded once. Uncaught errors that aren't fatal are capped at 10 a minute, and
the same one at most once every 10 seconds; Lyrelog.skippedErrors counts what was left out.
The handlers that were there before still run: the red box and LogBox in development, the
crash in release.
Error boundaries
import { LyrelogErrorBoundary } from "@lyrelog/react-native";
<LyrelogErrorBoundary
category="feed"
fallback={({ error, reset }) => <Retry onPress={reset} />}
>
<Feed />
</LyrelogErrorBoundary>A render error below it is recorded as exception with mechanism: error_boundary and React's
component stack (component_stack in the payload), and fallback is shown instead. onError
is called after it is recorded. Without a fallback it renders nothing after an error.
Native crashes
These are the native SDKs' (captureCrashes, on by default), sent on the next launch in the
diagnostics area: uncaught JVM exceptions on Android as app_crashed; on iOS MetricKit's
reports, crashes as app_crashed and hangs as app_hung. See
Android crashes and
Swift crashes and hangs.
On Android, a fatal JavaScript error ends the app with a Java exception. Once the JavaScript
app_crashed is on disk, that exception skips the Android SDK's recorder, so the same crash
isn't reported twice.
Environments and platform
The environment is the native SDK's: on iOS development in debug builds, testflight on
TestFlight, production otherwise; on Android development when the app is debuggable,
production otherwise. Your own debug builds send development, while the dashboard opens on
production: pick development in the top bar to see them.
The platform is ios or android. Override either:
Lyrelog.init({
apiKey: key,
environment: isBeta ? "beta" : undefined, // undefined = detected
});Events name this package and the native SDK under it (sdk is
lyrelog-react-native/0.1.0 lyrelog-swift/0.1.0 or lyrelog-react-native/0.1.0 lyrelog-android/0.1.0).
Consent
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 keeps events on the device without sending them. Nothing is uploaded unless consent
is granted. Consent isn't saved between launches: store the person's choice yourself (for
example with AsyncStorage) and pass it to init each time.
Attestation
attest (on by default) proves the app with App Attest on iOS and Key Attestation on Android,
so its events are stored as verified. See Verified events.
Options
| Option | Default | What |
|---|---|---|
apiKey | The project's ingest key, lyr_ing_... | |
endpoint | https://ingest.lyrelog.com | Where events go |
consent | granted | granted, pending or denied |
environment | detected | Any name |
platform | ios / android | Which part of the product sends |
minimumLevel | debug | Lower levels are dropped |
flushIntervalMs | 15000 | How often queued events are sent in the foreground |
sessionTimeoutMs | 30 minutes | A new session after this long without an event |
maxDiskBytes | 20 MB | What may wait on the device; the oldest go first |
redactKeys | DEFAULT_REDACT_KEYS | Attribute and payload keys whose values are replaced. Your list replaces the defaults; [] turns it off |
captureErrors | true | JavaScript errors nobody caught |
captureCrashes | true | Native crashes |
attachScreen | true | The screen attribute on every event |
attest | true | App Attest and Key Attestation |
mirrorToNativeLog | false | Also print every event to the Xcode console or logcat |
Flush and stop
Going to the background already sends, so you rarely need to.
await Lyrelog.flush(); // write everything to disk and try to send now
await Lyrelog.close(); // send what's queued (up to 2 seconds), then stopAfter close, init can be called again.