障害の発生を知らせる呼び出しをきっかけに過去のポストモーテムを検索し、症状の近い障害の原因・効いた暫定対処・再発防止策の進み具合を当番のエンジニアに示す

処理の起点を決める

PagerDuty の Webhook で、障害が新しく起きたことを受け取ります。 PagerDuty の Webhook（V3）は、サービス・チーム・アカウントのいずれかを範囲にして購読でき、triggered は障害が新しく作られたときに送られるとされています。購読は範囲ごとに10件までです。運用のチームの範囲で1つ購読すれば足ります。

当番がメモを書いたときにも、もう一度動かします。 annotated のイベントで、当番が障害に書いたメモを受け取ります。呼び出しの直後はアラートの名前しか分かりませんが、数分後には当番が「DBの接続数が上限」のような症状をメモに書きます。 その言葉で探し直すと、当たる報告書が変わります。2回目以降は、前の投稿のスレッドに返信する形にします。

Webhook の送り主は署名で確かめます。 V3 の購読は x-pagerduty-signature のヘッダーを付けて送り、購読を作ったときに検証用の秘密の値が渡されます。確かめない受け口は、誰からでも検索と投稿を動かせてしまいます。

索引の更新は別に動かします。 ポストモーテムが承認されたとき、その1件だけを索引に入れ直します。再発防止策のチケットの状態は索引に入れず、検索のたびに引きます。 索引に入れると、状態が古くなります。

入力データを集める

質を決めるのは、ポストモーテムの「暫定対処」の書き方です。 タイムラインの中に埋もれていると、どの行が止め方なのかを機械で見分けられません。 ひな形に「暫定対処」の見出しを置き、何をしたか、いつしたか、効くまでに何分かかったかを書く決まりにします。

再発防止策には、チケットの番号を必ず書かせます。 番号の無い再発防止策は、状況を引けません。過去の報告書で番号の無いものは、最初の準備として書き足します。

データの取得方法を決める

ポストモーテムは、承認されたものだけを索引に入れます。 書きかけの報告書には、推測の原因や、あとで取り消された対処が残っています。承認の前は、検索の対象にしません。

サービスの絞り込みは、依存する先まで広げます。 決済のサービスで応答が遅れていても、原因はその下のデータベースや認証のサービスにあることが多くあります。障害のサービスだけで絞ると、原因の側のサービスで書かれた報告書が出ません。

新しさは、絞り込みではなく点数で効かせます。 OpenSearch の function_score は、返す文書を変えずに順位を変えるものです。その中の減衰関数（gauss・exp・linear）は、数値・日付・位置の項目について、起点からの距離で点数を下げます。 日付の項目では起点を省くと now になり、offset の内側は点数1、scale と offset を足した距離で点数が decay（既定0.5）になります。

古い報告書を消さずに下げるのは、構成が変わっても原因の型は残るからです。 5年前の報告書の「接続プールの枯渇」は、いまの構成でも起きえます。

減衰関数には注意が1つあります。 公式のドキュメントでは、その項目が無い文書には点数1が返るとされています。発生日を入れ忘れた報告書は、新しさで下がらず、いちばん新しい報告書と同じ扱いになります。取り込みのときに発生日の無い報告書を止めます。

AIへ渡す前に整形する

1. 見出しで段落に分ける … 概要、影響、検知、タイムライン、暫定対処、根本原因、再発防止策で分け、段落ごとに種類を付けます
2. アラートの名前を取り出す … 報告書の「検知」の段落から、監視のアラートの名前を取り出し、keyword の項目に入れます
3. タイムラインから止め方を拾う … 「暫定対処」の見出しが無い古い報告書は、タイムラインの中の「回復」「復旧」の直前の行を暫定対処の候補として印を付けます
4. 数値と識別子を外す … ホスト名、IPアドレス、利用者のIDは、索引に入れる前に消します
5. 障害の側の言葉をそろえる … PagerDuty の題名に入る監視の定型の文言（しきい値や時刻）を外し、アラートの名前とサービスだけを残します

2番目を軽く見ないでください。 当番が最初に持っている情報は、アラートの名前だけのことが多くあります。報告書の本文は人の言葉で書かれ、アラートの名前はほとんど出てきません。「検知」の段落からアラートの名前を取り出して完全一致で探せるようにすると、最初の数分で当たる報告書が増えます。

AIに処理させる

検索そのものは OpenSearch が行います。 問い合わせは、たとえば次の形になります。

{
  "query": {
    "function_score": {
      "query": {
        "bool": {
          "filter": [
            { "terms": { "services": ["{障害のサービス}", "{依存する先のサービス}"] } }
          ],
          "should": [
            { "terms": { "alert_names": ["{アラートの名前}"], "boost": 3 } },
            { "match": { "text": "{題名と当番のメモ}" } }
          ],
          "minimum_should_match": 1
        }
      },
      "functions": [
        { "gauss": { "occurred_on": { "offset": "365d", "scale": "730d", "decay": 0.5 } } }
      ]
    }
  }
}

アラートの名前の一致を、言葉の一致より重く置きます。 アラートの名前が同じなら、監視が同じ壊れ方を同じ場所で見つけたということで、言葉が似ているより強い手がかりです。言葉の一致は、アラートの名前が当たらない障害の受け皿にします。

当たった段落は、報告書ごとにまとめてから渡します。 同じ報告書の「根本原因」と「暫定対処」が別々に当たったら、1つの報告書として扱い、再発防止策の段落も必ず添えます。 渡すのは点数の上位5件の報告書までで、その中から生成AIに3件まで選ばせます。

生成AIにさせるのは、当たった報告書ごとに4つの見出しで並べることだけです。

