障害報告書を書こう！ #QiitaEngineerFesta2022

担当しているITサービスなどに何かしらのインシデントや障害が発生した時に、対処後のアクションとして報告書を提出して事象の内容を報告（レポート）する場合がある。
提出先は会社の偉い人だったりクライアントだったり。場合によってはユーザー向けに発表したり。事の顛末を報告して「今後同様のことを起こさないように努力します、ごめんなさい」をするのだ。どのように再発防止の努力するのかを書くものでもある。

主にクライアント向けのビジネス内容ではあるが、自分が使っているテンプレパターンを共有するので参考にしてもらえればと思う。¹

全般的なポイント

心得のようなもの。次の点は留意してて欲しい。

淡々と冷静な説明をこころがける

当然のことながら事実は脚色しない。無駄な修飾も要らない。客観的な事実を簡潔に述べる。
例： ❌「一生懸命頑張って対応したが…」 ❌「寝ないで対応したが…」 ❌「本当の原因は…」

できるだけ数字で説明する

具体的な数字をできるだけ用いた説明をする。
例：　❌「大勢のユーザーに影響が出た」 ❌「サービスに深刻な影響を及ぼした」　⭕️「MM月DD日01:30頃〜5:15頃の間にログインを試みた５,９６３人のユーザー」）
分からないところは「現在調査中」などとし、追って報告するなどの調整をしよう。

報告の内容でもっともプライオリティが高いのは影響範囲

原因と対策はその次だと思って構わない。
報告の時点で完全に分かっていなくても、分かっている範囲で影響範囲は述べること。
例：（まず報告しなければならない内容として） ❌「プログラムの実装で発生したバグによりログインエラーが発生した」 ⭕️「およそ３時間の間約1000人のユーザーがログインできない状態が発生していた」

エンジニアの人が書くと職業柄どうしても原因に重きを置きがちな傾向にはなる。この報告で重要なのはビジネス上どのくらいインパクトを及ぼしたか（及ぼすか）という、報告を受けた人たちがそれを考えるための情報である。サービスのブランディングや信用、経済的損失（お金の問題）などに関わるからだ。

「です・ます」調や「だ・である」調でOK

クライアントなどとの関係から「ございます」「いただいた」といった丁寧・謙譲語を書いてしまうかもだが、シンプルにですます調（です、でした）、またはだ・である調（した、であった）で問題ない。
原因説明や対策は「です・ます」調、概要や時系列など事実説明では「だ・である調」が良いかなと思っている。

体言止めは使わない

「〜を計画、」「〜を確認、」「〜を連絡、」と書いたりすることはないだろうか。なんとなく言わんとしていることはわかるが、した、のか、する、のか曖昧で読み手が判断に迷う場合がある。
時系列で経緯を説明する場合などでは前後関係が微妙にわからなくなる場合もある。体言止めにならないように注意しよう。

原因や改善対象は個人に帰するものではない

故意でやってない限りは、誰か一個人を原因とすることはない。
チームで分担して開発している以上、誰か担当の人間の行為が事象のトリガーとなる場合があるが、だからと言ってその人を原因とすることはない。
背景、開発手法、運用方法などから、何が原因かどうやって解決していくかなどをポストモーテムなどを通してチームやプロジェクトなど考えていくことになる。

「意識」や「注意」では対策にならない

心得というよりプラクティスな内容であるが、改善策や再発防止策として「意識」や「気持ち」を変えるだけでは対策にならない。ヒューマンエラーの問題解決は人に依存しないところで解決すべし。
フローを変える、環境を見直す、手順を見直す、（ツールなどで）機械的に解決する、といった具体的な対策をチームやプロジェクトで考えよう。
例：❌「同様の問題を起こさないよう開発者の意識を高める」 ❌「十分注意して作業する」 ⭕️「設計の段階でセキュリティのレビューを入れる」 ⭕️「一見して分かるように本番環境のUIの背景色を変える」 ⭕️「手順に作業監督者のダブルチェックと指差し確認を加える」 ⭕️「CIツールを導入してマージ前に自動的にテストをするようにする」
ただし、教育や啓発といった目的で、意識や認識を高める施策活動を他の対策と併せて実施するのはアリ。

必ずレビューを経る

SLAや補填・補償内容など、各契約に関わることもあるので、他の人（マネージャーなど）のレビューを経よう。

書く内容

フォーマットなどは適宜必要に合わせていただく。
PDF化などしてどこかへ提出する場合ヘッダなどに文書番号などを入れるかもしれないが、それも会社の方針などに合わせてもらえればである。

