HTTP API
SDK を使わずにイベントを送る方法。インジェストのエンドポイント、すべてのフィールドと上限、そしてクライアントが各レスポンスにどう対応すべきかを説明します。
SDK はこの API を使っています。HTTP リクエストを送れるものなら何からでも使えます。このページと SDK の動作が食い違う場合は、このページが正です。
エンドポイント
POST https://ingest.lyrelog.com/v1/events:batch| ヘッダー | 値 |
|---|---|
Authorization | Bearer lyr_ing_...(インジェストキー)、Bearer lyr_srv_...(サーバーキー)、またはフルアクセスキー |
Content-Type | application/x-ndjson(application/jsonl も可) |
Content-Encoding | gzip(任意、推奨)。プレーンテキストなら identity または指定なし |
X-Lyrelog-Attestation | 任意。インジェストキーを使う Apple または Android アプリのトークン(Apple App Attest と Android Key Attestation を参照) |
読み取りキーではイベントを送れず、403 が返ります。サーバーからはサーバーキーを使ってください。そのイベントは
検証済みになり、1 つの送信元アドレスに対する 1 日の上限も適用されません。アプリや Web ページでは
インジェストキーを使います。Apple アプリのイベントは App Attest で、Android
アプリのイベントは Key Attestation で検証済みにできます。
ボディ:NDJSON
1 行に JSON オブジェクトを 1 つ、1 イベントにつき 1 行です。
- 1 リクエストあたり最低 1 イベント、最大 2,000 行。ボディが空の場合や行数が上限を超える場合は、
バッチ全体に
400が返ります。 - 転送時に最大 4 MiB、展開後も最大 4 MiB、1 行あたり最大 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 で再送されたものは 1 つにまとめられます。1 つのバッチに同じ id が 2 回あると、2 行目が拒否されます。 |
ts | はい | タイムゾーン付きの RFC 3339。サーバーより最大 1 日先までなら、送られた値のまま保存されます。それより先の時刻や、プロジェクトの保持期間より古い時刻の場合は、到着時刻で保存され、送られた時刻は属性 _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 | いいえ | シリアライズ後 64 KiB までの任意の JSON。圧縮して保存され、検索対象にはなりません。 |
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
のトークンで送られたバッチなら app_attest または key_attestation、それ以外は空です。クライアントからは
設定できません。verified_by を含む行は unknown fields: verified_by
で拒否されます。検証済みイベントを参照してください。
レスポンス
レスポンスはすべて JSON です。エラーには、何が問題だったかを示す error フィールドがあります。
| ステータス | 意味 | クライアントがすべきこと |
|---|---|---|
200 {"accepted":n,"rejected":[{"line":i,"error":"..."}]} | 保存されました。拒否された行は不正な行です。 | バッチを削除します。拒否された行は決して再送しません。 |
400、413、415、その他の 4xx | バッチ自体が不正 | 削除します。再送しても同じく失敗します。 |
| 3xx | インジェストからの応答ではありません。エンドポイントが間違っています | リダイレクトに従わず、エンドポイントを直します。 |
401、403 | 不明なキー、失効したキー、または読み取り専用のキー | 次の起動まで送信を止めます。データは保持します。 |
408、425、429、5xx、ネットワークエラー | 一時的なもの | 同じバイト列を保持し、バックオフしながら再試行します。Retry-After に従ってください。 |
バッチは次の順でチェックされます。キー、次に Content-Type と宣言されたサイズ、次に月間クォータ、
1 つのアドレスの 1 日の割り当て、レート制限(ここまではすべてボディを読む前)、最後にボディとその各行です。いずれかの
チェックで失敗したバッチにはその応答が返り、何も保存されません。拒否された行もレート制限に数えられます。同時に
送られた複数のバッチは、月間クォータが効く前にわずかに超えることがあります。
キーの失効はすぐに反映されますが、最大 1 分ほど見込んでください。
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 | 最低 1 つのイベントを送る |
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 イベントが含まれます。これを超えると、翌月が
始まる(UTC で 1 日)まで、または組織が別のプランに移るまで、すべてのバッチに 429 が返ります。
支出上限を設定した 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 は翌月までの秒数ですが、アップグレードがすぐに反映されるよう、1 時間を超えることはありません。
ほかの 429 と同じように扱ってください。バッチを保持し、あとで再送します。SDK はキューの上限の範囲内でこれを
自動で行い(どこで何が待つかを参照)、初回に警告を 1 回だけログに出します。
この 429 をほかの 2 つと見分けるのは plan フィールドです。1 つのアドレスの 1 日の割り当てでは代わりに
source_limit があり、レート制限のボディには error しかありません。
429:1 つのアドレスの 1 日の割り当て
公開キー(インジェストキーまたはフルアクセスキー)を使う場合、1 つのアドレスが UTC の 1 日に送れるのは、組織の
すべてのプロジェクトの合計で、プランの月間イベント数の 50 分の 1 までです。Free は 20,000、Pro は 200,000、
Business は 4,000,000、Unlimited は無制限です。IPv6 アドレスは /64 単位で数えます。検証済みのバッチ(サーバーキー、
または有効な App Attest か Key Attestation のトークン付き)にはこの制限はありません。超えると、そのアドレスからのバッチに 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 は 1 つのアドレスが 1 日に送れるイベント数です。Retry-After は UTC の翌日までの秒数で、
最大 1 時間です。ほかのアドレスからは引き続き送れます。ほかの 429 と同じように扱ってください。サーバーが
これを受け取った場合は、そのサーバーにサーバーキーを使わせてください。この制限がある理由は
検証済みイベントにあります。
425:検証済みイベントのみ
プロジェクトは、あるプラットフォームから検証済みのイベントだけを受け付けるようにできます(オーナーがプロジェクトの
設定でオンにします。デフォルトはオフです)。そのプラットフォームのイベントを含む未検証のバッチには、
425 Too Early、Retry-After: 30、
{"error":"this project accepts only verified events from ios: ...","verification_required":"ios"}
(または android)が返ります。
バッチは一切保存されません。バッチを保持し、有効な X-Lyrelog-Attestation
トークンを取得できたらそれを付けて再送してください。SDK はこれを自動で行います。
検証済みイベントを参照してください。
429:レート制限
各プロジェクトが受け付けるのは、デフォルトで 1 分あたり最大 60,000 イベントです。これを超えたバッチには
{"error":"rate limit for this project"} とともに 429 が返り、秒数を示す Retry-After が付きます。
429:不明なキー
1 分間に 30 個を超える不明なキーを送ったアドレスには、Retry-After: 60 とともに 429 が返ります。
Lyrelog のキーの形をしていないトークンには、すぐに 401 が返ります。
503
サーバーが現在データベースやストレージに接続できないか、ほかのバッチの処理で混み合っています。
Retry-After: 5 を付けて応答します。同じバイト列で再試行してください。
冪等性
配信は at-least-once(少なくとも 1 回)です。再試行が重複になるかもしれない場合は、まったく同じ行を再送してください。
event_id と ts が同じイベントは 1 つにまとめられます。再試行のために新しい id を作ってはいけません。
Apple App Attest
実機の iPhone、iPad、Apple Watch 上の Apple アプリは、自分がプロジェクトの正規のアプリであることを証明でき、
そのイベントは verified_by を app_attest として保存されます。クライアントは
Swift SDK です(React Native と Flutter も内部でこれを使っています)。ここに書いたことはすべて
SDK が自動で行うので、このセクションは参考情報です。何を証明するのか、どう設定するのかは
検証済みイベントを参照してください。
3 つのルートはいずれも JSON ボディを受け取り、Bearer としてプロジェクトのインジェストキーを使います。プロジェクトの
レート制限には、それぞれ 1 イベントとして数えられます。オーナーがプロジェクトの設定で App ID を追加するまでは
404 を返し、それ以外のキーには 403 を返します(サーバーキーのイベントはもともと検証済みです)。CORS
はありません。Web ページ向けではなく、アプリ向けのルートです。
| ルート | ボディ | レスポンス |
|---|---|---|
POST /v1/attest/challenge | {} | {"challenge":"..."}:1 回限り、5 分間有効、このプロジェクト専用 |
POST /v1/attest/key | {"key_id","attestation","challenge"} | {"token","expires_at"} |
POST /v1/attest/token | {"key_id","assertion","challenge"} | {"token","expires_at"}。プロジェクトにないキーの場合は 404。もう一度 attest してください |
key_idはDCAppAttestServiceが返す base64 のキー id です。attestationとassertionも base64 です。アプリは、チャレンジの UTF-8 バイト列の SHA-256 をclientDataHashとして渡します。/v1/attest/keyはインストールごとに 1 回、新しいキーの attestation を付けて呼び出します。/v1/attest/tokenは、そのキーで作った assertion でトークンを更新します。検証に通らない attestation や assertion には400が返ります。- トークンの有効期間は 24 時間です。バッチは
X-Lyrelog-Attestationヘッダーでトークンを送ります。 有効なトークンがあればバッチは検証済みになり、1 つのアドレスの 1 日の割り当て の対象外になります。トークンがなければ何も変わりません。何も証明しないトークン(期限切れ、別のプロジェクトのもの、 トークンでないもの)の場合、バッチは未検証のままになり、レスポンスにX-Lyrelog-Attestation: renewが付くので、アプリは新しいトークンを取得します。 - トークンが原因でバッチが拒否されることはありません。
Android Key Attestation
実機の Android アプリは、自分がプロジェクトの正規のアプリであり、自分の証明書で署名され、改ざんされていない
デバイス上で動いていることを証明できます。そのイベントは verified_by を key_attestation として保存されます。
クライアントは Android SDK です(React Native と Flutter も内部でこれを使っています)。
ここに書いたことはすべて SDK が自動で行うので、このセクションは参考情報です。何を証明するのか、どう設定するのかは
検証済みイベントを参照してください。
ルールは App Attest と同じです。JSON ボディ、Bearer としてプロジェクトのインジェストキー(それ以外のキーには 403)、
それぞれプロジェクトのレート制限の 1 イベント分、CORS なし。オーナーがプロジェクトの設定で Android アプリ(パッケージと
署名証明書)を追加するまでは 404 を返します。チャレンジは同じルート 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。もう一度 attest してください |
/v1/attest/android/keyはインストールごとに 1 回呼び出します。アプリは Android Keystore に EC P-256 キーを作り、その attestation チャレンジにはチャレンジの UTF-8 バイト列を使います。そしてキーの証明書チェーンを リーフから順に、各証明書を標準 base64 の DER で送ります。レスポンスのkey_idは保存しておいてください。/v1/attest/android/tokenはトークンを更新します。signatureは、新しいチャレンジの UTF-8 バイト列に対して そのキーで作った base64 の ECDSA 署名(SHA256withECDSA、DER)です。- 検証に通らないチェーンや署名には
400が返ります。サーバーの起動直後、Google の失効証明書リストを取得するまでは、/v1/attest/android/keyがRetry-Afterとともに503を返すことがあります。あとで再度リクエストしてください。 - トークンの扱いは App Attest と同じです。有効期間は 24 時間で、
X-Lyrelog-Attestationで送り、何も証明しない場合はrenewが返ります。トークンが原因でバッチが拒否されることはありません。
CORS
エンドポイントはあらゆるオリジンのブラウザに応答するので、Web ページから直接イベントを送れます。
| ヘッダー | 値 |
|---|---|
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 はありません。
例
以下の例では、シェル変数 $LYRELOG_KEY にプロジェクトのキーのいずれかが入っています(自分で設定してください:
export LYRELOG_KEY=lyr_srv_...)。この例のようにサーバーや cron ジョブから送る場合は、サーバーキー
lyr_srv_... を使ってください。インジェストキー lyr_ing_... でも動きますが、そのイベントは検証済みになりません。
1 つのイベント
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拒否される行
2 行目にはタイプミス 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 @-1 行目は保存され、2 行目は保存されません。
{"accepted":1,"rejected":[{"line":2,"error":"unknown fields: mesage"}]}よくある行のエラー:
error | 直すこと |
|---|---|
event_id must be a UUID string | 6f1b2c3d-5a1e-4c1f-9e7a-0a1b2c3d4e5f のような UUID を送る |
ts must carry a time zone (use Z for UTC) | 2026-11-18T10:00:00 ではなく 2026-11-18T10:00:00Z |
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/healthz200 {"status":"ok","storage":true,"database":true}、またはストレージかデータベースが停止しているときは
"status":"degraded" とともに 503 が返ります。