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

HTTP API

不用 SDK 也能发送事件。采集 endpoint、每个字段和限制,以及客户端该如何处理每种响应。

SDK 用的就是这个 API,任何能发 HTTP 请求的程序也都可以用。本页与某个 SDK 的说法不一致时,以本页为准。

Endpoint

POST https://ingest.lyrelog.com/v1/events:batch
Header值
AuthorizationBearer lyr_ing_...(采集密钥)、Bearer lyr_srv_...(服务器密钥),或完全访问密钥
Content-Typeapplication/x-ndjson(application/jsonl 也可以)
Content-Encodinggzip(可选,推荐),纯文本则用 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怎么修正
415Content-Type must be application/x-ndjson发送 application/x-ndjson 或 application/jsonl
400unsupported Content-Encoding "br" (use gzip)发送 gzip,或不带 Content-Encoding
400body is not valid gzip用 gzip 压缩整个请求体
400empty batch至少发送一个事件
400too many events in one batch (max 2000)拆分批次
413body 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_kindplan(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-Attestation header 中携带它。有效的 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-MethodsPOST, OPTIONS
Access-Control-Allow-HeadersAuthorization, Content-Type, Content-Encoding
Access-Control-Expose-HeadersRetry-After
Access-Control-Max-Age86400

使用通配符是安全的,因为不涉及 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 stringsattrs 中的数组只能包含字符串
event_id repeated in this batch每个事件要有自己的 id

健康检查

GET https://ingest.lyrelog.com/healthz

返回 200 {"status":"ok","storage":true,"database":true};存储或数据库不可用时,返回 503 并带有 "status":"degraded"。