夜間・休日の監視アラートに、運用手順書と過去の障害対応記録から該当する手順と判断の目安を探し、当番の担当者へ根拠付きで返す

処理の起点を決める

起点は、アラートポリシーが発報したことです。 Cloud Monitoring の通知の送り先に Pub/Sub のトピックを加え、中継プログラムがそこから通知を受け取ります。当番への通常の通知は、これまでの送り先にそのまま残します。 中継プログラムが止まっても、アラートそのものは当番に届きます。

対象は、夜間・休日に当番へ届くアラートに限りません。 日中のアラートにも同じ回答を付けます。日中に回答の質を見ておかないと、夜間に初めて外れに気付くことになります。 最初の1か月は日中だけに付け、当番の評価を見てから夜間に広げます。

通知は、発報のたびに1件ずつ処理します。 まとめて処理する理由がありません。ただし、同じ障害の続報と復旧の通知は、新しい検索の対象にしません。 通知に含まれる障害の識別子で、すでにスレッドがあるかを確かめます。

入力データを集める

質を決めるのは、説明文の欄の「手順書の番号」と、メタデータの「現行／廃止」です。 手順書の番号が通知に入っていれば、検索の精度に頼らずに正しい手順書へたどり着けます。 「現行／廃止」が無いと、第3章の（b）の古い手順書がそのまま回答に使われます。

振り返りの記録に「関係したアラートポリシー」を付けるのは、後から効いてきます。 同じアラートの過去の判断を、名前の揺れに関係なく引けるようになります。新しく書く振り返りから付け始め、過去分は件数の多いサービスから順に付けます。

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

アラートポリシーの説明文の欄に、手順書の番号とサービス名を書きます。 説明文には変数を使えるとされ、${policy.display_name}（ポリシー名）、${condition.display_name}（条件名）、${resource.label.KEY}（リソースのラベル）、${policy.user_label.KEY}（ポリシーに付けたラベル）などが使えます。ポリシーのラベルに runbook_id と service を持たせ、説明文でそれを書き出すのが、ポリシーごとに書き分けずに済む方法です。説明文には最大3つまでリンクも付けられるとされており、手順書のURLを入れておくと当番がすぐ開けます。

手順書と振り返りは、Cloud Storage に置いてデータストアに取り込みます。 文書ごとのメタデータは、JSONL の各行に id、structData（または jsonData）、content.mimeType、content.uri を書いた形式で渡します。

絞り込みに使う項目は、スキーマの設定で索引可能にします。 絞り込みの式は runbook_id: ANY("RB-0123") や service: ANY("billing") AND status: ANY("current") のように書けます。日付の項目には比較の演算子も使えるとされています。

取り込み直しは、手順書を更新した日に行います。 Cloud Storage からの定期的な取り込み（1日、3日、5日ごと）もありますが、元のデータの権限の制御が反映されないとされています。手順書と振り返りは運用チームだけが見るものなので、このデータストア自体を運用チームだけが使えるようにし、他部門の文書は入れません。

AIへ渡す前に整形する

1. 手順書を1事象1文書にそろえる … 1つのページに複数の事象が書かれているものは分けます
2. 現行／廃止を付ける … 管理表から状態を付け、置き換えられた旧版には「廃止」を付けます
3. 見出しを整える … 「確認の手順」「対応の手順」「上位へ連絡する条件」の見出しをそろえます
4. 振り返りから個人と顧客の情報を除く … 担当者の氏名、顧客企業の名前、問い合わせの文面を伏せます
5. 認証情報を除く … 手順書に書かれたパスワード、トークン、接続文字列が無いかを確かめて消します
6. 文書の分割を設定する … データストアを作るときに分割（チャンク）を有効にし、見出しを各断片に付けます
7. パーサーを選ぶ … 書き出したHTMLやDOCXはレイアウトパーサーで、表と見出しを保ったまま読みます

6番目は、データストアを作る前に決めます。 分割はデータストアの作成後に有効・無効を切り替えられないとされています。断片の大きさは100〜500トークンの範囲で指定でき、includeAncestorHeadings を有効にすると、題名と各階層の見出しが断片に付くとされています。手順書の「対応の手順」の断片だけが返ってきても、どの事象の手順かが分かるようにするためです。

5番目を省かないでください。 手順書には、管理画面へのログインの方法がそのまま書かれていることがあります。検索に入れた時点で、回答の文に出てくる可能性があります。 認証情報は手順書から外し、秘密情報の管理の仕組みを指す書き方に直します。

AIに処理させる

させるのは、アラートの内容に合う手順書の手順と、過去の記録にある判断の目安を、出典を付けて短くまとめることです。

右端の列を混ぜないことが、この構成で最も大事な点です。 振り返りの記録には、そのときだけの応急処置（一時的な設定の変更、手作業での再実行）が書かれています。それが「手順」として返ると、当番は手順書にない操作を正式な手順だと思って実行します。 手順は手順書だけ、目安は記録だけから取らせます。

answer メソッドの設定は次のようにします。

2行目が最も起きやすい失敗です。 回答を作るモデルは、データベースの接続数が足りないときの一般的な対処を知っています。それを使って答えると、自社の構成では別の影響が出る操作が、手順のように並びます。 検索結果の文書だけで答えることを、指示で明記します。

指示内容を固定する

answer メソッドの preamble に、次の指示を入れます。

あなたは夜間・休日にシステムの監視アラートを受けた当番の担当者に、
運用手順書と過去の障害対応記録から、該当する手順と判断の目安を返します。
読むのは深夜に起こされた当番で、あなたの回答を見て手順書を開きます。

