抢先体验仅限邀请,SDK 尚未发布。申请邀请
跳到正文
文档

SDK

每种语言都是同一套模型。选择你用的语言,或者直接通过 HTTP 发送事件。

Lyrelog 的各个 SDK 共用同一套模型(级别、分类、属性、用户),在语言允许的范围内使用相同的名称,只是按各语言自己的大小写习惯来写。下表列出了它们的不同之处。

应用

SwiftAndroidReact NativeFlutter
启动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: {...})
分类 loggerLyrelog.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 和服务器

JavaScriptPythonGoJVM
启动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 = ...)
分类 loggerclient.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你自己的 recovercaptureUncaught = 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_send hook,可以修改或丢弃任意事件。
  • 定时发送(应用 SDK 每 15 s,Web 和服务器每 5 s),另外在你调用 flush 时、应用进入后台时以及关闭时也会发送。
  • 在入队前让事件符合服务器的限制,因此绝不会发送一行因格式问题而被服务器拒绝的数据。

配置

每个 SDK 都有相同的设置,只是按各语言的命名方式。完整列表见各 SDK 的页面。

应用

设置SwiftAndroidReact NativeFlutter默认值
密钥apiKeyapiKeyapiKeyapiKey必填:采集密钥
Endpointendpointendpointendpointendpointhttps://ingest.lyrelog.com
环境environmentenvironmentenvironmentenvironment自动检测,见环境
平台platformplatformplatformplatform操作系统,见平台
版本取自 bundleappVersion,否则取自包信息取自应用取自应用作为 resource.app_version 发送
应用 id取自 bundle包名bundle id 或包名bundle id 或包名作为 resource.app_id 发送
保留的最低级别minimumLevelminimumLevelminimumLevelminimumLeveldebug
发送间隔uploadIntervalflushIntervalMillisflushIntervalMsflushInterval15 s
队列大小maxDiskBytesmaxDiskBytesmaxDiskBytesmaxDiskBytes磁盘上 20 MB
同意consentconsentconsentconsentgranted
证明应用身份(已验证事件)appAttestattestattestattest开启

Web 和服务器

设置JavaScriptPythonGoJVM默认值
密钥apiKeyapi_keyAPIKeyapiKey必填:浏览器中用采集密钥,服务器上用服务器密钥
EndpointendpointendpointEndpointendpointhttps://ingest.lyrelog.com
环境environmentenvironmentEnvironmentenvironment自动检测,见环境
平台platformplatformPlatformplatform自动检测,见平台
版本releasereleaseReleaserelease,否则取自 jar 的 manifest作为 resource.app_version 发送
应用 idappIdapp_idAppIDappId,否则取自 jar 的 manifest作为 resource.app_id 发送
保留的最低级别minimumLevelminimum_levelMinimumLevelminimumLeveldebug
发送间隔flushIntervalMsflush_intervalFlushIntervalflushIntervalMillis5 s
队列大小maxQueuemax_queueMaxQueuemaxDiskBytes内存中 10,000 个事件;JVM 上为磁盘上 20 MB
同意consentgranted(浏览器)

在 JavaScript 和 Go 列中,实例名为 client(JavaScript 示例中为 log);其他 SDK 通过 Lyrelog 或 lyrelog 模块记录日志。计数器也按各语言命名:JavaScript 和 Python 计 delivered,Go 计 Sent。

事件没有出现时

  1. 检查环境。 控制台默认打开 production。Swift 在 Xcode 和模拟器中发送 development,Android 的所有 debug 构建也是如此,React Native 和 Flutter 应用则跟随其底层的原生 SDK。JavaScript 在 localhost 上发送 development,在 Node 上只要 NODE_ENV 不是 production(包括未设置时)也是如此。在顶部栏中选择对应的环境,或选择 All environments。
  2. 查看 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:lyrelog logger。Go:Config.ErrorLog;没有设置时,第一个问题会向 stderr 打印一次。JVM:标准错误输出中以 lyrelog: 开头的行,或 Configuration.diagnostics。它们会告诉你密钥是否被拒绝、endpoint 是否写错、是否有批次被丢弃。
  3. 让进程在结束前把事件发出去。 短脚本、serverless 函数以及调用 exit 的进程,必须先立即发送(flush)或关闭客户端。JVM SDK 的 shutdown hook 会在正常退出时完成这一步,但 serverless handler 仍然需要手动立即发送。详见各 SDK 的页面。
  4. 检查同意状态和级别。 同意状态为 pending 时什么都不会发送。低于保留的最低级别的事件永远不会入队。
  5. 检查密钥。 收到 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 也一样。