pagerduty-oncall

PagerDuty オンコールインシデント調査ツール

認証し、エスカレーションポリシーを一覧表示して、すべてのインシデントとその詳細を取得し、オンコールチーム全体における関連性を分析します。

入力

生の引数：$ARGUMENTS

引数から次の情報を推定します：

• QUERY：調査する内容です。デフォルトは「今日のインシデント」です。期間を解釈して、--since および --until の日付（UTC の YYYY-MM-DD）を導き出します（ローカルタイムゾーンではありません）。Step 5 の日付導出表を参照してください。
• MODE：QUERY から推定します。
  • QUERY が「incident 」で始まる場合、または PagerDuty URL（pagerduty\.com/incidents/([A-Z0-9]+) に一致するもの）を含む場合 → 単一インシデントモード
  • それ以外の場合 → 一覧モード（従来の動作）
• SINCE：（任意）分析期間の開始日時（UTC ISO8601）。一覧モードでは、QUERY から導出した日付より優先されます。
• UNTIL：（任意）分析期間の終了日時（UTC ISO8601）。一覧モードでは、QUERY から導出した日付より優先されます。
• TZ_DISPLAY：（任意）レポート表示用のタイムゾーン略称（例：呼び出し元のマシンで date +"%Z" を実行した出力）。指定された場合は、システムクロックから検出する代わりに、すべてのレポートのタイムスタンプにこの値を使用します。

対象のエスカレーションポリシー

調査対象のエスカレーションポリシーのリストは、次の順序で決定されます：

1. config.json — config.json の escalation_policies 配列
2. PD_ESCALATION_POLICIES — カンマ区切りの環境変数（例："On Call, Platform Engineering On-Call"）
3. 両方が空の場合は、すべてのエスカレーションポリシーが含まれます

システム要件

• pd CLI がインストールされていること（https://github.com/martindstone/pagerduty-cli）
• 有効な PagerDuty REST API トークンを設定した環境変数 PAGERDUTY_API_TOKEN があること。重要： この変数を確認する際、未設定と判断する前に少なくとも2回確認してください。シェルコンテキストの違いにより、環境変数が未設定のように見えることがあります。値を決して公開しないでください — 存在確認のみを使用してください（例：test -n "$PAGERDUTY_API_TOKEN"）。

スクリプト

すべての解析とフィルタリングは、${CLAUDE_SKILL_DIR}/scripts/ 内のスクリプトで処理されます：

スクリプト	目的
extract-json.js	JSON 以外のテキストが含まれる場合がある pd CLI の出力から JSON を抽出します
filter-eps.js	対象名で EP をフィルタリングし、関連フィールドを抽出します
filter-incidents.js	ep-list.json のサービス ID でインシデントをフィルタリングし、フィールドを抽出します
parse-log.js	インシデントログエントリから関連フィールドを抽出します
parse-notes.js	インシデントノートから関連フィールドを抽出します
parse-analytics.js	インシデント分析データから関連フィールドを抽出します

すべてのスクリプトは stdin から読み込み、stdout に書き込みます。pd CLI の出力を最初に extract-json.js に通し、その後、適切なフィルター／解析スクリプトに通します。

出力ディレクトリ

すべての中間 JSON ファイルと最終レポートは、次の場所に保存されます：

.pagerduty-oncall-tmp/
├── ep-list.json              # Filtered escalation policies
├── incidents.json            # Incidents filtered by target EPs
├── logs/<INCIDENT_ID>.json   # Log entries per incident
├── notes/<INCIDENT_ID>.json  # Notes per incident
├── analytics/<INCIDENT_ID>.json # Analytics per incident
└── report.md                 # Final analysis report

実行

1. 接続を確認する

PAGERDUTY_API_TOKEN が設定されていることを確認します（未設定と判断する前に少なくとも2回確認してください）：

test -n "$PAGERDUTY_API_TOKEN" && echo "TOKEN_SET" || echo "TOKEN_MISSING"

トークンが設定されている場合は、認証します：

pd auth add --token "$PAGERDUTY_API_TOKEN"

認証に失敗した場合は、AskUserQuestion を使用してユーザーに知らせ、セットアップ手順が記載された PagerDuty CLI ユーザーガイド へのリンクを提示します。認証が成功するまで続行しないでください。

2. ローカルタイムゾーンを検出する

TZ_DISPLAY が指定されていない場合は、次のコマンドを実行して現在のマシンのローカルタイムゾーンを取得します：

date +"%Z"

出力を、すべてのレポートのタイムスタンプに使用する表示タイムゾーンとして記録します。

3. 出力ディレクトリを準備する

ファイルを保存する前に、出力ディレクトリ .pagerduty-oncall-tmp/ とサブディレクトリ logs/、notes/、analytics/ を作成します。

4. エスカレーションポリシーの設定を読み込む

Read ツールを使用して config.json を読み込みます。escalation_policies 配列を抽出します。

