React Native
从你的 React Native 应用收集结构化日志、JavaScript 错误和崩溃,基于 Swift 和 Android SDK。
React Native SDK 是构建在 Swift 和 Android SDK 之上的一层轻量 TurboModule。原生 SDK 负责把队列保存在磁盘上、批量发送、重试、维护会话以及上报原生崩溃。这个包补上只有 JavaScript 才能看到的部分:未捕获的错误、未处理的 promise 拒绝、React 渲染错误以及 React Navigation 的页面。
它需要启用了新架构(New Architecture)的 React Native 0.80 或更高版本,以及 React 19。应用需运行在 iOS 16 或更高版本、Android 7.0(API 24)或更高版本上。
内部预览:这个包还没有发布。在发布之前,npm 上没有 @lyrelog/react-native,它所依赖的原生 SDK 也都还没有发布。
安装
pnpm add @lyrelog/react-native
cd ios && pod install在 iOS 上,这个 pod 会通过 Swift Package Manager 引入 Swift 包 Lyrelog。请把应用的 deployment target(以及 Podfile 中的 platform :ios 一行)设为 16.0 或更高。在 Android 上,Gradle 会从 Maven Central 拉取 com.lyrelog:lyrelog-android,该依赖会添加 INTERNET 权限。
启动
只启动一次,越早越好,放在 index.js 中 AppRegistry 之前。第二次调用会保留第一次的配置。在 init 之前记录的事件会被忽略,但在 init 之前调用的 setUser 和 setConsent 会被保留,并在启动时生效。
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);事件发送到 https://ingest.lyrelog.com。只有要发送到其他地方时才需要传 endpoint。它必须是 https;普通 http 只适用于 localhost、127.0.0.1 或 ::1(iOS 模拟器),以及 Android 模拟器上的 10.0.2.2。
SDK 不会向你的应用抛出任何异常。在开发构建中,缺少密钥或缺少原生模块(安装后没有重新构建应用)时,会用 console.warn 报告一次。
记录事件
每个级别一个函数:trace、debug、info、notice、warning、error、critical,或者 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 },
});属性是用于筛选和绘制图表的小字段:字符串、数字、布尔值、null、数组以及最多 4 层的嵌套对象。payload 可以是任意 JSON,用来放那些只有打开单个事件时才会看的细节。minimumLevel(默认 debug)会在跨越到原生代码之前丢弃更低级别的事件。
按分类使用 logger
logger 会在每个事件上打上它的 category。它有所有级别,外加 log 和 captureException。
const sync = Lyrelog.logger("sync");
sync.warning("sync_conflict", { attrs: { records: 2 } });用户
Lyrelog.setUser(playerId); // attached to every following event
Lyrelog.setUser(null); // on sign-outLyrelog.sessionId 返回当前的会话 id,例如可以显示在客服支持页面上。用户 id 不会在两次启动之间保存:每次启动时再调用一次 setUser。
页面
使用 React Navigation 时,把 trackNavigation 展开到容器上:
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>
);
}每显示一个页面都会记录 screen_viewed(分类 navigation),带有 screen、previous_screen 和 seconds_on_previous,之后的每个事件都会打上 screen 属性。名称取自路由;传入 name: (route) => ... 可以换成别的名称,返回 undefined 则跳过该路由。你自己的 onReady 和 onStateChange 放在选项里,会在 Lyrelog 的之后运行。
不使用 React Navigation 时,调用 Lyrelog.screen("Settings"),或在页面组件中调用 useLyrelogScreen("Settings")。用相同的名字再次调用 screen 不会记录任何内容。用 attachScreen: false 可以关闭这种标记。
你捕获的错误
try {
await store.purchase(product);
} catch (error) {
Lyrelog.captureException(error, { category: "store" });
}它发送的是每个 SDK 都会发送的 exception 事件:级别为 error,带有属性 error_type 和 error_message,payload 中包含名称、消息、调用栈以及最多 3 层 cause(error.cause)。attrs 用于添加你自己的属性;level 用于修改级别。JavaScript 可以抛出任何值:字符串或对象也同样会被记录。
调用栈保持 Hermes 报告的原样。在 release 构建中,它们指向打包后的 bundle:请保留该构建的 source map 以便解读。
没人捕获的错误
开启 captureErrors(默认开启)时,SDK 会接入 React Native 的错误处理:
| 发生了什么 | 事件 | 级别、分类 | mechanism |
|---|---|---|---|
| JavaScript 致命错误,例如在定时器或事件处理函数中抛出 | app_crashed | critical、diagnostics | js_fatal |
| 没有被任何 error boundary 捕获的渲染错误 | app_crashed | critical、diagnostics | react_render |
报告给 ErrorUtils 的非致命错误 | exception、handled: false | error | js_error |
| 未处理的 promise 拒绝 | exception、handled: false | error | unhandled_rejection |
致命错误会在应用退出前写入磁盘(最多等待 1.5 秒),能发送时当场发送,否则在下次启动时发送。它是 diagnostics 分类中的 app_crashed,与原生崩溃报告一样,所以 JavaScript 崩溃和原生崩溃会并列显示在控制台中。
每个错误只记录一次。非致命的未捕获错误每分钟最多记录 10 个,同一个错误每 10 秒最多记录一次;Lyrelog.skippedErrors 统计被略过的数量。原有的 handler 仍会运行:开发时的红屏和 LogBox,release 中的崩溃。
Error boundary
import { LyrelogErrorBoundary } from "@lyrelog/react-native";
<LyrelogErrorBoundary
category="feed"
fallback={({ error, reset }) => <Retry onPress={reset} />}
>
<Feed />
</LyrelogErrorBoundary>其子树中的渲染错误会被记录为 exception,带有 mechanism: error_boundary 和 React 的组件栈(payload 中的 component_stack),同时改为显示 fallback。onError 会在记录之后被调用。没有 fallback 时,出错后它什么都不渲染。
原生崩溃
这部分由原生 SDK 负责(captureCrashes,默认开启),在下次启动时发送,位于 diagnostics 分类:Android 上未捕获的 JVM 异常记为 app_crashed;iOS 上来自 MetricKit 的报告,崩溃记为 app_crashed,卡顿记为 app_hung。见 Android 崩溃和 Swift 崩溃和卡顿。
在 Android 上,JavaScript 致命错误会以一个 Java 异常结束应用。一旦 JavaScript 的 app_crashed 已写入磁盘,这个异常就会绕过 Android SDK 的记录器,因此同一次崩溃不会被报告两次。
环境和平台
环境由原生 SDK 决定:iOS 上 debug 构建为 development,TestFlight 上为 testflight,其他情况为 production;Android 上应用可调试时为 development,其他情况为 production。你自己的 debug 构建发送的是 development,而控制台默认打开 production:在顶部栏选择 development 才能看到它们。
平台为 ios 或 android。两者都可以覆盖:
Lyrelog.init({
apiKey: key,
environment: isBeta ? "beta" : undefined, // undefined = detected
});事件会注明这个包以及它底层的原生 SDK(sdk 为
lyrelog-react-native/0.1.0 lyrelog-swift/0.1.0 或 lyrelog-react-native/0.1.0 lyrelog-android/0.1.0)。
同意
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 会把事件保留在设备上而不发送。除非已获得同意,否则什么都不会上传。同意状态不会在两次启动之间保存:请自己保存用户的选择(例如用 AsyncStorage),并在每次调用 init 时传入。
Attestation
attest(默认开启)在 iOS 上用 App Attest、在 Android 上用 Key Attestation 证明应用身份,这样它的事件会被保存为已验证事件。见已验证事件。
选项
| 选项 | 默认值 | 说明 |
|---|---|---|
apiKey | 项目的采集密钥,lyr_ing_... | |
endpoint | https://ingest.lyrelog.com | 事件发送到哪里 |
consent | granted | granted、pending 或 denied |
environment | 自动检测 | 任何名称 |
platform | ios / android | 由产品的哪一部分发送 |
minimumLevel | debug | 更低的级别会被丢弃 |
flushIntervalMs | 15000 | 前台时多久发送一次队列中的事件 |
sessionTimeoutMs | 30 分钟 | 超过这么久没有事件,就开始新会话 |
maxDiskBytes | 20 MB | 设备上最多可以等待多少数据;最旧的先丢弃 |
redactKeys | DEFAULT_REDACT_KEYS | 值会被替换的属性和 payload 键名。你的列表会替换默认值;[] 则关闭脱敏 |
captureErrors | true | 没人捕获的 JavaScript 错误 |
captureCrashes | true | 原生崩溃 |
attachScreen | true | 每个事件上的 screen 属性 |
attest | true | App Attest 和 Key Attestation |
mirrorToNativeLog | false | 同时把每个事件打印到 Xcode 的 console 或 logcat |
立即发送(flush)和停止
进入后台时已经会自动发送,所以你很少需要手动立即发送。
await Lyrelog.flush(); // write everything to disk and try to send now
await Lyrelog.close(); // send what's queued (up to 2 seconds), then stop调用 close 之后,可以再次调用 init。