소규모 사이트 장애 기록은 어떻게 남기면 좋을까

기록의 목적은 책임 추궁이 아니라 재현 방지다

작은 사이트에서 장애가 나면 운영자는 대부분 개발자이자 배포자이자 고객 지원 담당자입니다. 그래서 기록을 남기지 않으면 당장 복구한 뒤 모든 맥락이 사라집니다. 다음에 비슷한 문제가 생기면 같은 명령을 다시 찾고, 같은 대시보드를 다시 열어보게 됩니다.

장애 기록은 길 필요가 없습니다. 언제 시작됐는지, 사용자는 무엇을 봤는지, 원인은 무엇이었는지, 어떤 조치가 효과가 있었는지, 다음에는 무엇을 바꿀지만 남겨도 충분합니다. 중요한 것은 기억이 생생할 때 적는 것입니다.

시간순으로 쓰면 판단이 보인다

장애 중에는 원인을 단번에 맞히기 어렵습니다. DNS를 의심했다가 캐시로 돌아가고, 코드 문제로 보였지만 환경 변수였던 경우도 있습니다. 시간순 기록은 그때 어떤 증거를 보고 어떤 판단을 했는지 남겨줍니다.

예를 들어 “14:05 홈 접속 500 확인, 14:08 최근 배포 커밋 확인, 14:12 환경 변수 누락 발견, 14:20 재배포 완료”처럼 쓰면 충분합니다. 나중에 보면 복구 시간이 어디서 길어졌는지 알 수 있습니다.

사용자 영향 범위를 분리한다

모든 장애가 같은 무게는 아닙니다. 관리자만 불편한 문제, 일부 이미지가 늦게 뜨는 문제, 전체 사이트가 열리지 않는 문제는 대응 우선순위가 다릅니다. 기록에는 영향 받은 URL, 기기나 브라우저, 지역, 오류 메시지, 시작과 종료 시간을 적습니다.

이 범위가 있어야 다음에 모니터링을 어디에 둘지 결정할 수 있습니다. 홈만 확인하는 모니터링으로는 상세 글 404를 잡지 못합니다. 반대로 모든 URL을 계속 확인하면 운영 비용과 소음이 커집니다.

작은 개선 하나로 마무리한다

장애 기록의 끝에는 항상 다음 조치가 있어야 합니다. 체크리스트에 항목 추가, 배포 전 명령 추가, 환경 변수 문서화, DNS 변경 기록 양식 만들기처럼 작아도 됩니다. 큰 재설계를 매번 약속하면 기록이 부담스러워져 오래가지 않습니다.

CloudPlare의 콘텐츠도 이런 관점을 유지합니다. 완벽한 인프라 이론보다 작은 운영자가 실제로 다음 배포에서 덜 틀리게 만드는 기록이 더 가치 있습니다. 이런 목소리가 사이트의 독창성을 만듭니다.

기록 양식과 실제 예시

장애 기록은 형식이 정해져 있어야 나중에 검색됩니다. 항목을 고정해 두면 작성 시간도 줄어듭니다.

## 2026-06-14 이미지가 전부 깨져 보임

- 증상: 목록 페이지의 썸네일만 전부 X 표시. 본문 이미지는 정상.
- 영향: 목록 페이지 진입 사용자 전체. 기능 장애는 없음.
- 발견: 배포 20분 뒤 직접 확인
- 확인한 것:
  - curl -sSI .../thumb.webp  -> 404
  - 빌드 산출물에 thumb.webp 없음
  - 원본 파일명이 thumb.WEBP (대문자)
- 원인: 로컬은 대소문자 구분 없음, 배포 환경은 구분함
- 조치: 파일명을 소문자로 통일하고 재배포
- 재발 방지: 자산 파일명은 소문자·하이픈만 사용하도록 규칙화
- 걸린 시간: 발견 20분 + 조치 15분

가장 중요한 항목은 "확인한 것"입니다. 결론만 적어두면 다음에 비슷한 증상이 나왔을 때 같은 확인 과정을 처음부터 반복하게 됩니다. 반대로 확인 절차가 남아 있으면 두 번째부터는 몇 분 만에 끝납니다.

"걸린 시간"을 적는 이유는 어떤 문제에 재발 방지를 투자할지 고르기 위해서입니다. 30분짜리 문제가 다섯 번 반복됐다면 그건 자동화할 가치가 있는 문제입니다.

기록은 장애가 끝난 당일에 씁니다. 다음 날로 미루면 "확인한 것" 항목이 기억나지 않아 결국 결론만 남게 됩니다.