SDK
每种语言都是同一套模型。选择你用的语言,或者直接通过 HTTP 发送事件。
Lyrelog 的各个 SDK 共用同一套模型(级别、分类、属性、用户),在语言允许的范围内使用相同的名称,只是按各语言自己的大小写习惯来写。下表列出了它们的不同之处。
应用
Web 与服务器
应用
| Swift | Android | React Native | Flutter | |
|---|---|---|---|---|
| 启动 | Lyrelog.start(Configuration(...)) | Lyrelog.start(context, Configuration(...)) | Lyrelog.init({...}) | Lyrelog.start(LyrelogConfiguration(...)) |
| 记录日志 | Lyrelog.info("checkout_done", attrs:) | Lyrelog.info("checkout_done", attrs = ...) | Lyrelog.info("checkout_done", { attrs }) | Lyrelog.info('checkout_done', attrs: {...}) |
| 分类 logger | Lyrelog.Logger(category: "checkout") | Lyrelog.logger("checkout") | Lyrelog.logger("checkout") | Lyrelog.logger('checkout') |
| 用户 | Lyrelog.setUser("u_123") | Lyrelog.setUser("u_123") | Lyrelog.setUser("u_123") | Lyrelog.setUser('u_123') |
| 页面 | Lyrelog.screen("Settings") | Lyrelog.screen("Settings") | trackNavigation(ref),或 Lyrelog.screen("Settings") | LyrelogNavigatorObserver(),或 Lyrelog.screen('Settings') |
| 网络请求 | session.loggedData(for:) | |||
| 捕获错误 | Lyrelog.captureError(error) | Lyrelog.captureError(e) | Lyrelog.captureException(error) | Lyrelog.captureError(e, stackTrace: s) |
| 未捕获的错误和崩溃 | MetricKit 报告的崩溃和卡顿,自动 | 未捕获的异常,自动,下次启动时发送 | JavaScript 致命错误和渲染错误记为崩溃,Promise 拒绝和其他错误也会记录,外加原生崩溃;自动 | Dart 错误(FlutterError、PlatformDispatcher),外加原生崩溃;自动 |
| 立即发送(flush) | await Lyrelog.flush() | Lyrelog.flush()(不要在主线程调用) | await Lyrelog.flush() | await Lyrelog.flush() |
| 停止 | await Lyrelog.stop() | Lyrelog.stop() | await Lyrelog.close() | await Lyrelog.stop() |
Web 和服务器
| JavaScript | Python | Go | JVM | |
|---|---|---|---|---|
| 启动 | Lyrelog.init({...}) | lyrelog.init(...) | lyrelog.New(lyrelog.Config{...}) | Lyrelog.start(Configuration(...)) |
| 记录日志 | client.info("checkout_done", { attrs }) | lyrelog.info("checkout_done", attrs=) | client.Info("checkout_done", lyrelog.Attrs{}) | Lyrelog.info("checkout_done", attrs = ...) |
| 分类 logger | client.logger("checkout") | lyrelog.logger("checkout") | client.Logger("checkout") | Lyrelog.logger("checkout") |
| 用户 | client.setUser("u_123") | lyrelog.set_user("u_123") | client.SetUser("u_123") | Lyrelog.setUser("u_123"),或用 Lyrelog.userScope(id) 只作用于一个线程 |
| 页面 | client.screen("Settings") | |||
| 捕获错误 | client.captureException(err) | lyrelog.capture_exception(exc) | client.CaptureError(err) | Lyrelog.captureError(e) |
| 未捕获的错误和崩溃 | window 和 Node,自动 | 你自己的 sys.excepthook | 你自己的 recover | captureUncaught = true(默认关闭) |
| 立即发送(flush) | await client.flush() | lyrelog.flush() | client.Flush(ctx) | Lyrelog.flush() |
| 停止 | await client.close() | lyrelog.shutdown() | client.Close() | Lyrelog.close()(退出时由 shutdown hook 完成) |
| 标准日志库 | lyrelog.LoggingHandler() | lyrelog.NewSlogHandler(client, nil) | 用于 Logback 的 LyrelogAppender |
应用 SDK 还可以把每个事件同时输出到平台自带的日志里,这样在 Xcode 和 logcat 中也能看到:Swift 中是 mirrorToOSLog,Android 上是 mirrorToLogcat,React Native 中是 mirrorToNativeLog,Flutter 中是 mirrorToConsole。
内部预览
这些 SDK 都还没有发布,所以目前这些页面上的安装命令都会失败:pnpm add、flutter pub add 和 uv add 找不到包,Gradle 和 Maven 在 Maven Central 上什么也找不到,Swift Package Manager 和 go get 无法访问私有仓库。每个页面展示的是 SDK 发布之后的写法。
每个 SDK 都会替你做的事
React Native 和 Flutter SDK 在 iOS 上通过 Swift SDK 发送,在 Android 上通过 Android SDK 发送,所以下面列出的一切它们也都具备,并且以原生方式完成。JVM SDK 运行的是 Android SDK 的引擎,只是针对服务器做了配置。
- **绝不会阻塞你的代码,也不会抛出异常。**记录日志只是把事件复制到队列中就返回;由后台 worker 负责发送。
- 批量发送,每个请求最多 500 个事件或约 512 KiB,每个事件一行 NDJSON,平台支持时用 gzip 压缩。
- 发送到
https://ingest.lyrelog.com,除非你设置了其他endpoint。endpoint 是基础 URL:如果你粘贴了完整的.../v1/events:batch地址,SDK 会去掉路径部分。endpoint 写错时(返回404或重定向),SDK 会在自己的日志里给出警告。 - 重试临时失败(
408、425、429、5xx、网络错误),采用指数退避(从 1 s 开始翻倍,最长 5 min)加随机抖动,遵守Retry-After,在你调用flush或关闭客户端时也是如此。除 Python 外,所有 SDK 都使用 full jitter(在 0 到上限之间随机等待);Python 使用 equal jitter(在上限的一半到上限之间)。 - **丢弃被拒绝的批次。**其他任何 4xx(
400、413、415...)都表示批次本身有问题,所以会被丢弃而不是重发。密钥被拒绝(401、403)时,在应用或进程重启之前停止发送,但保留事件。永远不跟随重定向:3xx 响应意味着 endpoint 写错了,所以会丢弃该批次并记录一条警告。 - 遇到
429时保留事件。 当 Free 组织用完了当月的事件数,或项目超出了速率限制时,SDK 会保留批次,在Retry-After之后再试(见 HTTP API)。应用 SDK(Swift、Android、React Native、Flutter)把它们保存在磁盘上,跨启动保留。JVM SDK 也保存在磁盘上,除非你提供storageDirectory,否则放在该进程的临时目录中。JavaScript、Python 和 Go 把它们保存在内存中。无论哪种方式,下面的上限都适用。 - 限制等待中的事件量:JavaScript、Python 和 Go 默认在内存中最多 10,000 个事件、16 MiB;应用 SDK 和 JVM 在磁盘上最多 20 MB、7 天。最旧的事件会先被丢弃。
- 对敏感信息脱敏,每个 SDK 的做法都一样。字段名转为小写并去掉
-、_、.和空格后,如果等于或以authorization、cookie、password、passwd、secret、token、apikey、privatekey、credential(s)、accesskey或signature结尾,它的值就会变成"[redacted]"。所以X-Api-Key、csrf_token和Set-Cookie会被脱敏,而token_count和max_tokens不会。这在属性和 payload 的任意深度生效,并且发生在任何截断之前,因此敏感信息绝不会残留在截短的字符串或 payload 的预览里。只检查字段名:message 或错误文本里的敏感信息会原样发送。可以用redactedKeys(Swift、Android、Flutter、JVM)、redactKeys(JavaScript、React Native)、redact_keys(Python)或RedactKeys(Go)修改这个列表:你的列表会替换默认列表,传空列表则关闭脱敏。要在默认列表上追加,请扩展导出的默认值:Swift 中是Configuration.defaultRedactedKeys,Android 和 JVM 上是Configuration.DEFAULT_REDACTED_KEYS,Flutter 中是LyrelogConfiguration.defaultRedactedKeys,JavaScript、React Native 和 Python 中是DEFAULT_REDACT_KEYS,Go 中是DefaultRedactKeys()。JavaScript 和 Python SDK 还接受beforeSend/before_sendhook,可以修改或丢弃任意事件。 - 定时发送(应用 SDK 每 15 s,Web 和服务器每 5 s),另外在你调用
flush时、应用进入后台时以及关闭时也会发送。 - 在入队前让事件符合服务器的限制,因此绝不会发送一行因格式问题而被服务器拒绝的数据。
配置
每个 SDK 都有相同的设置,只是按各语言的命名方式。完整列表见各 SDK 的页面。
应用
| 设置 | Swift | Android | React Native | Flutter | 默认值 |
|---|---|---|---|---|---|
| 密钥 | apiKey | apiKey | apiKey | apiKey | 必填:采集密钥 |
| Endpoint | endpoint | endpoint | endpoint | endpoint | https://ingest.lyrelog.com |
| 环境 | environment | environment | environment | environment | 自动检测,见环境 |
| 平台 | platform | platform | platform | platform | 操作系统,见平台 |
| 版本 | 取自 bundle | appVersion,否则取自包信息 | 取自应用 | 取自应用 | 作为 resource.app_version 发送 |
| 应用 id | 取自 bundle | 包名 | bundle id 或包名 | bundle id 或包名 | 作为 resource.app_id 发送 |
| 保留的最低级别 | minimumLevel | minimumLevel | minimumLevel | minimumLevel | debug |
| 发送间隔 | uploadInterval | flushIntervalMillis | flushIntervalMs | flushInterval | 15 s |
| 队列大小 | maxDiskBytes | maxDiskBytes | maxDiskBytes | maxDiskBytes | 磁盘上 20 MB |
| 同意 | consent | consent | consent | consent | granted |
| 证明应用身份(已验证事件) | appAttest | attest | attest | attest | 开启 |
Web 和服务器
| 设置 | JavaScript | Python | Go | JVM | 默认值 |
|---|---|---|---|---|---|
| 密钥 | apiKey | api_key | APIKey | apiKey | 必填:浏览器中用采集密钥,服务器上用服务器密钥 |
| Endpoint | endpoint | endpoint | Endpoint | endpoint | https://ingest.lyrelog.com |
| 环境 | environment | environment | Environment | environment | 自动检测,见环境 |
| 平台 | platform | platform | Platform | platform | 自动检测,见平台 |
| 版本 | release | release | Release | release,否则取自 jar 的 manifest | 作为 resource.app_version 发送 |
| 应用 id | appId | app_id | AppID | appId,否则取自 jar 的 manifest | 作为 resource.app_id 发送 |
| 保留的最低级别 | minimumLevel | minimum_level | MinimumLevel | minimumLevel | debug |
| 发送间隔 | flushIntervalMs | flush_interval | FlushInterval | flushIntervalMillis | 5 s |
| 队列大小 | maxQueue | max_queue | MaxQueue | maxDiskBytes | 内存中 10,000 个事件;JVM 上为磁盘上 20 MB |
| 同意 | consent | granted(浏览器) |
在 JavaScript 和 Go 列中,实例名为 client(JavaScript 示例中为 log);其他 SDK 通过 Lyrelog 或 lyrelog 模块记录日志。计数器也按各语言命名:JavaScript 和 Python 计 delivered,Go 计 Sent。
事件没有出现时
- 检查环境。 控制台默认打开
production。Swift 在 Xcode 和模拟器中发送development,Android 的所有 debug 构建也是如此,React Native 和 Flutter 应用则跟随其底层的原生 SDK。JavaScript 在localhost上发送development,在 Node 上只要NODE_ENV不是production(包括未设置时)也是如此。在顶部栏中选择对应的环境,或选择 All environments。 - 查看 SDK 自己的消息。 Swift:统一日志,subsystem 为
com.lyrelog.sdk,debug 级别(在 Console 应用中打开 Include Debug Messages)。Android:logcat,tag 为Lyrelog,debug 级别。React Native 和 Flutter:看原生 SDK 的消息,位置同上;React Native 在开发构建中,如果缺少密钥或原生模块,还会在 Metro 中警告一次。JavaScript:以[lyrelog]开头的 console 输出。Python:lyreloglogger。Go:Config.ErrorLog;没有设置时,第一个问题会向 stderr 打印一次。JVM:标准错误输出中以lyrelog:开头的行,或Configuration.diagnostics。它们会告诉你密钥是否被拒绝、endpoint 是否写错、是否有批次被丢弃。 - 让进程在结束前把事件发出去。 短脚本、serverless 函数以及调用
exit的进程,必须先立即发送(flush)或关闭客户端。JVM SDK 的 shutdown hook 会在正常退出时完成这一步,但 serverless handler 仍然需要手动立即发送。详见各 SDK 的页面。 - 检查同意状态和级别。 同意状态为
pending时什么都不会发送。低于保留的最低级别的事件永远不会入队。 - 检查密钥。 收到
401或403后,在应用或进程重启之前不会再发送任何内容。密钥为空时什么都不会发送(在 Go 中,New返回错误;在 JVM 上,start返回false)。
不要发送什么
message 用来放稳定的事件名,绝不要放含有个人数据的文本。用你自己的 id 标识用户(setUser、user_id),而不是电子邮件地址。不要把 token、密码以及带 header 的完整请求或响应体放进属性和 payload。脱敏只是针对它已知字段名的一道安全网,不是可以依赖的过滤器。
开发和测试中
- Swift: 不要在测试中调用
Lyrelog.start。在start之前记录的任何内容都会被忽略。 - Android: 同样,不要在单元测试中调用
Lyrelog.start。debug 构建发送development;要从模拟器访问你电脑上的 endpoint,需要做一些设置,见开发和测试中。 - React Native: 不要在测试中调用
Lyrelog.init:init之前的调用都会被忽略。debug 构建发送development。 - Flutter: 不要在 widget 测试和单元测试中调用
Lyrelog.start:在start之前记录的任何内容都会被忽略。在插件不支持的平台(Web、桌面)上,所有调用都不做任何事。见开发和测试中。 - JavaScript: 把
apiKey留空,客户端会警告一次并且什么都不发送;或者传入consent: "denied"。 - Python:
api_key为空时,得到的客户端会接受事件但什么都不发送。 - Go: 没有
APIKey时New返回错误,而nil的*Client什么都不做,所以没有密钥时同一套代码也能照常运行。 - JVM: 不提供密钥即可:
start返回false,所有调用都不做任何事,Logback appender 也一样。