配列が空の場合は、PD_ESCALATION_POLICIES 環境変数を確認します：

test -n "$PD_ESCALATION_POLICIES" && echo "$PD_ESCALATION_POLICIES" || echo "EMPTY"

次のステップで使用する対象 EP 名のリストを作成します。両方の情報源が空の場合は、名前を渡さず（すべての EP が含まれます）。

5. エスカレーションポリシーの一覧表示とフィルタリング

以下のパイプラインで取得、JSON の抽出、対象名によるフィルタリング、保存を行います。

pd ep list --json 2>&1 | node ${CLAUDE_SKILL_DIR}/scripts/extract-json.js | node ${CLAUDE_SKILL_DIR}/scripts/filter-eps.js "EP Name 1" "EP Name 2" > .pagerduty-oncall-tmp/ep-list.json

対象の EP 名は、それぞれ個別の引数として filter-eps.js に渡します。対象名がない場合は、引数を省略します（すべての EP がそのまま通過します）。

6-ALT. 単一インシデントモード（MODE = SINGLE-INCIDENT の場合）

QUERY からインシデント ID を抽出します。

• URL から：pagerduty\.com/incidents/([A-Z0-9]+) に一致させます → キャプチャグループが ID です
• 短縮形式から：incident ([A-Z0-9]+) に一致させます → キャプチャグループが ID です

該当するインシデントを取得します。

pd rest get --endpoint "/incidents/<INCIDENT_ID>" 2>&1 \
  | node ${CLAUDE_SKILL_DIR}/scripts/extract-json.js \
  > .pagerduty-oncall-tmp/incidents.json

インシデントの JSON から以下を抽出します。

• id、incident_number、title、status、urgency
• created_at、resolved_at（未解決の場合は null）
• service.summary → SERVICE
• escalation_policy.summary → EP

同じサービスで、created_at の前後 2 時間以内に発生した関連インシデントも取得します。

pd incident list --json --statuses=open --statuses=closed --statuses=triggered --statuses=acknowledged --statuses=resolved \
  --since=<created_at minus 2h, YYYY-MM-DD UTC> --until=<created_at plus 2h, YYYY-MM-DD UTC> 2>&1 \
  | node ${CLAUDE_SKILL_DIR}/scripts/extract-json.js \
  | node ${CLAUDE_SKILL_DIR}/scripts/filter-incidents.js .pagerduty-oncall-tmp/ep-list.json \
  > .pagerduty-oncall-tmp/related-incidents.json

その後、通常どおりステップ 6（詳細の収集）とステップ 7（レポート）に進みます。

レポートの先頭には、構造化されたメタデータセクションを必ず含めます（機械処理用に UTC ISO8601 を使用）。

## Incident Metadata
- created_at: <ISO8601 UTC>
- resolved_at: <ISO8601 UTC or "ongoing">
- service: <name>
- title: <title>

続けて、ローカルタイムゾーンで人が読めるタイムラインを記載します（ステップ 7 を参照）。

6. インシデントの取得とフィルタリング（LIST モード）

QUERY から SINCE_DATE と UNTIL_DATE（UTC の YYYY-MM-DD）を導出します。重要： pd CLI の --until は排他的です。その日自体は含まれません。

SINCE と UNTIL が UTC ISO8601 タイムスタンプとして指定されている場合は、そのまま pd incident list に渡します。pd CLI の --since／--until は ISO8601 に対応しています。

pd incident list --json ... --since=<SINCE> --until=<UNTIL> ...

それ以外の場合は、エージェントのローカルタイムゾーンを使い、QUERY から SINCE と UNTIL をUTC ISO8601 タイムスタンプとして導出します。「今日」はローカルの暦日を指します。たとえば、現地時間の午前 11 時に発生したインシデントは、UTC で別の日付になる場合でも「今日」に含まれます。ローカル日の開始時刻を計算し、UTC ISO8601 に変換して pd API に渡します。

相対的な期間には、pd CLI の自然言語表現をそのまま使用します。

pd incident list --json ... --since "24 hours ago" --until "now" ...

曜日や暦上の期間には、ローカルの午前 0 時を UTC ISO8601 に変換して計算します。

# Start of local today as UTC ISO8601 (Linux / macOS)
date -d "$(date +%Y-%m-%d) 00:00:00" -u +%Y-%m-%dT%H:%M:%SZ          # Linux
date -jf "%Y-%m-%d %H:%M:%S" "$(date +%Y-%m-%d) 00:00:00" -u +%Y-%m-%dT%H:%M:%SZ  # macOS

# Start of local yesterday
date -d "$(date -d yesterday +%Y-%m-%d) 00:00:00" -u +%Y-%m-%dT%H:%M:%SZ       # Linux
date -jf "%Y-%m-%d %H:%M:%S" "$(date -v-1d +%Y-%m-%d) 00:00:00" -u +%Y-%m-%dT%H:%M:%SZ  # macOS