項目	どんな内容を書くか
（導入部分）	一言二言謝罪の言葉を述べ、これから事象内容について説明する導入文章を書こう。なおここは謝罪の部分であるので丁寧な口調を使う。
概要	事象の概要を書く。簡単な5W1H的説明を述べる。次項の影響範囲も含めて、サマリー表などを横に書き添えるのも良いアイディア。
発生期間	障害が発生した期間を記す。 ”YYYY年MM月DD日 hh:mm〜YYYY年MM月DD日 hh:mm”形式が良いだろう。時間は”hh:30頃”といった形でも良いが、SLAなどに関係する場合は正確に書く。
影響範囲	障害の影響を受けた場所や、ユーザーの数、その条件などを書く。その時点でわかっている範囲でできるだけ具体的に説明する。数字が変化する可能性があればその旨も言及する。場合によってはユーザー数などは補填・補償に関係するので正確な数字が求められる。
経緯	事象の発生とその対処、完了までの一連の流れを時系列で説明する（完了していないのであれば現時点まで）。 ”MM/DD hh:mm 説明"　という書き方。表にしても良い。誰と誰がどうやりとりしたかといった自分たち以外のステークホルダー含めて、対応や連絡・報告のアクションの流れも記述する。
原因	直接的原因と間接的原因を書く。直接的原因とは問題事象の発生トリガーとなった原因である。例えばバグだったりオペミスだったり物理故障だったりである。間接的原因は、背景要因の説明であり、なぜそれを発生させたのかの分析の説明である。例えばテストが不十分だった、仕様や設計の考慮漏れだった、などといった理由である。原因がまだ調査中の段階で一旦出す場合は「調査中」とし、書ける情報を書いておく。
対応	原因を踏まえて、問題を解決する対応策などを説明する。（場合によっては報告書を出す段階ではすでに対応済みであるかもしれない。）当座の間でのワークアラウンドを「暫定対応」とし、根治的な改善改修を「恒久対応」とする、といった形で段階を分けて対応を計画し、説明する場合がある。開発のインパクトやスケジュールなどを勘案する必要があるためである。
再発防止策	前述の恒久対応の延長として説明することもある。同様の事象を再発させないために講じた対策を説明する。これはチームだったりプロジェクトだったり会社だったりで対応することになるので、必要に応じてPDCAサイクルに組み込んだり、ルール化・標準化したりと、開発・運用の品質向上として関係者全体で取り組むことになる。なお、この項目は暫定対応後で、関係者内で協議された上で説明される項目となる。
その他	残タスクや検討事項、提案事項など、補足や備考など、付記しておきたいことを書く。

その他場合によって書くもの、添えるもの

場合によっては別紙資料などになるかもしれない。必要に応じて書いたりするもの。

項目	内容
設計系の図	構成図やネットワーク図、コンポーネント図など、問題が発生した箇所などを視覚的に把握するために添えたりする。 ✖︎印などをつけて分かりやすくする。
画面キャプチャ	実際に発生している事象を画像として記録し、どのようになっていたかの視覚的な説明資料としたりする。
ログ	実際に発生した時間やエラー内容など、証跡資料として添付したりする。エビデンスとなる場合がある。

文章例

リバースプロキシサーバの設定値の一部変更作業を行った場合、設定値のミスにより正しくプロキシされず、アクセス障害が発生した、というケースを想定して、サンプルの障害報告書を考えた。
長くなるのもあれなので、あっさり目の文章にしているのでご了承いただきたい。

この度は作業に起因するネットワークの通信障害によりごユーザー様のサービス利用に影響をきたすこととなり申し訳ございませんでした。
今回発生した事象について調査をし対策を講じました。以下ご報告いたします。

概要

リバースプロキシの設定ファイルの更新作業を行なった際に、値の設定ミスがあり、一部のAPIサーバと管理画面へ正常にアクセスできない状況が発生した。

発生日時

2022年7月2日 1:30頃〜 2022年7月2日 2:30頃

影響範囲

当該期間中にアプリのXXX機能を利用したユーザー123人が正常に機能を利用できず「通信エラー」が発生していた状態だった。
（なお、人数はIPアドレス単位での換算）

経緯

時刻	内容	補足
7/2 1:00	計画作業のためにサービスのメンテナンスモード開始した。	・サーバ増設作業
1:30	作業を終了しメンテナンスモードを解除した。サービスを開放した。
1:35	作業者内でアプリのXXX機能でアクセスエラーが発生する事象を確認した。再現性があった。原因調査を開始した。
1:40	PM△△△から○○○様へ一時報告する。
1:45	・・・（省略）・・・
2:20	内部リグレッションテストを終え、メンテナンスモードの解除を完了した。公開後の動作確認を開始した。
2:30	動作確認で問題ないことを確認したので、○○○様へ作業の完了を報告した。
2:40	○○○様からも問題ないことの報告を受ける。本件をクローズし作業を解散をした。

原因

直接的原因
今回設定変更したリバースプロキシサーバの設定ファイル中で、XXX機能のAPIのプロキシ先の設定内容にミスがあった。このためサーバのプロキシ処理が正常に行われず、結果的にクライアントにエラーが返却されていた。

間接的原因
今回の変更において、主たる変更箇所についての修正内容についてはチーム内でレビューを行い、内容に問題がないことを設計および変更ファイル作成段階で確認していた。しかしながら今回原因となった内容ミスの箇所は改善箇所外の既存箇所で、レビューのチェックから漏れていた。
想定外の箇所が変更されていた理由は、開発者のファイルの編集時に誤って編集されてしまいそのまま保存されてしまっていたからであった。

対応・再発防止策

障害自体への対応は完了済み。

再発防止策

再発防止策として、レビューにおける観点を見直す。
- 変更箇所のみをチェックするだけではなく、設定ファイル自体の差分確認を行う。
- また、設定ファイルはプログラムのソースコードとは別に管理していたためGitリポジトリ管理外のファイルとなっていた。今後はこれもGitリポジトリの管理下におき、履歴記録、改修、レビューなどを他のソースと同様の統一的な手法で行う。
リグレッションテストにおけるテスト項目を見直す。
- 主機能を中心にリグレッションテストを行なったが、今回問題となったXXX機能についてはサブ機能的な理由から対象から外れていた。サブ機能についてもリグレッションテストに含めるようにする。

（以上）

ちょうどこの記事を書いているタイミングでauの大規模障害が発生していて、対応エンジニアさんなどの苦労を推し測っていたところです。あちらの場合は総務省への報告になるからもっと分厚い報告書になるのだろうなぁ。。。収束へ向けて頑張って欲しい。 ↩