事件
一个事件就是发生过的一件事,带有稳定的名称、级别、分类,以及用于筛选的字段。
Lyrelog 中的一切都是事件。一个事件说明发生了什么(message)、有多严重(level)、发生在应用的哪个部分
(category)、发生在谁身上(user_id、session_id、install_id),并带有一些用来筛选和绘图的小字段
(attrs),必要时还可以附带一块只在打开事件时才读取的较大数据(payload)。
{
"event_id": "6f1b2c3d-5a1e-4c1f-9e7a-0a1b2c3d4e5f",
"ts": "2026-11-18T10:00:00.123Z",
"level": "error",
"category": "checkout",
"message": "payment_declined",
"user_id": "user-1",
"attrs": { "code": 51, "attempt": 2, "method": "card" },
"payload": { "response": "..." }
}message 是一个稳定的名称
把 message 写成事件名,而不是一句话:payment_declined、checkout_done、http_request_failed。
名称始终不变,才能用来计数、绘图、做漏斗分析,以及归并为错误。会变化的内容(id、耗时、错误码)放进 attrs。
| 推荐 | 不推荐 |
|---|---|
payment_declined,并带上 attrs: { code: 51 } | "Payment declined with code 51 for user-1" |
message 最长 2,048 字节。
级别
从最低到最高:trace、debug、info(默认)、notice、warning、error、critical。
控制台为每个级别着色,在 Explorer 图表中把错误画在坐标轴下方,并在 Errors 页面中把
error 和 critical 事件归组。
SDK 会在入队之前丢弃低于 minimumLevel(默认 debug)的事件。
Category:事件所属的应用分类
category(在控制台中显示为 Area)是事件所属的应用部分:checkout、sync、onboarding、network。
它的作用类似 OSLog 的 category。控制台按它筛选和计数。可选,最长 64 字节。每个 SDK 都为每个分类提供一个 logger,
这样你就不必反复填写它。
属性与 payload
attrs | payload | |
|---|---|---|
| 用途 | 用于筛选、分组和绘图的字段 | 打开单个事件时才阅读的细节 |
| 示例 | id、耗时、状态码、标志位 | 服务器响应、堆栈跟踪 |
| 可筛选 | 是,按路径和值筛选(attr=payment.method:card) | 否(压缩存储) |
| 限制 | 最多 200 个叶子节点,字符串最长 1,024 字节,字符串数组最多 64 项,对象最多嵌套 4 层 | 任意 JSON,序列化后不超过 64 KiB |
属性值可以是字符串、数字、布尔值、null、字符串数组和嵌套对象。名称不能包含点号(请改用嵌套对象),也不能以 _ 开头。
数字要按数字记录(latency_ms: 412,而不是 "412"):这样 Insights
才能绘制它们的平均值、中位数或 p95。
SDK 会在每个事件入队之前把它裁剪到这些限制以内:过长的字符串在字符边界处截断,超大的 payload 会被替换为
{"lyrelog_truncated": true, "bytes": N, "preview": "..."},其中 preview 是 payload 的开头部分。
上下文
每个事件还带有一个 resource:应用 id、版本和构建号、操作系统及其版本、设备型号、区域设置、SDK、
环境以及平台。这些由 SDK 替你填写。服务器会再加上
国家。
Id 与重复事件
每个事件都有一个 event_id,即记录时生成一次的 UUID。投递语义是至少一次:如果一个批次被发送了两次,
event_id 和 ts 都相同的事件只会存储一次。