Leave a Record the Next Person Can Rerun

목표

조사한 것을 다음 사람이 다시 돌릴 수 있는 형태로 남깁니다. 이론에서 본 네 종류(재현 명령 · 배제 목록 · 측정값 · 넘길 문서)를 실제 파일로 만듭니다.

마지막 단계에서 채점기가 다음 사람 역할을 합니다. 여러분이 쓴 재현 명령을 여러분의 셸이 아닌 곳에서 돌려 같은 숫자가 나오는지 봅니다. 여기서 떨어지는 기록이 현장에서 가장 흔한 기록입니다 — 쓴 사람 자리에서만 돌아갑니다.

환경

/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 요청 수

만들 파일

전부 /root/record/ 아래입니다.

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

단계

1. 작업 디렉터리를 만들고 대상 서비스를 띄웁니다.
2. repro.sh 를 씁니다. /quote 를 20회 호출해 200 이 아닌 응답의 개수만 출력합니다. 물어보지 않고 끝나야 합니다.
3. before.txt 에 결과를 적되 몇 번 호출해 얻은 값인지와 무엇을 호출했는지를 함께 적습니다. 숫자만 있으면 다음 사람이 같은 잣대로 잴 수 없습니다.
4. ruled_out.md 에 지운 계층을 두 개 이상, 근거가 된 명령과 함께 적습니다.
5. evidence.txt 에 실패 응답의 상태 코드와 본문을 요약하지 말고 그대로 남깁니다.
6. 채점기가 repro.sh 를 다른 디렉터리에서, 환경변수 없이 돌립니다.
7. runbook.md 에 증상 · 칠 명령 · 판정 기준 · 막혔을 때 갈 곳을 씁니다.
8. handoff.md 에 현재 상태 · 다음 한 걸음 · 만지지 말 것, 그리고 앞에서 남긴 파일을 가리키는 줄을 씁니다.

참고

6단계가 이 실습의 전부입니다. cd 해 둔 자리, 셸 별칭, 미리 export 해 둔 변수 — 셋 중 하나라도 기대고 있으면 거기서 떨어집니다. 데이터 경로는 절대경로로 쓰고, 필요한 값은 스크립트 안에서 만드세요.

작업 디렉터리와 대상 서비스

작업 디렉터리를 만들고 대상 서비스를 띄웁니다.

/root/record 를 만들고 /opt/app/flaky.py 를 띄웁니다. 백그라운드로 돌리고 /health 가 200 인지 확인하세요.

재현 명령을 하나로 고정

repro.sh 를 씁니다. /quote 를 20회 호출해 200 이 아닌 응답의 개수만 출력합니다. 물어보지 않고 끝나야 합니다.

20회 호출해 200 이 아닌 응답의 개수만 출력합니다. curl -o /dev/null -w '%{http_code}' 로 코드만 받아 세면 간단합니다. 사람이 없어도 끝나야 하니 입력을 기다리는 문장은 넣지 마세요.

측정값과 측정 방법을 함께

before.txt 에 결과를 적되 몇 번 호출해 얻은 값인지와 무엇을 호출했는지를 함께 적습니다. 숫자만 있으면 다음 사람이 같은 잣대로 잴 수 없습니다.

숫자만 남기면 다음 사람이 같은 잣대로 잴 수 없습니다. 몇 번 호출했는지와 어느 경로를 호출했는지를 같은 파일에 적으세요.

지운 계층과 그 근거

ruled_out.md 에 지운 계층을 두 개 이상, 근거가 된 명령과 함께 적습니다.

'확인해서 지웠다' 는 것만으로는 부족합니다. 무엇으로 지웠는지가 없으면 다음 사람이 그 계층을 다시 확인합니다. 서비스가 살아 있다는 것은 /health 로 보입니다.

실패 증거를 원문 그대로

evidence.txt 에 실패 응답의 상태 코드와 본문을 요약하지 말고 그대로 남깁니다.

'503 이 났다' 는 요약입니다. 상태 코드와 응답 본문을 그대로 남겨야 다음 사람이 같은 것을 보고 있는지 알 수 있습니다.

다른 환경에서 다시 돌려 보기

채점기가 repro.sh 를 다른 디렉터리에서, 환경변수 없이 돌립니다.

채점기가 cd /tmp 한 뒤 환경변수를 비우고 repro.sh 를 돌립니다. 상대경로나 미리 export 해 둔 변수에 기대고 있으면 여기서 떨어집니다 — 그것이 이 실습의 요점입니다.

다시 났을 때의 첫 30분

runbook.md 에 증상 · 칠 명령 · 판정 기준 · 막혔을 때 갈 곳을 씁니다.

고객이 인수인계 문서에서 가장 자주 다시 여는 것이 런북입니다. 설명이 아니라 칠 명령과 결과를 어떻게 읽을지가 있어야 새벽에 쓸모가 있습니다.

넘기는 문서

handoff.md 에 현재 상태 · 다음 한 걸음 · 만지지 말 것, 그리고 앞에서 남긴 파일을 가리키는 줄을 씁니다.

인수인계에서 가장 자주 빠지고 가장 비싼 항목이 '만지지 말 것' 입니다. 그리고 문서만 넘기고 재현 명령을 안 넘기면 다음 사람은 처음부터 다시 시작합니다.