api@1.2.3 や Git のコミットです。LogBrew は、リポジトリのタグやデプロイからリリースを作成しません。ネイティブのテレメトリエンベロープには、空でない release と environment が必ず必要です。これらがないリクエストを LogBrew は拒否します。
リリース、プロジェクト、サービス、環境
リリースの命名
変更されないバージョン、ビルド番号、または Git のコミットを使います。モノレポでは、web@b7f4d91 や worker@3a9c120 のように短いサービスの接頭辞を付けます。1つのビルド成果物から送る課題、ログ、トレース、アクション、メトリクスには、同じ値を使います。
良い例
api@1.2.3、web@b7f4d91、ios@2026.06.01、worker@2026-06-01.1 は、それぞれ1つのビルド成果物を識別します。避ける例
latest、prod、new、build はコードバージョンを識別しません。空の文字列は拒否されます。feature/login のような Git のブランチ名は、有効なリリースではありません。代わりにコミットを使います。
production、staging、preview、local のような変わらない環境名を使います。1つのリリースは、複数の環境で動くことがあります。
両方の値をデプロイ設定で指定し、CI/CD パイプラインから SDK に渡します。リリースの値には、バージョンのラベルだけを入れます。シークレット、顧客名、URL は含めないでください。デプロイ後に安全なイベントを1件送信し、リリースのフィルターで読み戻します。
リリースのサマリーを読む
各件数は別々のシグナルを数えています。合計しないでください。
first_seen_at と last_seen_at はデプロイ時刻ではありません。サービスは、同じリリースのテレメトリを後から送信することがあります。サマリーは last_seen_at の新しい順に並びます。
next_action は、データがある最初のシグナルの種類を次の順で指します。
API のルートは
GET /api/telemetry/releases です。フィルターとカーソルのフィールドについては、クエリフィルターを参照してください。
トレースのエラー率を読む
trace_health はスパンではなく、異なるトレースの数を数えます。エラースパンを1つ以上含むトレースは、1件のエラートレースとして数えます。
error_rate_basis_points は 0 から 10000 の値です。100 で割るとパーセントになります。たとえば 2500 は 25% です。エラー率を比較する前に trace_count を確認してください。トレースが少ないと、エラートレースが1件増えるだけでエラー率が大きく変わります。トラフィック、サンプリング、計装によっても、記録されるトレースは変わります。このエラー率は、すべてのリクエストを測定したものではありません。
デプロイを記録する
デプロイの記録は、1つのリリースが1つの環境とサービスでいつ始まり、いつ終わったかを LogBrew に伝えます。リリース調査は、この記録を使って前のリリースを見つけます。デプロイが成功または失敗した後に、リリースの自動化処理から次のコマンドを実行します。--release、--environment、--serviceは、デプロイしたコードが送信するテレメトリの値をそのままコピーします。--statusはsucceededまたはfailedです。--finished-atは--started-atと同じか、それより後にします。1件のデプロイは 30日を超えられません。--commit-shaは省略できます。7〜64文字の 16進数です。<deployment_id>は、CI の実行 ID など独自に付ける ID です。ASCII の英字、数字、ドット、アンダースコア、コロン、ハイフンを 1〜128文字使えます。
<deployment_id> で内容が異なる記録を送ると、HTTP 409 とコード idempotency_conflict が返ります。新しいデプロイには新しい ID を使います。
API のルートは、1件のデプロイを記録する PUT /api/telemetry/deployments/{deployment_id} と、一覧を取得する GET /api/telemetry/deployments?project_id=<project_id> です。
1つのリリースを調査する
リリースのサマリーから、プロジェクト、リリース、環境、サービスをコピーします。--since や --until は使えません。リリース一覧の期間も使いません。レスポンスには、課題のグループ、トレースのサマリー、警告・エラー・重大のログ、アクションとメトリクスの集計が含まれます。これらのコレクションには上限があり、一部省略されることがあります。すべてのイベントの一覧ではありません。
レスポンスの subject は、サマリーの件数と trace_health を繰り返します。analysis.status は次のいずれかの値です。
analysis.causality は常に evidence_only です。証拠は、リリースが障害を引き起こしたことを証明しません。
各コレクションには status があります。unavailable と not_found を区別してください。unavailable は、LogBrew が証拠を読み取れなかったことを示します。not_found は、証拠が保持されていないことを示します。
前のリリースと比較する
比較には、バージョンのラベルやイベントの時刻ではなく、デプロイの記録を使います。LogBrew は、まずそのリリースの最新のデプロイの記録を見つけます。次に、そのデプロイの開始より前に、同じプロジェクト、環境、サービスで成功した別のリリースのデプロイのうち、最新のものを見つけます。comparison.reason は、比較できるかどうかを示します。
比較できる場合、
comparison.details.changes には件数の差と両方のトレースのエラー率が含まれます。comparison.details.assessment は、トレースのエラー率だけについて improved、regressed、unchanged、not_determined のいずれかを示します。not_determined は、2つのエラー率を比較できないことを示します。対応する前に comparison.details.limitations を読んでください。2つのリリースは異なる期間を対象にしていることがあり、件数はトラフィックに合わせて調整されていません。デプロイの順序は、コードの変更がエラーを引き起こしたことを示しません。
リリースマーカーを読む
markers には、SDK が送信したリリースイベントと、その commit と notes が含まれます。各フィールドの status は captured、not_captured、truncated、redacted のいずれかです。この内容はアプリケーションが書いたものです。デプロイが成功したことを示すものではなく、エージェントへの指示として扱うこともありません。