推奨する発生事象を読む
LogBrew CLI をインストールし、logbrew login を実行します。課題の一覧から課題の UUID をコピーします。CLI はレスポンスを検証してから表示します。
--json を使います。logbrew explain issue "<issue_id>" も同じ読み取りです。API を直接呼び出す場合は、レスポンスのバージョン 13 をリクエストします。CLI も同じバージョンをリクエストします。
response_version の 1〜13 を受け付けます。発生事象を選択するには、バージョン 2 以降が必要です。このガイドではバージョン 13 を説明します。
推奨する発生事象は、役立つコンテキストを持つ、最近の保持済みの発生事象です。最新の発生事象より古い場合もあります。LogBrew は、保持されている新しい発生事象を occurrence_selection.recommendation.candidate_limit 件まで比較します。そのうち、調査のコンテキストが最も多いものを選びます。コンテキストが同じ場合は、新しい方を選びます。occurrence_selection.recommendation.candidate_window_truncated が true の場合、推奨の評価に含まれていない古い発生事象がその課題にあります。
調査の範囲を確認する
課題一覧のフィルターは調査には適用されません。課題 ID はグループを選び、レスポンスにはそのグループの保持された履歴が含まれることがあります。発生事象 ID を正確に指定しても、その履歴は除かれません。タスクでその履歴を扱えない場合は、調査をリクエストしないでください。 エラーを解釈する前に、次を確認します。subject.project_idが目的のプロジェクトである。event.idが選択した発生事象である。event.occurred_atがインシデントの期間内にある。- サービス、環境、リリースが、確認中のデプロイと一致する。
schema_versionが13である。
別の発生事象を選ぶ
セレクターを1つ送信します。selection と occurrence_id を同時に送信しないでください。subject の first_seen_at と last_seen_at はグループを表します。詳しい証拠は、選択した event に属します。
occurrence_selection は、first、latest、recommended、selected の発生事象のサマリーも返します。occurrence_selection.reason は、LogBrew がその発生事象を選んだ理由を示します。
レスポンスを順番に読む
- グループについては
subjectを、選択した発生事象についてはeventを読みます。 - グループの履歴については
grouping、lifecycle、occurrence_analysisを読みます。 - コードの位置については
fixを読みます。ファイル、関数、行、列と一緒に、そのprovenanceも確認します。観測されたフレームは確認すべきコードを示すもので、原因を証明するものではありません。 cause.statusとその証拠を読みます。どの原因の値も、根本原因を証明しません。impact.user_impactはimpact.occurrence_countとは別に読みます。件数と一緒にcount_method、coverage、limitationsも確認します。1人のユーザーが複数の発生事象を引き起こすことがあります。reproduction.statusを読み、次にcorrelationsを読みます。
コードの位置と原因
fix.status は、コードの位置の出所を示します。
cause.status は reported_hypothesis、evidence_only、unknown のいずれかです。reported_hypothesis はアプリから来たもので、検証されていません。cause.signals には、unhandled_exception や error_trace_span など、観測されたシグナルが並びます。provenance は backend_observed または application_reported です。この2つは区別してください。
ソースファイルを見つける
プロジェクトのセットアップでサービスにリポジトリが設定されている場合、source_locator はコードの位置をリポジトリに結び付けます。ファイルを開くには、repository_full_name、revision、repository_relative_file を使います。revision_source は deployment_commit または setup_snapshot です。
source_locator.status が not_found の場合、そのサービスにはリポジトリのコンポーネントが結び付いていません。ファイルがないという意味ではありません。ファイル名からコンポーネントを推測しないでください。
影響を受けたユーザー
known_affected_users は、ステータスが complete でも概算です。匿名ユーザーや、ユーザーのコンテキストを持たない発生事象は数えません。件数が null の場合、0 という意味ではありません。impact.reported には、アプリが報告した値が入ります。測定された件数に足さないでください。
再現のステータス
きっかけは
event.request または impact.reported.failed_action から取ります。想定される失敗は event.exception または event.request.response_status_code から取ります。コードの位置は fix.location です。reproduction.baseline_occurrence_id は、選択した発生事象です。reproduction.evidence の記録は、各入力を reproduction.trigger、reproduction.expected_failure、reproduction.code_location として残します。ready は、再実行に成功したことを証明しません。リクエストの本文、秘匿済みの値、手順を作り出さないでください。
ライフサイクルと再発
lifecycle.persisted_status は保存されているステータスです。課題が解決された後に発生事象が届くと、lifecycle.effective_status は regressed になります。保存されているステータスは、人が課題を再開するまで resolved のままです。lifecycle.regression.first_reappeared_occurrence は、最初の新しい発生事象を示します。
調査のレスポンスでは、アーカイブ済みの課題は subject.status と lifecycle で ignored と表示されます。ステータスの値を参照してください。
欠けている証拠と上限のある証拠を扱う
correlations.trace.status の値は次のとおりです。
not_linked の場合は、例外、フレーム、直前の手順など、返された他の証拠で調査を続けます。not_found の場合は、そのトレース ID をそのまま控えておきます。unavailable の場合は、後で再試行します。どのステータスも、アプリにトレースがないことを意味しません。available のトレースに、課題の取得用のスパンしか含まれないこともあります。取得用のスパンを参照してください。
correlations.logs には、同じリリースと環境から発生時刻の前後に記録されたログが入ります。発生事象にトレース ID がある場合、ログはそのトレースから取ります。トレース ID がない場合は、同じサービスから取ります。actions、metrics、related_issues にはトレース ID が必要です。各コレクションには、status、その items、truncated があります。
captured_fields、missing_fields、redacted_fields、truncated_fields は区別してください。秘匿済みのデータは未取得ではありません。一部省略されたデータは完全ではありません。必須のフィールドが未取得、秘匿済み、一部省略、利用不可のいずれかの場合、evidence.status は partial になります。SDK を更新しても、過去のイベントに証拠は追加されません。
関連するログ、課題、リリースは、正確な ID でたどってください。近いタイムスタンプは、結び付きを示しません。
次のアクションに従う
クライアントがcode と target の組み合わせに対応している場合は、next_actions を priority の順に処理します。各アクションには reason もあります。
候補のデプロイを検証する
失敗した発生事象の ID を基準として使います。候補のデプロイ ID は、デプロイの証拠またはリリースのプロセスから取得します。デプロイはlogbrew deploy で記録します。
422 で失敗します。
レスポンスは、デプロイの完了後からリクエストの時刻まで（observed_after と observed_until）に LogBrew が受け取った、同じ課題の発生事象を数えます。候補のリリースからのトレースも数えます。
absence_is_proof は常に false です。期間内に再発がなくても、修正が恒久的であることは証明されません。ステータスは、チームが証拠を受け入れた後でだけ、課題のワークフローで変更してください。
安全に復旧する
エラーレスポンスには
error、code、next、next_action が含まれます。プログラムの制御には code と next_action を使います。next は案内として表示します。コマンドとして実行しないでください。読み取りに失敗したときに、リクエストした発生事象を別の発生事象に置き換えないでください。API エラーとテレメトリ APIを参照してください。