弊社のSRE部門では、商用環境に問題が発生した場合、Redmine上で「インシデントチケット」と呼ばれるチケットを作成することで、その顛末を管理しています。
このインシデントチケットの書き方について、日ごろ思っているポイントをこの機会にまとめてみました。チケットのみならず、手順書なども含めたドキュメントの書き方にまつわる話になりそうです。
※本記事は「Develop fun!を体現する Works Human Intelligence Advent Calendar 2020」の12/9を担当したものです。
#インシデントチケットとは何か
商用環境に起きた問題に対して1対1で作成し、その顛末をまとめたものです。チケット管理にはRedmineを利用しています。
問題発生時には初動として同一事象を扱っているチケットがないかを検索し、もしヒットしたらそのチケットに書かれている対応方法等を参考にして対処します。
インシデントチケットには主に以下のような内容が含まれています。
- 問題の発生箇所
- 問題発生時のログ
- 対応担当者
- 一次対応の方法
- 根本原因
- 恒久対応の方針
#インシデントチケットの目的とは？
インシデントチケットを書く目的は大きく分けて以下の通りだと考えています。
- 同一事象が発生した場合に問題解消までのリードタイムを短くする
- 問題発生までの経緯や後続の対応を紐づけて管理して俯瞰できるようにする
そのため、この目的を達成することができない書き方のチケットは「よくないチケット」と考えることができます。
いずれにしても言えるのは「チケットはあとから参照するためのもの」ということで、書くだけで効果がある魔除けのお札ではありません。
#良いチケットを書くためのポイント
参照しやすいチケット、もう少し言うなら「読んでわかりやすいチケット」を書くためには、大事なポイントがいくつかあると考えています。
###見た目を整える
ソースコードのインデントなどもそうですが、人に読まれることが前提のものは見た目を整えることが非常に大事です。節ごとに見出しを付ける、ログやコードの部分をブロックで指定する、などを最低限使いたいです。
Redmineの場合はテンプレート機能を使ってあらかじめ用意しておくと便利です。
###省略せずに具体的に書く
チケットを書いた人と参照する人で必ずしも同じだけの知識・知見があるとは限りません。特に一次対応をどう行ったかを書く際、具体的な手順や言葉については省略せずになるべく具体的に書くようにしています。
- 悪い例
アラートが出ていたのでコンソールから再起で解消
- よい例
監視システムでアラートの発生を確認。
AWSコンソールから対象インスタンスの再起動を実施。
その後、監視システム上でアラートの解消を確認した。
###判断の流れが追えるようにする
上の”具体的に書く”と似ていますが、一次対応や根本原因の調査において、何を見てどういった基準で判断したかという流れもなるべく明記します。
結論だけが書いてある場合、後からそのチケットを見た人はその判断を再現することができず、同じ対処をすべきかどうかが決定できません。それではインシデントチケットの意味は薄れてしまいます。
また、これを書くことで部署内で他の人が書いたチケットを見てその判断方法を踏襲することができ、知見の共有や教育コストの削減にも効果があると考えています。
#チケット管理の問題は…
ここまで色々と書きましたが、これを全員が認識したからといってインシデントチケットの運用が良くなっていくとは限りません。なぜなら、そもそも問題発生時に必ずチケットが切られる前提で話しているからです。
チケットを切ることそれ自体が問題を解決してくれるわけではありません。チケットを書くぐらいなら具体的な修正のために手を動かしたいと感じる場合も多く見受けられ、他のタスクが山積みになってる状況では容易に忘れ去られてしまいます。
なので、実は内容なんかよりチケット作成の自動化のほうがよっぽど大事なのではと思ったり…
戦いはまだまだ続きます。