读取 API
用只读密钥在脚本中查询项目的事件。
控制台是读取事件的一种方式,读取 API 是另一种:同样的筛选条件,以 JSON 形式提供给脚本、notebook、定时任务或 agent。
认证
在项目的 API keys 页面中选择 New key,并把 What it can do 设为 Read events。这个密钥以
lyr_read_ 开头,只显示一次。把它作为 bearer token 发送到 https://app.lyrelog.com。下面的示例把它保存在一个 shell 变量中:
export LYRELOG_READ_KEY=lyr_read_...
curl -s https://app.lyrelog.com/v1/events \
-H "Authorization: Bearer $LYRELOG_READ_KEY"只读密钥能看到所属项目的每一个事件,此外什么也看不到。请把它放在服务器上:任何拿到它的人都能读取你的用户事件。
Full access 密钥也可以读取;采集密钥不行(403)。
列出事件
GET /v1/events 按从新到旧返回事件,每次 100 个;如果不另行指定,时间范围是最近 24 小时。
| 参数 | 含义 |
|---|---|
from、to | Unix 毫秒时间戳。默认:最近 24 小时。 |
level | 一个或多个级别,用逗号分隔:error,critical |
category、message | 分类和事件名。多个值用 | 分隔,前面加 ! 表示排除:message=!http_request_served |
user、session、install | 一个 id |
env、platform | production、ios……不指定时包含所有环境和平台。 |
version、os、device、locale | 应用版本、操作系统版本(27.2.0)、设备型号和区域设置 |
country | 用户所在地:事件来源地址所在的国家,没有时取设备区域设置中的地区(es_ES 即 ES) |
verified | 事件如何被验证:server(用服务器密钥发送)、app_attest(由你的 Apple 应用发送并经 App Attest 证明)、key_attestation(由你的 Android 应用发送并经 Key Attestation 证明)、none(未验证) |
attr | 对某个属性使用 path:value,或用 path!:value 排除。需要多个时重复该参数。 |
q | 事件名(message)或分类中的文本(不区分大小写),或者精确的事件、用户、会话或安装 id。不搜索属性:请用 attr。 |
limit | 1 到 1000,默认 100 |
order | asc 表示从旧到新 |
cursor | 上一次响应中的 next_cursor,用于获取下一页 |
category、message、user、session、install、env、platform、version、os、
device、locale、country 和 verified 可以接受用 | 分隔的多个值(“是其中任意一个”),或者前面加 ! 的列表
(“不是”):os=26.4|27.2.0、platform=!web。attr 的值同样可以用 |,排除时把 ! 放在路径之后:
attr=plan!:free|trial。设备型号中含有逗号(iPhone18,1),所以分隔符用的是 |。
# Errors on iOS in production in the last hour
curl -s -G https://app.lyrelog.com/v1/events \
-H "Authorization: Bearer $LYRELOG_READ_KEY" \
--data-urlencode "level=error,critical" \
--data-urlencode "platform=ios" \
--data-urlencode "env=production" \
--data-urlencode "from=$(( ($(date +%s) - 3600) * 1000 ))"响应为 {"events": [...], "next_cursor": "..."};在最后一页,next_cursor 为 null。
每个事件都包含 event_id、ts(Unix 毫秒时间戳)、level、category、message、user_id、
install_id、session_id 和 attrs,以及 resource 字段(app_id、app_version、
app_build、os_name、os_version、device_model、locale、environment、platform),
还有 country 和 verified_by:事件用服务器密钥发送时为 "server",你的 Apple 应用通过 App Attest 证明了自己时为
"app_attest",你的 Android 应用通过 Key Attestation 证明了自己时为 "key_attestation",未验证时为 ""(参见已验证事件)。列表中不包含 payload:
要获取它,请单独请求该事件。
读取所有页
cursor 只对生成它的那个查询有效:翻页时要带上相同的筛选条件。不指定 from 和 to 时,时间窗口会随时钟移动,
所以读取多页时请把它们固定下来。下面的脚本读取最近 7 天的所有错误,从旧到新,每次 1000 个(需要 jq):
FROM=$(( ($(date +%s) - 7*86400) * 1000 )); TO=$(( $(date +%s) * 1000 )); CURSOR=""
while :; do
PAGE=$(curl -s -G https://app.lyrelog.com/v1/events \
-H "Authorization: Bearer $LYRELOG_READ_KEY" \
--data-urlencode "level=error,critical" --data-urlencode "order=asc" --data-urlencode "limit=1000" \
--data-urlencode "from=$FROM" --data-urlencode "to=$TO" ${CURSOR:+--data-urlencode "cursor=$CURSOR"})
echo "$PAGE" | jq -c '.events[]'
CURSOR=$(echo "$PAGE" | jq -r '.next_cursor // empty'); [ -z "$CURSOR" ] && break
done单个事件
GET /v1/events/{event_id}?ts={ts} 返回单个事件及其完整的 payload,格式为 {"event": {...}}。
请传入列表给出的 ts(Unix 毫秒时间戳):事件按时间存储,只凭 id 就得搜索全部事件。
curl -s -G "https://app.lyrelog.com/v1/events/6f1b2c3d-5a1e-4c1f-9e7a-0a1b2c3d4e5f" \
-H "Authorization: Bearer $LYRELOG_READ_KEY" \
--data-urlencode "ts=1794996000123"{"event":{"event_id":"6f1b2c3d-5a1e-4c1f-9e7a-0a1b2c3d4e5f","ts":1794996000123,"level":"error","category":"checkout","message":"payment_declined","user_id":"user-1","install_id":"","session_id":"2f9a...","app_id":"com.example.app","app_version":"2.0","app_build":"202611181200","os_name":"iOS","os_version":"27.2.0","device_model":"iPhone18,1","locale":"es_ES","country":"ES","environment":"production","platform":"ios","verified_by":"","attrs":{"code":51},"payload":{"response":"..."}}}应用没有发送的字段为空字符串。事件没有 payload 时,响应中不包含 payload。
限制与错误
| 状态码 | 含义 |
|---|---|
400 | 某个参数有误,响应体会指出是哪个。例如:from 不早于 to、时间范围超过 400 天、attr 筛选超过 8 个、单个筛选超过 100 个值、未知的级别、limit 不在 1 到 1000 之间、无效的 cursor |
401 | 没有密钥,或者密钥未知或已吊销 |
403 | 该密钥无法读取(采集密钥) |
404 | 没有该 id 和 ts 对应的事件 |
429 | 该密钥每分钟请求超过 120 次(Retry-After: 60);项目已经有 4 个查询在同时运行,控制台和它的密钥合并计算(Retry-After: 2);或者 15 分钟内来自你的地址的未知密钥超过 60 个 |
500 | {"error":"something went wrong on the server"}。耗时超过 15 秒的查询会以这种方式结束:请缩小时间范围或添加筛选条件 |
出错时响应为 {"error": "..."}。收到 429 后,请等待 Retry-After 指定的时间再重试。
响应从不缓存(Cache-Control: no-store)。API 特意不提供 CORS header:只读密钥不应该出现在浏览器中。