mcpField
P
production-investigation

production-investigation

github.com/honeycombioクラウド・DevOps2865 回インストール3 週間前に更新
リポジトリ

production-investigation について

production-investigationは、Honeycombで本番障害を調査するための可観測性スキルです。クエリとBubbleUpによる分析からトレース確認、仮説検証、調査結果の記録までを順に案内します。

主な機能

  1. 01SLO・アラート・クエリの確認
  2. 02遅延とエラーの特徴分析
  3. 03BubbleUpによる外れ値分析
  4. 04トレースウォーターフォールの調査
  5. 05仮説の検証と結果の記録

活用シーン

  1. 01本番環境の遅延急増の調査
  2. 02エラー急増の原因追跡
  3. 03デプロイ回帰や依存先障害の確認

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/honeycombio/agent-skill --skill production-investigation

インストール後、Claude Code で/production-investigationを入力して読み込まれたか確認します。

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

references/
bubbleup-guide.md
investigation-playbooks.md
trace-exploration.md

詳細

Honeycomb 本番環境の調査

本番環境の問題をデバッグするための構造化されたワークフローです。MCP ツールは自身の パラメータを文書化していますが、このスキルはツール呼び出しの順序と、根本原因に到達するために 結果を解釈する方法に焦点を当てています。

中核となる分析ループ

このワークフローは、observability-fundamentals スキルの中核となる分析ループ（Define → Visualize → Investigate → Evaluate）を実装しています。BubbleUp が有用な結果を返さない場合、多くの場合その問題は 計装の欠落です — 不足している属性を追加し（otel-instrumentation スキルを参照）、再試行してください。

調査ワークフロー

ステップ 1: 状況を把握する
  1. get_workspace_context → 環境とデータセット
  2. get_slos → 違反している SLO はあるか？（深刻度を判断する）
  3. get_triggers → 発火しているアラートはあるか？（範囲を絞り込む）
  4. find_queries → 以前に誰かがこれを調査したことはあるか？
ステップ 2: 問題を特徴づける

広範なクエリを実行して、問題の形状を把握します:

  • レイテンシのスパイク: P99(duration_ms)、HEATMAP(duration_ms) をサービスまたはルートでグループ化
  • エラーの急増: 失敗したオペレーションスパン（error=true）をサービス/ルート/カテゴリでカウントし、次に 別途、event.name=exception と exception.type exists を使用して例外イベント行をカウントします； サンプリングされた trace.trace_id 値を使用して、代表的なトレースを掘り下げます
  • 不明: COUNT を service.name でグループ化して、どのサービスに異常なボリュームがあるかを特定します

また get_service_map も呼び出してください — これはサービス間の P95 所要時間を示し、どの依存関係が遅いかを即座に明らかにできます。

例外データには 2 つのクエリサーフェスがあります: オペレーションの失敗はスパン（error=true、スパン ステータス、低カーディナリティの exception.slug/エラーカテゴリ）に属します；完全な例外診断は、 トレースに関連付けられた Logs API イベント行に属する場合があります。exception.* が包含するスパンに 存在すると仮定しないでください。 例外を調査するときは、まずデータセットスキーマを確認し、event.name=exception を exception.type exists および trace.trace_id exists とともにクエリし、サンプルを取得して、その trace.trace_id を get_trace(show_events=true) に渡します。レガシーなスパンイベント例外については、 name=exception と meta.signal_type=trace も確認してください；Logs API イベントは event.name/body と meta.signal_type=log を使用します。

サービスが例外を昇格させる LogRecordProcessor を使用している場合、一部の exception.* フィールドが 包含するスパンにも現れることがあります。これは明示的なクライアント側の互換機能として扱い、Honeycomb の 保証とは見なさないでください: イベント行は完全な診断のために引き続き権威であり、親スパンのフィールドが 存在しないことは例外イベントが欠落していることを意味しません。

ステップ 3: BubbleUp で差異要因を見つける

これは最も価値の高いステップです。異常を示すクエリが得られたら:

  1. クエリ結果に対して run_bubbleup を実行し、外れ値の領域を選択します
  2. BubbleUp は外れ値とベースラインの分布をすべての列にわたって自動的に比較します
  3. 分布が大きく異なるフィールドを探します

BubbleUp の結果を解釈する方法:

  • カテゴリカルフィールド（ディメンション）: 外れ値で過剰に表現されている値は原因を示します（例: deployment.version=v2.3.1 が遅いリクエストの 90% を占めるが、ベースラインでは 20% のみ）
  • 数値フィールド（メジャー）: 分布のシフトは相関するメトリクスを示します（例: db.query_duration が外れ値ではるかに高い）
  • 表面化する典型的な根本原因: デプロイバージョン、リージョン、ユーザーコホート、特定のエンドポイント、フィーチャーフラグ