【答え方】
1. 最初に、該当する手順書の番号と題名を書いてください。
2. 次に、手順書の「確認の手順」から、最初に確かめることを3つまで書いてください。
3. 過去に同じアラートが鳴ったときの記録があれば、
   そのとき待ったのか、対応したのか、誰に連絡したのかを、記録の番号と日付を付けて書いてください。
4. 手順書に「上位へ連絡する条件」があれば、そのまま書いてください。

【厳守事項】
- 検索結果の文書に書かれていることだけで答えてください。
  一般的な知識で手順を補わないでください。
- 手順は運用手順書からだけ書いてください。
  障害対応の記録にある操作を、手順として書かないでください。
  記録にある操作は「過去にこう対応した」とだけ書いてください。
- 数値の基準（しきい値、待つ時間、件数）は、文書に書かれているとおりに書いてください。
- 原因を断定しないでください。「原因の候補」も書かないでください。
- 待つべきか、対応すべきか、誰かを起こすべきかの結論を書かないでください。
- 廃止と書かれた手順書を使わないでください。
- 該当する手順書が見つからないときは、
  「該当する手順書が見つかりません。上位の担当者の連絡先を確認してください」とだけ書いてください。
- 手順書と記録で記載が違う点があれば、両方を書き、
  「手順書と過去の記録の記載が異なります」と明記してください。
- 人の氏名、顧客の名前、パスワードやトークンを書かないでください。

「記録にある操作は『過去にこう対応した』とだけ書く」が、この指示の要です。 禁じるだけでは、記録の操作が手順のなかに混ざります。書き方まで決めると、読む当番の側で「これは手順ではない」と区別できます。

検索の文は、中継プログラムが通知から組み立てます。 例えば「サービス：billing、ポリシー：DB接続数の上限に近い、条件：接続数が上限の90％を5分超える、リソース：本番のデータベース。該当する手順と過去の対応を教えてください」のように、通知の項目を決まった順に並べます。

出力形式を固定する

answer メソッドの応答を、中継プログラムが次の形に整えて、チャットと記録に渡します。

{
  "incident_id": "",
  "policy": "",
  "service": "",
  "lookup": "runbook_id | service_search | none",
  "status": "answered | skipped | no_runbook",
  "skipped_reasons": [],
  "answer_text": "",
  "runbook": { "id": "", "title": "", "status": "current", "uri": "" },
  "past_records": [
    { "id": "", "date": "", "decision": "", "uri": "" }
  ],
  "conflict": false,
  "feedback": "useful | partly | wrong | none"
}

1つ目の理由は、lookup で引き方を残せることです。 手順書の番号で引いた回答と、サービス名で検索した回答では、外れる確率が違います。月次の集計で、番号が無いポリシーを洗い出す材料になります。

2つ目は、runbook を回答の文と別に持てることです。 中継プログラムは、出典の中に手順書が1つも無い回答を no_runbook に書き換え、手順の部分を表示せず、過去の記録だけを「参考」として出します。 廃止の手順書が出典に入っていれば、その出典を除きます。

3つ目は、feedback で回答の質を測れることです。 当番がスレッドで選んだ評価を残し、「外れ」の多いポリシーから手順書と説明文を直します。

チャットには、次の形で投稿します。

システムへ連携する

監視の仕組みにもサーバーにも、書き込みません。 中継プログラムが持つのは、通知を読む権限と検索を呼ぶ権限と、チャットに投稿する権限だけです。自動で再起動する仕組みを足したくなっても、この構成の中には作りません。 夜間に誤った手順で操作が走ると、1件のアラートが障害に変わります。

人が確認する

当番は、回答を読んだあと必ず手順書の原文を開きます。 回答は「どの手順書か」と「過去に何があったか」を短く示すもので、手順の細部と注意書きは原文にしかありません。

1. 手順書の番号と題名を確かめる … アラートの事象と合っているか、廃止でないかを見ます
2. 原文で確認の手順を読む … 回答の3つの要点ではなく、原文の手順に沿います
3. 過去の対応を参考にする … 記録の日付が古ければ、その後に構成が変わっていないかを疑います
4. 初動を決めてスレッドに書く … 待つ／対応する／上位を起こすを当番が決めます
5. 回答を評価する … 役に立った／一部／外れの3択を選びます

3番目を軽く見ないでください。 2年前の記録で「待てば戻った」アラートが、構成を変えたあとも同じとは限りません。記録の日付を回答に必ず出させているのは、このためです。

目標は、1件6分です。 回答と手順書を読んで初動を決めるまでで、探す時間をなくし、読む時間と判断の時間だけを残します。

例外に対処する

5行目は、大きな障害のときに効きます。 1つの原因で十数個のアラートが同時に鳴ると、それぞれに回答を付けたくなりますが、当番が最初に知りたいのは「どこから見るか」だけです。 同じサービスのものはまとめ、他は件数だけを示します。

記録を残す

• アラートの通知のJSONの全文と、受け取った日時
• 中継プログラムが組み立てた検索の文と、使った絞り込みの式
• answer メソッドの応答の全文（回答、出典、回答しなかった理由）
• チャットに投稿した内容と、当番が付けた評価
• 当番がスレッドに書いた初動の判断
• そのとき参照した手順書の版と、現行／廃止の状態

最後の行は、振り返りのときに効きます。 障害の振り返りで「なぜその手順で動いたか」を確かめるとき、手順書がその後に直されていると、当時の回答の根拠が分かりません。