良いデバッグは痕跡が残らない

한 줄 요약

30분 만에 정확히 좁혀 고친 사람과 세 시간 헤매다 우연히 고친 사람의 커밋은 똑같이 생겼고, 그래서 기록을 남기지 않으면 실력도 조직의 자산도 쌓이지 않는다.

왜 이게 필요했나

디버깅이 경력에 비례해 늘지 않는 이유가 셋 있습니다.

첫째, 명시적으로 가르치는 곳이 거의 없습니다. 언어와 프레임워크는 배우지만 좁히는 절차는 어깨너머로 배웁니다.

둘째, 피드백이 잘못 걸려 있습니다. 증상이 사라지면 보상이 옵니다. 왜 사라졌는지 모르는 상태도 똑같이 보상받습니다. 그래서 운으로 고친 경험이 실력으로 오인됩니다.

셋째, 좋은 디버깅은 흔적이 안 남습니다. 조직이 이 능력을 알아보기 어렵고, 알아보지 못하면 육성되지도 않습니다.

여기에 대한 대응은 하나뿐입니다. 흔적을 남기는 것.

좁히는 절차에는 이름이 있다

기록을 남기려면 먼저 절차가 있어야 합니다. 경험 많은 사람이 무의식적으로 하는 것을 이름 붙여 두면 배울 수 있게 됩니다.

이분 탐색. 요청이 지나는 계층을 반으로 자릅니다. 클라이언트 → 게이트웨이 → 서비스 → DB 라면, 먼저 게이트웨이에서 직접 서비스를 불러 봅니다. 되면 앞쪽이, 안 되면 뒤쪽이 범인입니다. 한 번에 후보가 절반이 됩니다. 계층이 여덟이면 세 번에 하나로 좁힙니다.

차이 좁히기(delta debugging). 되는 것과 안 되는 것이 둘 다 있을 때 씁니다. 되는 요청과 안 되는 요청의 차이를 하나씩 지워 가며 어느 차이가 사라지는 순간 증상도 사라지는지 찾습니다. 헤더 하나, 필드 하나, 시각 하나가 남습니다.

시간 축 맞추기. 배포·설정 변경·트래픽 증가의 시각과 증상 시작 시각을 한 줄에 놓습니다. 대부분의 장애는 무언가가 바뀐 직후에 시작합니다. "언제부터인가" 를 정확히 아는 것이 "무엇 때문인가" 의 절반입니다.

가정 뒤집기. 30분 넘게 못 좁혔다면 확실하다고 믿은 것 하나가 틀렸을 가능성이 큽니다. "DNS 는 당연히 된다", "설정은 반영됐다", "그 버전이 맞다" — 이런 것을 한 번씩 실제로 확인합니다. 대개 여기서 나옵니다.

기록의 형식 — 한 장이면 된다

길게 쓰면 아무도 안 씁니다. 실무에서 실제로 유지되는 형식은 이 정도입니다.

## 증상
결제 완료 화면에서 간헐적 500 (약 20%)

## 재현
for i in $(seq 20); do curl -s -o /dev/null -w '%{http_code}
'   -X POST https://stg/api/pay -d @fixtures/pay.json; done
→ 20회 중 4~6회 500

## 배제
- 인증: 401/403 이 로그에 0건
- 네트워크: 같은 요청을 게이트웨이 안에서 직접 → 같은 비율로 실패
- 데이터: 실패한 요청의 body 가 성공한 것과 바이트 단위로 동일

## 원인
결제 서비스 파드 3개 중 1개만 옛 설정(타임아웃 1초)으로 떠 있었다.
ConfigMap 을 바꾼 뒤 rollout restart 를 하지 않아 그 파드만 옛 값을 안고 있었다.

## 수리 전후
전: 20회 중 5회 실패 / 후: 40회 중 0회 실패 (같은 명령)

## 다음에 이걸 막는 것
- [ ] ConfigMap 해시를 파드 애노테이션에 넣어 변경 시 자동 재시작 (담당: 배포팀, 3/25)

"다음에 이걸 막는 것" 이 이 문서의 값어치입니다. 원인만 적힌 기록은 같은 장애를 두 번째로 만났을 때 검색이 되는 정도지만, 여기까지 적힌 기록은 두 번째를 없앱니다.

시간 상자를 정해 둔다

좁히지 못한 채 시간이 흐르는 것이 디버깅의 가장 큰 비용입니다. 미리 정해 둡니다.

경과	할 일
15분	지금까지 배제한 것을 글로 적는다. 적는 동안 빠진 계층이 보인다
30분	확실하다고 믿은 가정 하나를 실제로 확인한다
45분	사람을 부른다. 설명하는 도중에 스스로 찾는 일이 절반이다
60분	우회로가 있는지 본다. 원인 규명과 서비스 복구는 다른 일이다

마지막 줄이 특히 중요합니다. 장애 대응에서는 복구가 먼저고 원인은 나중 입니다. 롤백으로 5분 만에 복구할 수 있는데 원인을 찾느라 한 시간을 쓰는 것은 잘못된 우선순위입니다.

어떻게 동작하나

FDE 가 남겨야 하는 기록은 네 종류입니다.

재현 명령. 증상을 일으키는 최소 명령 한 줄. 이것이 있으면 수리 여부를 같은 잣대로 판정할 수 있고, 없으면 "고친 것 같다" 까지만 말할 수 있습니다.

배제 목록. 확인해서 지운 계층과 그 근거. 한 줄이면 충분합니다. auth — 401/403 이 로그에 한 건도 없음 처럼.

측정값의 전후. 수리 전 20회 중 5회 실패, 수리 후 20회 중 0회. 두 숫자가 같은 방법으로 측정됐다는 것이 중요합니다.

떠난 뒤에도 남는 문서. FDE 의 성공 조건은 특이합니다. 내가 없어도 굴러가야 성공입니다. 상주가 끝나는 날 시스템이 같이 멈춘다면 그것은 배포가 아니라 대여였던 셈입니다.

현장에서 만나는 모습

인수인계 문서에서 고객이 가장 자주 다시 여는 것은 아키텍처 그림이 아니라 장애 런북입니다. 자주 나는 증상별로 첫 30분에 무엇을 할지가 적힌 문서. 런북이 없는 시스템은 넘길 수 없는 시스템입니다.

그리고 문서를 넘기는 날에는 문서만 넘기지 말고, 고객 엔지니어가 런북대로 장애 시나리오 하나를 직접 처리해 보는 리허설까지 하는 것이 완결입니다. 읽고 이해한 것과 손이 움직이는 것은 다릅니다.

기록의 형식보다 중요한 것은 타이밍입니다. 인수인계 문서는 마지막 주가 아니라 프로젝트 중반부터 쌓아야 합니다. 마지막 주에 몰아 쓴 문서는 예외 없이 "무엇이 안 되는지" 가 빠져 있습니다. 그때쯤이면 본인이 이미 그 예외에 익숙해져서 특별하다고 느끼지 않기 때문입니다.

다음 실습에서 할 것

네 종류를 실제로 남깁니다. 그리고 마지막에 채점기가 다음 사람 역할을 합니다 — 여러분이 쓴 재현 명령을, 여러분의 셸이 아닌 깨끗한 환경에서 다시 돌립니다. 거기서 같은 숫자가 나와야 기록이 기록입니다.