参照しやすいインシデントチケットの書き方

Last updated at 2020-12-08Posted at 2020-12-08

弊社のSRE部門では、商用環境に問題が発生した場合、Redmine上で「インシデントチケット」と呼ばれるチケットを作成することで、その顛末を管理しています。

このインシデントチケットの書き方について、日ごろ思っているポイントをこの機会にまとめてみました。チケットのみならず、手順書なども含めたドキュメントの書き方にまつわる話になりそうです。

インシデントチケットとは何か

商用環境に起きた問題に対して1対1で作成し、その顛末をまとめたものです。チケット管理にはRedmineを利用しています。

問題発生時には初動として同一事象を扱っているチケットがないかを検索し、もしヒットしたらそのチケットに書かれている対応方法等を参考にして対処します。

インシデントチケットには主に以下のような内容が含まれています。

インシデントチケットを書く目的は大きく分けて以下の通りだと考えています。

そのため、この目的を達成することができない書き方のチケットは「よくないチケット」と考えることができます。

いずれにしても言えるのは「チケットはあとから参照するためのもの」ということで、書くだけで効果がある魔除けのお札ではありません。

参照しやすいチケット、もう少し言うなら「読んでわかりやすいチケット」を書くためには、大事なポイントがいくつかあると考えています。

ソースコードのインデントなどもそうですが、人に読まれることが前提のものは見た目を整えることが非常に大事です。節ごとに見出しを付ける、ログやコードの部分をブロックで指定する、などを最低限使いたいです。

Redmineの場合はテンプレート機能を使ってあらかじめ用意しておくと便利です。

チケットを書いた人と参照する人で必ずしも同じだけの知識・知見があるとは限りません。特に一次対応をどう行ったかを書く際、具体的な手順や言葉については省略せずになるべく具体的に書くようにしています。

アラートが出ていたのでコンソールから再起で解消

監視システムでアラートの発生を確認。
AWSコンソールから対象インスタンスの再起動を実施。
その後、監視システム上でアラートの解消を確認した。

上の”具体的に書く”と似ていますが、一次対応や根本原因の調査において、何を見てどういった基準で判断したかという流れもなるべく明記します。

結論だけが書いてある場合、後からそのチケットを見た人はその判断を再現することができず、同じ対処をすべきかどうかが決定できません。それではインシデントチケットの意味は薄れてしまいます。

また、これを書くことで部署内で他の人が書いたチケットを見てその判断方法を踏襲することができ、知見の共有や教育コストの削減にも効果があると考えています。

ここまで色々と書きましたが、これを全員が認識したからといってインシデントチケットの運用が良くなっていくとは限りません。なぜなら、そもそも問題発生時に必ずチケットが切られる前提で話しているからです。

チケットを切ることそれ自体が問題を解決してくれるわけではありません。チケットを書くぐらいなら具体的な修正のために手を動かしたいと感じる場合も多く見受けられ、他のタスクが山積みになってる状況では容易に忘れ去られてしまいます。

なので、実は内容なんかよりチケット作成の自動化のほうがよっぽど大事なのではと思ったり…

戦いはまだまだ続きます。