422 と validation_failed で拒否します。project、trace、user などのわかりやすい別名は、クエリキーではありません。あるルートのフィルターを、別のルートにそのまま移さないでください。
絞り込んだリクエストを作る
クエリ文字列はパスの後に付けます。予約文字を安全に扱うため、--data-urlencode を使います。次のリクエストは、1つのプロジェクトの直近24時間の重大のログを読みます。
project_idまたはproject_idsでプロジェクトを選びます。sinceと、必要に応じてuntilで期間を追加します。- サービス、リリース、環境、ステータス、またはシグナル固有のフィルターを追加します。
- ページを小さくするには
limitを設定します。 - カーソルのフィールドは、カーソルのレスポンスが返した後にだけ追加します。
GET /api/logs では、status を省略すると status=active が使われます。
フィルターの一覧表
「必須」列のキーは、リクエストに必ず含めます。それ以外のキーはすべて任意です。
課題の調査では、
selection は first、latest、recommended のいずれかです。selection と occurrence_id は、どちらか一方だけを送信します。どちらも、2から13までの response_version が必要です。バージョン2以降でどちらも指定しない場合、LogBrew は recommended を使います。occurrence_id は GET /api/telemetry/issues/{issue_id}/events で取得します。
POST の分析用ルートは JSON のボディを受け取ります。プロダクト分析を参照してください。
共通のフィルターとシグナル固有のフィルター
service_name、release、environment は、どのテレメトリの一覧でも結果を絞り込みます。SDK が送信する値をそのまま使ってください。
一部のフィルターは、1つのシグナル専用です。
- ログは
search、trace_id、severity、attribute_filtersを受け付けます。 - ログは
statusとしてactive（デフォルト）、ignored、allを受け付けます。ignoredは、ログのルールによって有効なビューから非表示になっているログを選びます。 - 課題は、課題の
statusとしてunresolved、resolved、archivedを受け付けます。ignoredはarchivedの古い名前で、同じ課題を選びます。 - 課題は
severityとしてinfo、warning、error、criticalを受け付けます。 - 課題は
priorityとしてhigh、medium、lowを受け付けます。 - 課題は
assigneeとして、サインインしているアカウントに割り当てられた課題を表すme、担当者のいない課題を表すnone、自分のチームの課題を表すmy_teams、ユーザー ID、またはteam:<team_id>を受け付けます。 - アクションとメトリクスは
nameを受け付けます。 - アクションは
distinct_idを受け付けます。 - トレースは、トレースの
statusとmin_duration_msを受け付けます。 - デプロイは
statusとしてsucceededまたはfailedを受け付けます。
severity フィルターは、実際に適用された重大度を比較します。ルールで重大度が変更されている場合、フィルターはルールの値を使います。重大度の値を参照してください。
期間
since には、24h や 7d のような正の整数の時間数か日数、または RFC3339 のタイムスタンプを指定できます。短い形式の期間は、各リクエストの時刻を基準にします。
until には RFC3339 のタイムスタンプだけを指定できます。これは終了時刻を含みません。ちょうど until の時刻の行は結果に入りません。since は開始時刻を含みます。たとえば、since=2026-10-01T00:00:00Z と until=2026-10-02T00:00:00Z は、ちょうど1日を選びます。LogBrew はミリ秒単位で時刻を比較します。
until は since より後でなければなりません。そうでない場合や、until が RFC3339 のタイムスタンプでない場合、リクエストは 422 と validation_failed で失敗します。
複数ページを読むときは、RFC3339 の開始時刻を1つ決め、すべてのページで同じ値を使います。until も、すべてのページで同じ値にします。
次のリクエストは、1日分のエラーログを読みます。
デプロイの一覧では、時刻のルールが異なります。
since と until には RFC3339 のタイムスタンプだけを指定でき、どちらも指定した時刻を含みます。比較の対象は、デプロイが完了した時刻です。課題のレスポンスのバージョン
課題の一覧と課題の詳細は、response_version=1、response_version=2、response_version=3、response_version=4 を受け付けます。デフォルトはバージョン1です。それ以外の値は 422 と validation_failed で失敗します。
- バージョン1は、アーカイブ済みの状態を
ignoredと表示します。優先度は表示しません。 - バージョン2は、アーカイブ済みの状態を
archivedと表示します。priorityとpriority_sourceが加わります。 - バージョン3は、バージョン2のすべてのフィールドを持ちます。
assigneeが加わります。 - バージョン4は、バージョン3のすべてのフィールドを持ちます。
assigneeにはtype（userまたはteam）があります。
status=archived、priority、assignee を受け付けます。課題のレスポンスを参照してください。
重大度のフィルター
GET /api/logs では severity=info|warning|error|critical を使います。古い level キーは互換性のための別名です。どちらのキーも、正規の値と、別名の trace、debug、warn、fatal を受け付けます。LogBrew は、比較する前に別名を正規の値に変換します。
リクエストが severity と level の両方を送信した場合、LogBrew はまず両方を正規化します。値が食い違う場合は、次のエラーで拒否します。
トレースのフィルター
トレースの検索では、status は error または ok です。両方を含めるには省略します。min_duration_ms は0以上でなければなりません。これはトレースの検索にだけ適用されます。
次のリクエストは、500ミリ秒以上かかったエラーのトレースを探します。
trace_id をパーセントエンコードしてパスのセグメントにします。クエリキーとして送信しないでください。
プロジェクトの範囲
1つのプロジェクトを読むには、project_id=<project-uuid> を使います。一覧表で project_ids が記載されているルートでは、project_ids=<uuid>,<uuid> で2〜50件のプロジェクトを正確に指定できます。これらのルートでは、両方のキーを省略すると、アカウントが読み取れるすべてのプロジェクトを読みます。project_id が必須のルートは、1つのプロジェクトしか受け付けません。
422 と validation_failed で拒否します。
project_idとproject_idsの両方を含むリクエスト。- ID が2件未満、または50件を超える
project_idsの値。 - 重複した ID や、UUID ではない ID。
project_ids の中に、アカウントが読み取れないプロジェクトの ID が1つでもあると、リクエストは 404 と not_found で失敗します。その ID を外して続けないでください。新しい組み合わせを選ぶよう、ユーザーに依頼してください。
カーソルのどのページでも、同じプロジェクトの範囲を使います。結果が空だったからといって、プロジェクトのフィルターを外さないでください。それは別の質問をすることになります。
時間バケットごとの系列
GET /api/telemetry/metrics/series は、1つのメトリクスを時間バケット（1つの集計区間）ごとに返します。GET /api/telemetry/summary/volume は、シグナルの件数を時間バケットごとに返します。どちらのルートにも、次のルールがあります。
sinceは必須です。untilは任意で、デフォルト値はリクエストの時刻です。sinceからuntilまでの範囲は最大31日です。intervalはauto、1m、5m、15m、1h、6h、1dのいずれかです。デフォルト値はautoです。バケットが500個を超える間隔は失敗します。service_name、release、environmentは完全一致のフィルターです。
name は GET /api/telemetry/metrics で得た正確なメトリクス名です。group_by は none、service_name、release、environment のいずれかです。series_limit は1〜20です。
シグナルの量では、until を未来の時刻にできません。response_version は 1 だけです。
ログの属性で絞り込む
検索できる属性のパスと型を見つけるには、GET /api/logs/attributes を使います。次に、GET /api/logs に attribute_filters を送信します。どちらのリクエストにも since が必要です。
属性のカタログを読む
次のリクエストは、1つのプロジェクトでstatus を含む数値型のパスを探します。
type は string、number、boolean のいずれかです。observed_count は、範囲内で、そのパスと型を持つログの件数です。last_seen_at は、そのうち最新のログの時刻です。1件のログが多くのパスを持つことがあります。件数を足し合わせてログの件数としないでください。
coverage は、属性のフィルターで検索できるログを示します。
3つのグループを合計すると
total_logs になります。カタログの type、search、カーソルは、カバレッジを変えません。attributes の一覧が空でも、total_logs がゼロとは限りません。
カタログには status キーがありません。カタログの重大度フィルターは、実際に適用された重大度ではなく、取得された重大度を比較します。
search は、制御文字を含まない1〜128バイトの、パスの部分文字列です。limit は、1ページの属性の数を設定します。
カタログの続きを読む
カタログではpagination=cursor を使いません。すべてのフィルターを繰り返し、next_cursor の3つのフィールドをすべてコピーします。
next_cursor が null になったら止めます。
型付きのフィルターを適用する
パスと型はカタログからコピーします。パスには、ドット区切りのキーではなく JSON Pointer の構文を使います。パスの中の~0 や ~1 のエスケープは、そのままにしてください。
次のリクエストは、数値のレスポンスステータスが500以上のログを読みます。
attribute_filters は、1〜4個のフィルターを持つ JSON 配列です。ログは、すべてのフィルターに一致する必要があります。各フィルターには path、type、operator、value があります。value の JSON の型は type と一致する必要があります。数値の 500 は、文字列の "500" とは違います。
ne に一致するのは、そのパスを持つログだけです。パスを持たないログは ne に一致しません。string では、case_sensitive は任意で、デフォルト値は false です。LogBrew は、number と boolean に対する "case_sensitive": true を拒否します。
次の上限があります。
- JSON 配列は最大4,096バイトです。
- 文字列の値は最大1,024バイトです。
containsとstarts_withには、空でない文字列が必要です。- 数値は有限で、-9,007,199,254,740,992 から 9,007,199,254,740,992 までの範囲でなければなりません。
attribute_filters を付けないリクエストでは表示されることがあります。ログのレスポンスについては、ログのレスポンスを参照してください。
属性のエラーを修正する
次のエラーは、どれも422 と validation_failed を返します。
再試行する前に、リクエストを修正してください。フィルターを外すと結果が変わるため、外さないでください。
カーソルベースのページネーション
カーソルモードは、指定した場合にだけ有効になります。指定しない場合、一覧のルートは配列だけを返します。最初のページでは、カーソルのフィールドを付けずにpagination=cursor を送信します。次のページからは、すべてのフィルターを繰り返し、カーソルのフィールドをすべてそろえて送信します。
返された
next_cursor のフィールドを、次のリクエストに対応付けます。
next_cursor.timeはcursor_timeに入れます。next_cursor.idはcursor_idに入れます。- トレースでは、
next_cursor.trace_idをcursor_trace_idに入れます。 - リリースでは、返された各フィールド名の前に
cursor_を付けます。たとえば、next_cursor.releaseはcursor_releaseに入れます。
next_cursor が null になったら止めます。最後の行からカーソルを計算しないでください。リリースのカーソルは、選択したプロジェクトを変えません。元の project_id または project_ids をそのまま使ってください。
limit はページのサイズを設定します。1ページの行数がそれより少ないこともあります。これらのルートは page や page_number を受け付けません。
ほとんどのルートでは、最大値を超える
limit を LogBrew が最大値に置き換えます。デプロイの一覧は、1〜100の範囲外の limit を 422 で拒否します。デプロイの一覧は、pagination=cursor がなくても、常に next_cursor を含むページのオブジェクトを返します。
LogBrew は、次のリクエストを 422 と validation_failed で拒否します。
cursor以外のpaginationの値。pagination=cursorのないカーソルのフィールド。- そろっていないカーソルのフィールド。
- RFC3339 のタイムスタンプではない
cursor_time。
結果が空のときの診断
一覧が空の場合、すべてのフィルターに一致する行がなかったことを意味します。他のシグナルについては何もわかりません。リクエストを次の順序で確認します。- プロジェクト ID を確認します。
- 任意のフィルターを1つずつ外します。
- 期待するイベントがより古い場合は、
sinceを広げます。期待するイベントがより新しい場合は、untilを外すか、より後の時刻にします。 service_name、release、environmentを、SDK が送信する値と比較します。- ログの場合、ログのルールが期待するログを非表示にしている可能性があれば、
status=allを追加します。 - ルートが各フィルターを受け付けることを確認します。
拒否されたクエリから復旧する
拒否されたクエリは、標準のエラーエンベロープを返します。不明なキーや型の違う値は、422 を返します。
- わかりやすい別名を、フィルターの一覧表にあるキーに置き換えます。
- ルートが必要とする、続きを読むためのカーソルのフィールドをすべて送信します。
- 最初のページのリクエストから、カーソルのフィールドを外します。
- プロジェクトの指定方法は1つだけにします。
- 対応していない重大度やトレースのステータスを、正規の値に置き換えます。