2行目が、この構成の線引きです。 過去に効いた対処を、いまの環境でそのまま打てる手順のように書くと、当番は確かめずに実行します。 報告書が書かれた後に構成が変わっていれば、同じ操作が別の結果を招きます。手順は手順書の側に任せ、ここでは「何をしたか」までにします。

指示内容を固定する

あなたはSREチームで、いま起きている障害に近い過去のポストモーテムを、
当番のエンジニアのために整理する立場です。
渡した検索結果（報告書の段落）だけを根拠にしてください。

【いまの障害】題名：{title}／サービス：{services}／アラート：{alerts}
【当番のメモ】{notes}
【再発防止策の状態】報告書ごとに、チケットの状態を渡します。
  done ......... 完了
  open ......... 未着手または対応中
  wont_do ...... 見送り

【やること】
報告書ごとに、次の4つを短く書いてください。
1. 原因：根本原因の段落から、何が起きていたか
2. 止め方：暫定対処の段落から、何をして、効くまでに何分かかったか
3. その後：再発防止策と、渡した状態
4. 今回との違い：いまの障害の情報と、報告書の症状の違い

【厳守事項】
- 検索結果に書かれていないことを書かないでください。
  効くまでの時間が書かれていなければ「記載なし」としてください。
- 再発防止策の状態は、渡した値をそのまま使ってください。
  報告書の文面から完了したかどうかを判断しないでください。
- 実行するコマンドや設定の値を書かないでください。
  「接続プールの上限を引き上げた」のように、何をしたかまでにしてください。
- 今回の原因がどれかを断定しないでください。
- 近くない報告書は、無理に関連付けず「関連が薄い」と書いてください。
- 全体で、最も近い報告書から順に3件までにしてください。

「渡した値をそのまま使う」を明記しないと、報告書の文面から状態を推測します。 報告書の再発防止策は「〜を導入する」と書かれ、生成AIはこれを済んだことのように読みます。 状態はチケットから引いた値だけを使わせます。

「3件まで」にしているのは、障害の最中に読まれるからです。 10件並べても、当番は上の2〜3件しか読みません。読まれない候補で投稿を長くしないことが、そのまま速さになります。

出力形式を固定する

生成AIへは、検索結果のブロックで渡します。 公式のドキュメントでは、search_result のブロックに source・title・content を入れると、自社の文書を引用付きで答えます。 source に報告書のURL、title に障害の題名と発生日、content に段落を1つずつのテキストブロックで入れます。引用はテキストブロックの単位で付き、引用の設定はリクエストの中のすべての検索結果でそろえる必要があります。

返った文章と引用から、Slack に投稿する前に次の形に組み立てます。

{
  "incident_id": "",
  "matches": [
    {
      "postmortem_url": "",
      "title": "",
      "occurred_on": "",
      "services": [],
      "cause": { "text": "", "cited_text": "" },
      "mitigation": { "text": "", "minutes_to_effect": null, "cited_text": "" },
      "followups": [
        { "ticket": "", "status": "done | open | wont_do", "summary": "" }
      ],
      "difference": ""
    }
  ],
  "searched_with": { "services": [], "alerts": [], "notes_used": true }
}

1つ目の理由は、followups の状態を見出しにできることです。 open の再発防止策がある報告書は、投稿の先頭に「未完了の再発防止策あり」と出します。 今回の障害がその続きである可能性を、当番が最初に見ます。

2つ目は、searched_with で何を使って探したかを残せることです。 当番は「アラートの名前だけで探した結果」か「メモの症状まで使った結果」かを見分けられます。

Slack への投稿は、障害のチャンネルのスレッドにします。chat.postMessage で、親の投稿の ts を thread_ts に入れると返信になります。 本文は text を4,000文字以内に収めます。

システムへ連携する

Slack へは、障害ごとに投稿の数を絞ります。 chat.postMessage には特別な流量の制限があり、1つのチャンネルにはおおむね1秒に1件とされています。メモのたびに新しい投稿を重ねず、同じスレッドへの返信にまとめます。

チケットへは書き込みません。 再発防止策が止まっていると分かっても、優先度を上げるかは障害の後の振り返りで決めます。

人が確認する

1. 根拠の確認（当番） … 投稿の引用から報告書を開き、原因と止め方の段落を確かめます
2. 今回との違いの確認（当番） … 「今回との違い」に書かれた点を、監視の画面で確かめます
3. 対処の判断（当番と指揮者） … 過去の止め方を参考に、今回の対処を決めます。手順は手順書で確かめます
4. 当たり外れの記録（当番） … 障害の後、投稿の候補が役に立ったかをスレッドに印で残します

目安は、1件あたり12分です。 根拠の報告書を2件ほど開き、止め方の段落を読み、監視の画面と比べる時間です。全部の候補を読む必要はありません。

4番目を省かないでください。 当たり外れの印は、検索の重みとアラートの名前の取り出しを直す材料になります。

例外に対処する

最後の行が、障害の最中には大事です。 整理を待つより、題名とURLだけでも先に出るほうが当番の役に立ちます。

記録を残す

• 受け取った Webhook の内容と、署名の確認の結果
• 検索に使ったサービス・アラートの名前・メモ、返した報告書と点数
• 引いたチケットの状態と、引いた時刻
• 投稿した本文と引用、当番が付けた当たり外れの印
• 障害の後のポストモーテムで、この投稿の候補が原因と同じだったか

チケットの状態を引いた時刻を残すのは、後で状態が変わるからです。 障害の最中に「未完了」だったものが翌日に閉じられても、当時どう見えていたかを振り返りで確かめられます。

最後の行は、次の改善の材料になります。 当たった候補と原因が一致した割合を、四半期ごとに数えます。