ops-investigate-alert

アラートを調査する

メトリクス、ログ、トレース、関連するサービスコードを取得して、監視アラートを調査します。症状から根本原因の仮説を導き出します。

使用するタイミング

• 監視アラートが発生し、その原因を把握する必要があるとき
• オンコールエンジニアが、構造化された調査の出発点を必要としているとき
• アラートが頻発し、対応が必要か誤検知かを判断したいとき

手順

1. 監視 MCP の利用可否を確認する

利用可能な監視 MCP サーバーを確認します。監視プラットフォーム（Datadog、Grafana、PagerDuty など）に関連する mcp__* ツールを探してください。

推奨： Datadog MCP — モニター、メトリクス、ログ、トレース、イベントを 1 つのプラットフォームで扱えるため、最も充実した調査機能を提供します。

利用可能な監視 MCP がない場合は、次の内容で停止します。

エラー：監視 MCP サーバーが見つかりません。 このスキルでは、アラートデータを照会するために監視 MCP が必要です。 推奨：Datadog MCP を Claude Code の MCP 設定に追加してください。

次のオプションツールも確認します。

• GitHub CLI（gh） — 関連するサービスコードや最近のデプロイを確認するため
• Kubernetes MCP — Pod の状態を確認するため

利用可能なツールを記録し、それに応じて調査方法を調整してください。

2. 入力を解析する

監視プラットフォームの URL の場合：

• URL からモニター／アラート ID を抽出します
• 手順 3 に進みます

アラート名または説明の場合：

• 利用可能な監視 MCP を使ってモニターを検索します
• 複数見つかった場合は一覧を表示し、どれを調べるかユーザーに確認します
• それでも見つからない場合は、ユーザーに詳細を尋ねます

3. モニターの詳細を取得する

モニターの設定と現在の状態を取得します。

• モニター名、種類、クエリ
• 現在の状態（OK / Alert / Warn / No Data）
• 最後にトリガーされた時刻
• 影響を受けるサービスと環境
• アラートメッセージとランブックのリンク（ある場合）

4. メトリクスを照会する

アラートをトリガーしたメトリクスを取得します。

• 時間範囲： トリガーの 1 時間前から現在まで（または解決後 1 時間まで）
• 確認項目： 異常、急増、低下、横ばい、しきい値の超過
• モニターのしきい値と比較して、深刻度を把握します

5. ログを分析する

影響を受けるサービスと環境のログを検索します。

• 時間範囲： 手順 4 と同じ
• 確認項目： エラー、スタックトレース、タイムアウト、接続失敗、通常と異なるパターン
• 重大度で絞り込む： まず ERROR と WARN のレベルを確認し、必要に応じて範囲を広げます

6. トレースを確認する（利用可能な場合）

分散トレースを検索します。

• サービス名と時間範囲で絞り込みます
• 確認項目： 遅いスパン、エラースパン、通常と異なるレイテンシ分布、失敗している下流呼び出し

7. インフラストラクチャを確認する（利用可能な場合）

Kubernetes MCP またはクラウド CLI が利用可能な場合：

• Pod の状態、再起動回数、OOM キル
• アラート発生時刻前後のリソース使用量（CPU、メモリ）
• 最近のデプロイイベント

利用できない場合（VPN、権限など）は、その旨を記録し、利用可能なデータを使って調査を続けます。

8. 最近のコード変更を確認する（gh が利用可能な場合）

gh auth status

認証済みの場合：

1. サービス名からリポジトリを特定します
2. 最近のリリース／タグを確認して、現在デプロイされているものを把握します。

   gh api repos/<org>/<service>/tags --jq '.[0:3] | .[] | {name: .name, sha: .commit.sha}'
   

3. 直近 2 つのタグ間の差分を確認して、最新リリースでの変更を把握します。

   gh api repos/<org>/<service>/compare/<prev-tag>...<latest-tag> --jq '.commits[] | {sha: .sha[:7], message: .commit.message, author: .commit.author.name}'
   

4. エラーの種類に応じて関連するコードを確認します。
   • HTTP エラー → ルートハンドラー、ミドルウェア
   • DB エラー → クエリコード、コネクションプーリング
   • タイムアウトエラー → 外部呼び出しクライアント、タイムアウト設定
   • OOM → メモリを大量に使用する処理、上限のないコレクション

タグを作成、プッシュ、変更しないでください。

9. 調査の概要を提示する

## Alert Investigation: <Alert Name>

**Status:** <OK / Alert / Warn / No Data>
**Service:** <service> | **Env:** <env>
**Triggered:** <timestamp> | **Duration:** <duration or "Ongoing">

### Metrics
<key observations — spike at X time, value Y vs threshold Z>

### Logs
<key log lines or patterns — N errors of type X, stack trace summary>

### Traces
<latency or error observations — if available>

### Infrastructure
<pod status, resource usage — if available>

### Recent Code Changes
<commits near trigger time, or "No recent changes" or "gh CLI not available">

### Root Cause Hypothesis
<best assessment based on available data — be explicit about confidence level>

### Recommended Next Steps
1. <most impactful action>
2. <secondary action>
3. <what to check if hypothesis is wrong>

データから結論を出せない場合は、その旨を明示し、手動で確認する項目（例：k8s への VPN 接続、DB への直接クエリ、チームへの確認）を提案します。

対話スタイル

• 推測ではなくデータを先に示します。仮説を立てる前に、メトリクス／ログ／トレースを提示してください
• 確信度を明確にします。「確信度が高い」「可能性が高い」「結論が出ない」などと示してください
• 手順でデータが得られなかった場合は、その旨を伝えて次に進みます。憶測で補わないでください

ルール

• ステップ 3〜5（モニタリング、メトリクス、ログ）は絶対に省略しないでください。これらは調査の中核です
• ステップ 6〜8（トレース、インフラ、コード）は、利用可能なツールに応じて省略できます
• 調査中にタグやデプロイを作成、プッシュ、変更しないでください
• 結論が出ない場合でも、必ず最後に構造化された要約を提示してください

出力

調査の要約は、会話内に直接提示してください。ユーザーから保存を依頼されない限り、ファイルには出力しないでください。