ステップ 4: トレースを掘り下げる

BubbleUp が容疑者を特定したら:

  1. BubbleUp の発見を WHERE フィルターとして追加して結果を絞り込みます
  2. 代表的なトレース ID を選びます
  3. get_trace を呼び出して完全なトレースを取得します

トレースウォーターフォールで探すべきもの:

  • 親と比較して不釣り合いに長い所要時間のスパン（ボトルネック）
  • 並列化できる逐次的なスパン（N+1 クエリパターン）
  • エラースパン — スタックトレースについてスパンイベントを確認する
  • 子スパン間のギャップ（計装の欠落またはアイドル待機）
  • サービスの境界（トレースがサービスを横断する箇所）
ステップ 5: 仮説を検証する

BubbleUp + トレース分析から仮説を立て、次のように確認します。

  • 疑わしい原因でフィルタリングしたクエリ
  • それを除外したクエリ（対照として）
  • メトリクスが乖離していれば、原因を特定できたことになります
ステップ 6: 調査結果を記録する

create_board を次の内容で呼び出します。

  • 根本原因を要約したテキストパネル（Markdown）
  • 問題を特定した主要なクエリ実行 PK
  • 該当する場合は関連する SLO

調査パターン

レイテンシの急増

まず HEATMAP → 遅い領域を BubbleUp → 遅いリクエストをトレース → フィルタリングしたクエリで検証

エラーの急増

失敗した操作スパンをサービス/ルート/カテゴリ別にカウント → Logs API の例外イベントを event.name=exception と exception.type でカウント → trace.trace_id をサンプリング → get_trace(show_events=true) → フィルタリングしたクエリで検証。例外検索として親スパンの exception.message だけを使用しないでください。

デプロイによるリグレッション

deployment.version 別にグループ化した P99 → 新バージョンと旧バージョンを比較する BubbleUp → 新バージョンからトレース → 検証

依存関係の障害

get_service_map → 遅い依存関係の P99 → ユーザーへの影響を測定するリレーショナルクエリ（any.service.name） → 影響を受けたリクエストをトレース

道筋を守る

次のいずれかを推論していることに気づいても、とにかくワークフローに従ってください。

  • 「原因は明らかだ、BubbleUp は省略できる」 — BubbleUp は、後から振り返れば明らかに思えるものの最初の推測ではなかった原因を日常的に浮かび上がらせます。また、見逃してしまう二次的な原因も捉えます。
  • 「デプロイの問題だとすでにわかっている」 — ステップ 5 で検証してください。インシデント中は確証バイアスが最も強くなります。疑わしい原因を含めたクエリと除外したクエリの両方を実行してください。
  • 「トレースで確認できた、検証は不要だ」 — 単一のトレースは逸話にすぎません。検証クエリは、1 件のリクエストだけでなくすべてのトラフィックでパターンが成り立つことを証明します。
  • 「これは単純な問題だ、ワークフロー全体はやりすぎだ」 — ワークフローは数分で終わりますが、インシデント中の誤った診断は数時間のコストになります。

結果が空または不明瞭な場合

  • 結果がない: find_columns でフィールド名を確認し、時間範囲を広げ、環境/データセットを確認する
  • BubbleUp がシグナルを示さない: 別の時間選択を試す、異常をより明確に分離するためにフィルターを追加する、または別の計算を選択する
  • トレースにスパンがない: サンプリング、インストルメンテーションの欠落、または環境間でのトレース分割

追加リソース

参照ファイル
  • ${CLAUDE_PLUGIN_ROOT}/skills/production-investigation/references/investigation-playbooks.md — レイテンシの急増、エラーの急増、デプロイによるリグレッション、依存関係の障害、SLO バジェットの消費、ヘルスチェックに関するステップバイステップのプレイブック
  • ${CLAUDE_PLUGIN_ROOT}/skills/production-investigation/references/bubbleup-guide.md — BubbleUp の詳細な使用方法: 選択タイプ、時間指定、ページネーション、結果の解釈
  • ${CLAUDE_PLUGIN_ROOT}/skills/production-investigation/references/trace-exploration.md — トレース構造、get_trace のパラメータと表示モード、ウォーターフォール分析、スパンイベントとリンク
相互参照
  • コア分析ループの概念的基礎については、observability-fundamentals スキルを参照してください
  • クエリ構築パターンについては、query-patterns スキルを参照してください
  • 調査中の SLO/トリガーのコンテキストについては、slos-and-triggers スキルを参照してください

コメント

Markdown 対応