読み取り API
読み取りキーを使って、スクリプトからプロジェクトのイベントをクエリします。
イベントを読む方法の 1 つはダッシュボードです。もう 1 つが読み取り API です。同じフィルターを JSON で使え、スクリプト、ノートブック、定期ジョブ、エージェントから利用できます。
認証
プロジェクトの API keys ページで New key を選び、What it can do を Read events にします。キーは lyr_read_ で始まり、一度だけ表示されます。これを bearer token として https://app.lyrelog.com に送ります。以下の例では、キーをシェル変数に入れています。
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 | 1 つ以上のレベルをカンマ区切りで:error,critical |
category, message | 領域とイベント名。複数の値は | で区切り、除外するには先頭に ! を付けます:message=!http_request_served |
user, session, install | ID |
env, platform | production、ios など。指定しなければ、すべての環境とプラットフォーム。 |
version, os, device, locale | アプリのバージョン、OS のバージョン(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 が含まれないので、取得するにはイベントを 1 件指定してリクエストしてください。
すべてのページを読む
カーソルは、それが返されたクエリの続きにしか使えません。同じフィルターと一緒に送ってください。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
done1 件のイベント
GET /v1/events/{event_id}?ts={ts} は、1 件のイベントを 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 個を超える、1 つのフィルターの値が 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 ヘッダーがありません。読み取りキーはブラウザーに置くものではないからです。