これらの ISO8601 値を pd incident list の --since／--until にそのまま使用します。「今日」の場合、SINCE はローカルで今日が始まる時刻の UTC ISO8601、UNTIL は省略します（デフォルトで現在時刻になります）。「昨日」の場合、SINCE はローカルで昨日が始まる時刻、UNTIL はローカルで今日が始まる時刻です。明示的な日付範囲の場合、SINCE はローカルで最初の日が始まる時刻、UNTIL は最後の日の翌日が始まる時刻です。

以下の手順で取得、JSON の抽出、ep-list.json にあるサービス ID によるフィルタリング、保存を行います。この処理は 2 つのコマンドに分けて実行してください。 filter-incidents.js はディスク上の ep-list.json を読み込むため、ステップ 5 を開始する前にファイルへの書き込みを完了させる必要があります。ステップ 4 とステップ 5 を 1 つのパイプラインに連結しないでください。

# Step 4 must be complete before running this
pd incident list --json --statuses=open --statuses=closed --statuses=triggered --statuses=acknowledged --statuses=resolved --since=SINCE_DATE --until=UNTIL_DATE 2>&1 > /tmp/pd-incidents-raw.json
node ${CLAUDE_SKILL_DIR}/scripts/extract-json.js < /tmp/pd-incidents-raw.json | node ${CLAUDE_SKILL_DIR}/scripts/filter-incidents.js .pagerduty-oncall-tmp/ep-list.json > .pagerduty-oncall-tmp/incidents.json

.pagerduty-oncall-tmp/incidents.json を読み込み、結果を確認します。配列が空の場合は、インシデントが 0 件であることを記したレポートを作成して終了します。

7. インシデントの詳細の収集

.pagerduty-oncall-tmp/incidents.json にある各インシデントの詳細を、PagerDuty API のレート制限を避けるため順番に取得します。incident_number ではなく、id フィールド（例：Q1V3O5Q3JX39LJ）を使用してください。pd CLI が受け付けるのは内部 ID のみです。

ログエントリ：

pd incident log -i <INCIDENT_ID> --json 2>&1 | node ${CLAUDE_SKILL_DIR}/scripts/extract-json.js | node ${CLAUDE_SKILL_DIR}/scripts/parse-log.js > .pagerduty-oncall-tmp/logs/<INCIDENT_ID>.json

メモ：

pd incident notes -i <INCIDENT_ID> --output=json 2>&1 | node ${CLAUDE_SKILL_DIR}/scripts/extract-json.js | node ${CLAUDE_SKILL_DIR}/scripts/parse-notes.js > .pagerduty-oncall-tmp/notes/<INCIDENT_ID>.json

分析：

pd incident analytics -i <INCIDENT_ID> --json 2>&1 | node ${CLAUDE_SKILL_DIR}/scripts/extract-json.js | node ${CLAUDE_SKILL_DIR}/scripts/parse-analytics.js > .pagerduty-oncall-tmp/analytics/<INCIDENT_ID>.json

8. 分析とレポート

Read ツールを使って、.pagerduty-oncall-tmp/ 内の保存済み JSON ファイルをすべて読み込みます。構造化された分析を作成し、Write を使って .pagerduty-oncall-tmp/report.md に保存します。

SINGLE-INCIDENT モードの場合、レポートの冒頭に、構造化メタデータブロック（PIR オーケストレーターによる機械解析用の UTC ISO8601）を記載します。

## Incident Metadata
- created_at: 2026-03-20T02:30:00Z
- resolved_at: 2026-03-20T04:15:00Z
- service: storefront
- title: High error rate on checkout

続けて、次の内容を記載します。

1. インシデント概要表 — 各インシデントの ID、タイトル、サービス、エスカレーションポリシー、ステータス、緊急度、作成日時／解決日時を現地タイムゾーンで記載（TZ_DISPLAY が指定されていればそれを使用し、指定されていない場合はシステムクロックから検出します。形式：2026-03-20 15:30 <TZ>）。期間も記載します
2. チーム横断の相関関係 — 異なるエスカレーションポリシーにまたがり、時間が重複するインシデントを特定します。連鎖的な障害や共通の根本原因の可能性があれば明記します
3. タイムライン — 全チームのインシデントを現地タイムゾーンで時系列にまとめ、活動が集中した箇所を強調します
4. 主な調査結果 — パターン、繰り返し発生するサービス、繰り返されるトリガー、またはエスカレーションポリシーの不足点を記載します
5. 推奨事項 — 分析に基づく実行可能な提案を記載します

ユーザー向けに表示するすべてのタイムスタンプは、タイムゾーン略称を付けた現地タイムゾーンを使用する必要があります。人が読むセクションでは UTC を使用しないでください。TZ_DISPLAY が指定されていればそれを使用し、指定されていない場合はシステムクロックから検出します（date +"%Z"）。

レポートの保存後、応答の最終行で、保存先を明示的にユーザーに伝えてください。

Report saved to .pagerduty-oncall-tmp/report.md