HTTP API
不用 SDK 也能发送事件。采集 endpoint、每个字段和限制,以及客户端该如何处理每种响应。
SDK 用的就是这个 API,任何能发 HTTP 请求的程序也都可以用。本页与某个 SDK 的说法不一致时,以本页为准。
Endpoint
POST https://ingest.lyrelog.com/v1/events:batch| Header | 值 |
|---|---|
Authorization | Bearer lyr_ing_...(采集密钥)、Bearer lyr_srv_...(服务器密钥),或完全访问密钥 |
Content-Type | application/x-ndjson(application/jsonl 也可以) |
Content-Encoding | gzip(可选,推荐),纯文本则用 identity 或不填 |
X-Lyrelog-Attestation | 可选。使用采集密钥的 Apple 或 Android 应用提供的 token(见 Apple App Attest 和 Android Key Attestation) |
只读密钥不能发送事件,会收到 403。在服务器上请使用服务器密钥:它发送的事件是已验证的,而且不受单个发送地址每日配额的限制。应用和网页使用采集密钥;Apple 应用的事件可以通过 App Attest 验证,Android 应用的事件可以通过 Key Attestation 验证。
请求体:NDJSON
每行一个 JSON 对象,每个事件一行。
- 每个请求至少一个事件,最多 2,000 行。请求体为空或行数超出时,整个批次返回
400。 - 传输时最多 4 MiB,解压后最多 4 MiB,单行最多 1 MiB(超长的行会被单独拒绝)。
- 空行会被忽略,但仍计入行号(这样错误指向的行号才准确)。
{"event_id":"6f1b2c3d-5a1e-4c1f-9e7a-0a1b2c3d4e5f","ts":"2026-11-18T10:00:00.123Z","level":"info","category":"checkout","message":"checkout_done","user_id":"user-1","install_id":"8c1d...","session_id":"2f9a...","attrs":{"items":3,"latency_ms":412,"payment":{"method":"card"},"tags":["a","b"]},"payload":{"response":"..."},"resource":{"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","sdk":"lyrelog-swift/0.1.0","environment":"production","platform":"ios"}}字段
| 字段 | 必填 | 规则 |
|---|---|---|
event_id | 是 | 每个事件生成一次的 UUID。id 和 ts 都相同的重发会被合并。同一批次中同一个 id 出现两次,第二行会被拒绝。 |
ts | 是 | 带时区的 RFC 3339。比服务器时间最多超前一天时,按发送的值保存。超前超过一天,或早于项目的保留期限时,事件按到达时间保存,发送时的时间写入属性 _lyrelog_ts_clamped。 |
level | 否 | trace、debug、info(默认)、notice、warning、error、critical |
category | 否 | 最多 64 字节:应用内的分类(checkout、sync) |
message | 是 | 最多 2,048 字节。一个稳定的事件名(checkout_done),而不是一段描述文字。 |
user_id | 否 | 最多 128 字节 |
install_id | 否 | 最多 128 字节 |
session_id | 否 | 最多 128 字节 |
attrs | 否 | 见下文 |
payload | 否 | 任意 JSON,序列化后最多 64 KiB。压缩存储,不可搜索。 |
resource | 否 | 见下文 |
未知字段会被拒绝,这样拼写错误会暴露出来,而不是悄悄丢失。
attrs
用于筛选和绘制图表的小字段。
- 值:字符串(最多 1,024 字节)、数字、布尔值、null、字符串数组(最多 64 项)以及嵌套对象(最多 4 层)。
- 叶子节点总共最多 200 个。
- 名称:最多 128 字节,不能含点号(请改用嵌套对象),不能以
_开头。
resource
只接受以下键,每个最多 64 字节:
app_id、app_version、app_build、os_name、os_version、device_model、locale、sdk、environment、platform。
environment 和 platform 只能包含小写字母、数字、- 和 _,最多 32 个字符,且以字母或数字开头。没有 environment 时,事件按 production 保存。没有 platform 时,服务器会根据 sdk 和 os_name 推断。
服务器添加的字段
country:批次来源地址所在国家的 ISO 代码,写在该批次的每个事件上。客户端无法设置它,地址本身也不会保存。见国家。
verified_by:批次使用服务器密钥发送时为 server;使用采集密钥并带有有效的 App Attest 或 Key Attestation token 时为 app_attest 或 key_attestation;其他情况为空。客户端无法设置它:包含 verified_by 的行会被拒绝,并返回 unknown fields: verified_by。见已验证事件。
响应
所有响应都是 JSON。出错时会有一个 error 字段说明问题所在。
| 状态码 | 含义 | 客户端怎么做 |
|---|---|---|
200 {"accepted":n,"rejected":[{"line":i,"error":"..."}]} | 已保存。被拒绝的行是无效的。 | 删除该批次。永远不要重发被拒绝的行。 |
400、413、415,以及其他任何 4xx | 批次本身有问题 | 删除它:重发也会失败。 |
| 3xx | 不是采集服务的响应:endpoint 写错了 | 不要跟随跳转;修正 endpoint。 |
401、403 | 密钥未知、已撤销或只读 | 停止发送,直到下次启动;保留数据。 |
408、425、429、5xx、网络错误 | 临时问题 | 保留相同的字节,按退避策略重试,遵守 Retry-After。 |
批次按以下顺序检查:先是密钥,然后是 Content-Type 和声明的大小,接着是月度配额、单个地址的每日配额和速率限制(这些都在读取请求体之前),最后是请求体及其中的各行。没通过某项检查的批次会收到对应的响应,什么都不会保存。被拒绝的行也计入速率限制。同一时刻发送的多个批次,可能会在月度配额生效前略微超出一点。
撤销密钥会立即生效,但请留出最多一分钟的余量。
400、413、415:批次本身的问题
| 状态码 | error | 怎么修正 |
|---|---|---|
415 | Content-Type must be application/x-ndjson | 发送 application/x-ndjson 或 application/jsonl |
400 | unsupported Content-Encoding "br" (use gzip) | 发送 gzip,或不带 Content-Encoding |
400 | body is not valid gzip | 用 gzip 压缩整个请求体 |
400 | empty batch | 至少发送一个事件 |
400 | too many events in one batch (max 2000) | 拆分批次 |
413 | body too large、body too large once decompressed | 让每个批次在 gzip 前后都小于 4 MiB |
429:月度配额
Free 组织每月包含 1,000,000 个事件,由其所有项目共享。超出后,每个批次都会收到 429,直到下个月开始(UTC 时间每月 1 日),或组织换到其他套餐。设置了支出上限的 Pro 组织,在达到上限所覆盖的事件数时也会收到同样的响应,其中 limit_kind 为 spending_cap:
{"error":"this organization's free plan includes 1000000 events a month and they're used: upgrade it, or events resume on 1 December","limit_kind":"plan","plan":"free","limit":1000000,"used":1000412}| 字段 | 含义 |
|---|---|
error | 发生了什么,给人看的说明 |
limit_kind | plan(Free 的月度事件数)或 spending_cap(Pro 组织的支出上限所覆盖的事件数) |
plan | 组织的套餐 |
limit | 套餐每月包含的事件数,或支出上限覆盖的事件数 |
used | 本月到目前为止统计的事件数 |
Retry-After 是距下个月开始的秒数,但最多一小时,这样升级后很快就能生效。像对待其他 429 一样处理它:保留批次,稍后再发。SDK 会在其队列限制内自动处理(见什么在哪里等待),并在第一次遇到时记录一条警告。要区分这个 429 和另外两种,看 plan 字段:单个地址的每日配额返回的是 source_limit,而速率限制的响应体里只有 error。
429:单个地址的每日配额
使用公开密钥(采集密钥或完全访问密钥)时,一个地址在一个 UTC 日内最多可发送套餐月度事件数的五十分之一,由组织的所有项目共享:Free 20,000,Pro 200,000,Business 4,000,000,Unlimited 不限。IPv6 地址按 /64 计算。已验证的批次(使用服务器密钥,或带有有效的 App Attest 或 Key Attestation token)不受此限制。超出后,来自该地址的批次会收到 429:
{"error":"this address sent 20000 events today with a public key of this organization, its share of the day: a server should use a server key, which has no such limit; events from here resume tomorrow (UTC)","source_limit":20000}source_limit 是一个地址每天可以发送的事件数。Retry-After 是距下一个 UTC 日的秒数,最多一小时。其他地址照常发送。像对待其他 429 一样处理它;如果是服务器收到了,就给那台服务器换上服务器密钥。为什么有这个限制:已验证事件。
425:只接受已验证事件
项目可以设置为某个平台只接受已验证事件(由所有者在项目设置中开启,默认关闭)。未验证的批次中只要有来自该平台的事件,就会收到 425 Too Early、Retry-After: 30 以及
{"error":"this project accepts only verified events from ios: ...","verification_required":"ios"}
(或 android)。
该批次的任何内容都不会保存。保留它,等拿到有效的 X-Lyrelog-Attestation token 后再带上它重发:SDK 会自动这样做。详见已验证事件。
429:速率限制
默认情况下,每个项目每分钟最多接收 60,000 个事件。超出的批次会收到 429,响应体为 {"error":"rate limit for this project"},并带有以秒为单位的 Retry-After。
429:未知密钥
一个地址在一分钟内发送超过 30 个未知密钥时,会收到 429 和 Retry-After: 60。格式不像 Lyrelog 密钥的 token 会直接收到 401。
503
服务器暂时无法连接其数据库或存储,或正忙于处理其他批次。它会返回 Retry-After: 5。用相同的字节重试。
幂等性
投递语义是至少一次。当重试可能造成重复时,请重发完全相同的行:event_id 和 ts 都相同的事件会合并为一个。重试时永远不要生成新的 id。
Apple App Attest
运行在真实 iPhone、iPad 或 Apple Watch 上的 Apple 应用可以证明自己是该项目的正版应用,之后其事件保存时 verified_by 为 app_attest。Swift SDK 就是这个客户端(React Native 和 Flutter 底层也用它),会自动完成以下全部流程;本节仅供参考。它能证明什么,以及如何设置:已验证事件。
这三个路由接受 JSON 请求体,以项目的采集密钥作为 bearer,每次调用按一个事件计入项目的速率限制。在所有者于项目设置中添加 App ID 之前,它们返回 404;对其他任何密钥返回 403(服务器密钥的事件本来就是已验证的)。它们不支持 CORS:是给应用用的,不是给网页用的。
| 路由 | 请求体 | 响应 |
|---|---|---|
POST /v1/attest/challenge | {} | {"challenge":"..."}:一次性,5 分钟内有效,仅限本项目 |
POST /v1/attest/key | {"key_id","attestation","challenge"} | {"token","expires_at"} |
POST /v1/attest/token | {"key_id","assertion","challenge"} | {"token","expires_at"};如果项目中没有该密钥则返回 404:重新做一次 attestation |
key_id是DCAppAttestService返回的 base64 密钥 id;attestation和assertion也是 base64。应用对 challenge 的 UTF-8 字节计算 SHA-256,作为clientDataHash传入。/v1/attest/key每次安装调用一次,传入新密钥的 attestation。/v1/attest/token用该密钥生成的 assertion 续期 token。校验不通过的 attestation 或 assertion 会收到400。- token 有效期为 24 小时。批次在
X-Lyrelog-Attestationheader 中携带它。有效的 token 会让该批次成为已验证批次,并免受单个地址的每日配额限制。没有 token 时,一切照旧。证明不了任何东西的 token(已过期、属于其他项目,或根本不是 token)会让批次保持未验证,响应中会带上X-Lyrelog-Attestation: renew,让应用去获取新的 token。 - 批次永远不会因为其 token 而被拒绝。
Android Key Attestation
运行在真实设备上的 Android 应用可以证明自己是该项目的正版应用,用你的证书签名,并且运行在未被篡改的设备上。之后其事件保存时 verified_by 为 key_attestation。Android SDK 就是这个客户端(React Native 和 Flutter 底层也用它),会自动完成以下全部流程;本节仅供参考。它能证明什么,以及如何设置:已验证事件。
规则与 App Attest 相同:JSON 请求体,以项目的采集密钥作为 bearer(其他任何密钥返回 403),每次调用按一个事件计入项目的速率限制,不支持 CORS,并且在所有者于项目设置中添加 Android 应用(包名和签名证书)之前返回 404。challenge 来自同一个路由 POST /v1/attest/challenge。
| 路由 | 请求体 | 响应 |
|---|---|---|
POST /v1/attest/android/key | {"challenge","chain":[...]} | {"token","expires_at","key_id"} |
POST /v1/attest/android/token | {"key_id","challenge","signature"} | {"token","expires_at"};如果项目中没有该密钥则返回 404:重新做一次 attestation |
/v1/attest/android/key每次安装调用一次。应用在 Android Keystore 中生成一个 EC P-256 密钥,以 challenge 的 UTF-8 字节作为其 attestation challenge,然后发送该密钥的证书链,叶证书在前,每个证书都是标准 base64 编码的 DER。请保存响应中的key_id。/v1/attest/android/token用于续期 token:signature是用该密钥对新 challenge 的 UTF-8 字节所做的 base64 ECDSA 签名(SHA256withECDSA,DER)。- 校验不通过的证书链或签名会收到
400。服务器刚启动、还没拿到 Google 的证书吊销列表时,/v1/attest/android/key可能返回503并带有Retry-After:稍后再试。 - token 的工作方式与 App Attest 相同:有效期 24 小时,放在
X-Lyrelog-Attestation中,证明不了任何东西时返回renew,批次永远不会因为其 token 而被拒绝。
CORS
该 endpoint 响应来自任何源的浏览器请求,因此网页可以直接发送事件:
| Header | 值 |
|---|---|
Access-Control-Allow-Origin | * |
Access-Control-Allow-Methods | POST, OPTIONS |
Access-Control-Allow-Headers | Authorization, Content-Type, Content-Encoding |
Access-Control-Expose-Headers | Retry-After |
Access-Control-Max-Age | 86400 |
使用通配符是安全的,因为不涉及 cookie,而且采集密钥只能追加事件。控制台自己的 API 不支持 CORS。
示例
在这些示例中,shell 变量 $LYRELOG_KEY 存放项目的某个密钥(自己设置:export LYRELOG_KEY=lyr_srv_...)。像这里一样从服务器或 cron 任务发送时,请使用服务器密钥 lyr_srv_...;采集密钥 lyr_ing_... 也能用,但其事件不是已验证的。
一个事件
curl -X POST https://ingest.lyrelog.com/v1/events:batch \
-H "Authorization: Bearer $LYRELOG_KEY" \
-H "Content-Type: application/x-ndjson" \
--data-binary @- <<EOF2
{"event_id":"$(uuidgen | tr A-Z a-z)","ts":"$(date -u +%Y-%m-%dT%H:%M:%SZ)","level":"warning","category":"backup","message":"backup_slow","attrs":{"seconds":412},"resource":{"environment":"production","platform":"cron"}}
EOF2多个事件,gzip 压缩
cat > batch.ndjson <<EOF2
{"event_id":"$(uuidgen | tr A-Z a-z)","ts":"$(date -u +%Y-%m-%dT%H:%M:%SZ)","message":"deploy_started","attrs":{"version":"2.0.1"}}
{"event_id":"$(uuidgen | tr A-Z a-z)","ts":"$(date -u +%Y-%m-%dT%H:%M:%SZ)","message":"deploy_finished","attrs":{"version":"2.0.1","seconds":48}}
EOF2
gzip -c batch.ndjson > batch.ndjson.gz
curl -X POST https://ingest.lyrelog.com/v1/events:batch \
-H "Authorization: Bearer $LYRELOG_KEY" \
-H "Content-Type: application/x-ndjson" \
-H "Content-Encoding: gzip" \
--data-binary @batch.ndjson.gz被拒绝的行
第二行有个拼写错误,mesage:
printf '%s\n' \
"{\"event_id\":\"$(uuidgen | tr A-Z a-z)\",\"ts\":\"$(date -u +%Y-%m-%dT%H:%M:%SZ)\",\"message\":\"ok\"}" \
"{\"event_id\":\"$(uuidgen | tr A-Z a-z)\",\"ts\":\"$(date -u +%Y-%m-%dT%H:%M:%SZ)\",\"mesage\":\"typo\"}" |
curl -s -X POST https://ingest.lyrelog.com/v1/events:batch \
-H "Authorization: Bearer $LYRELOG_KEY" \
-H "Content-Type: application/x-ndjson" \
--data-binary @-第一行被保存,第二行没有:
{"accepted":1,"rejected":[{"line":2,"error":"unknown fields: mesage"}]}常见的行错误:
error | 怎么修正 |
|---|---|
event_id must be a UUID string | 发送一个 UUID,例如 6f1b2c3d-5a1e-4c1f-9e7a-0a1b2c3d4e5f |
ts must carry a time zone (use Z for UTC) | 用 2026-11-18T10:00:00Z,而不是 2026-11-18T10:00:00 |
message must be a non-empty string | 每个事件都需要 message |
unknown fields: ...、unknown resource fields: ... | 拼写错误,或 Lyrelog 不接受的字段(包括 verified_by 和 country,它们只能由服务器设置) |
bad attribute name "..." in attrs | 属性名含点号或以 _ 开头:请改用嵌套对象 |
attrs.tags: arrays may only hold strings | attrs 中的数组只能包含字符串 |
event_id repeated in this batch | 每个事件要有自己的 id |
健康检查
GET https://ingest.lyrelog.com/healthz返回 200 {"status":"ok","storage":true,"database":true};存储或数据库不可用时,返回 503 并带有 "status":"degraded"。