次の人がもう一度回せる記録を残す

目標

調べたことを、次の人がもう一度回せる形で残します。理論で見た4種類(再現コマンド・除外リスト・測定値・引き渡す文書)を、実際のファイルとして作ります。

最後のステップで、採点ツールが次の人の役を務めます。書いた再現コマンドを自分のシェルではない場所で実行して、同じ数字が出るかを見ます。ここで落ちる記録が、現場で最もよくある記録です。書いた人のところでしか動きません。

環境

/opt/app/flaky.pyは、顧客先の見積もりAPIを模したものです。直す対象ではなく、再現する対象です。

mkdir -p /root/record
nohup python3 /opt/app/flaky.py > /tmp/flaky.log 2>&1 &
sleep 1
curl -s http://127.0.0.1:8001/health

GET /health    항상 200
GET /quote     일정 주기로 503 — 본문은 upstream pool exhausted
GET /counter   지금까지 받은 /quote 요청 수

このコードブロックの韓国語の説明は、順に、/healthは常に200、/quoteは一定の周期で503を返し本文はupstream pool exhausted、/counterはこれまでに受け取った/quoteリクエストの数、という意味です。

作るファイル

すべて/root/record/の下です。

repro.sh       증상을 다시 일으키는 명령 하나. 사람 없이 끝나고 숫자만 출력한다
before.txt     측정값과 '어떻게 쟀는지'
ruled_out.md   지운 계층과 그 근거 명령
evidence.txt   실패 응답의 상태 코드와 본문 원문
runbook.md     이 증상이 다시 났을 때 첫 30분
handoff.md     넘기는 문서

ステップ

作業ディレクトリを作成し、対象のサービスを起動します。
repro.shを書きます。/quoteを20回呼び出し、200以外の応答の数だけを出力します。確認を求めずに終わる必要があります。
before.txtに結果を書きますが、何回呼び出して得た値か、そして何を呼び出したかを一緒に書きます。数字だけだと、次の人が同じ物差しで測れません。
ruled_out.mdに、消したレイヤーを2つ以上、根拠になったコマンドとともに書きます。
evidence.txtに、失敗した応答のステータスコードと本文を、要約せずにそのまま残します。
採点ツールがrepro.shを、別のディレクトリで、環境変数なしで実行します。
runbook.mdに、症状・打つコマンド・判定基準・行き詰まったときの行き先を書きます。
handoff.mdに、現在の状態・次の一歩・触ってはいけないもの、そして前に残したファイルを指す行を書きます。

参考

ステップ6がこのラボのすべてです。cdしておいた場所、シェルのエイリアス、あらかじめexportしておいた変数。この3つのどれか1つにでも頼っていると、そこで落ちます。データのパスは絶対パスで書き、必要な値はスクリプトの中で作ってください。

作業ディレクトリと対象サービス

作業ディレクトリを作成し、対象のサービスを起動します。

/root/recordを作成し、/opt/app/flaky.pyを起動します。バックグラウンドで動かして、/healthが200かどうかを確認してください。

再現コマンドを1つに固定する

repro.shを書きます。/quoteを20回呼び出し、200以外の応答の数だけを出力します。確認を求めずに終わる必要があります。

20回呼び出して、200以外の応答の数だけを出力します。curl -o /dev/null -w '%{http_code}'でコードだけを受け取って数えれば簡単です。人がいなくても終わる必要があるので、入力を待つ文は入れないでください。

測定値と測定方法を一緒に残す

before.txtに結果を書きますが、何回呼び出して得た値か、そして何を呼び出したかを一緒に書きます。数字だけだと、次の人が同じ物差しで測れません。

数字だけを残すと、次の人が同じ物差しで測れません。何回呼び出したかと、どのパスを呼び出したかを、同じファイルに書いてください。

消したレイヤーとその根拠

ruled_out.mdに、消したレイヤーを2つ以上、根拠になったコマンドとともに書きます。

「確認して消した」というだけでは足りません。何で消したかがないと、次の人がそのレイヤーをもう一度確認します。サービスが生きていることは、/healthでわかります。

失敗の証拠を原文のまま残す

evidence.txtに、失敗した応答のステータスコードと本文を、要約せずにそのまま残します。

「503が出た」は要約です。ステータスコードと応答の本文をそのまま残してはじめて、次の人が同じものを見ているかどうかがわかります。

別の環境でもう一度実行してみる

採点ツールがrepro.shを、別のディレクトリで、環境変数なしで実行します。

採点ツールがcd /tmpしたあとで、環境変数を空にしてrepro.shを実行します。相対パスや、あらかじめexportしておいた変数に頼っていると、ここで落ちます。それがこのラボの要点です。

再び起きたときの最初の30分

runbook.mdに、症状・打つコマンド・判定基準・行き詰まったときの行き先を書きます。

顧客が引き継ぎ文書で最もよく開き直すのが、ランブックです。説明ではなく、打つコマンドと結果の読み方があってはじめて、明け方に役立ちます。

引き渡す文書

handoff.mdに、現在の状態・次の一歩・触ってはいけないもの、そして前に残したファイルを指す行を書きます。

引き継ぎで最も抜けやすく、最も高くつく項目が、「触ってはいけないもの」です。そして文書だけを渡して再現コマンドを渡さないと、次の人は最初からやり直しになります。