이 문서를 통해 아래 질문들에 답할 수 있게 됩니다.
- 장애 보고서 템플릿은 어떤 판단을 빠르게 만들기 위한 도구인가?
- 장애 중 작성하는 보고서와 사후 보고서는 어떻게 달라야 하는가?
- 빈 템플릿을 실무에서 쓸 수 있게 만들려면 어떤 필드가 필요한가?
개요
장애 보고서 템플릿은 문서를 예쁘게 만들기 위한 형식이 아니다.
장애 중에는 현재 상태, 사용자 영향, 담당자, 다음 조치를 빠르게 맞추기 위한 도구다.
사후에는 타임라인, 원인, 완화, 재발 방지 작업을 남기는 근거가 된다.
템플릿이 없으면 사고 때마다 어떤 정보를 적어야 하는지 다시 논의하게 된다.
템플릿이 너무 길면 아무도 채우지 못한다.
따라서 장애 중 템플릿과 사후 템플릿을 나눠야 한다.
장애 중 보고서
장애 중 보고서는 짧고 자주 갱신되어야 한다.
## Incident Status
- 상태: Investigating | Mitigating | Monitoring | Resolved
- Severity: SEV-2
- 시작 추정 시각: 2026-07-01 10:05 KST
- 탐지 시각: 2026-07-01 10:12 KST
- 영향: 모바일 주문 생성 실패율 증가
- 영향 범위: 모바일 앱 사용자, 웹 주문은 정상
- 담당: IC 김민수, TL 이지현, Scribe 박서연
- 현재 조치: 최근 배포와 DB connection 상태 확인
- 다음 업데이트: 2026-07-01 10:30 KST이 템플릿은 현재 대응을 맞추기 위한 것이다.
원인이 아직 없더라도 상태, 영향, 담당, 다음 업데이트는 적을 수 있어야 한다.
사후 보고서
사후 보고서는 학습과 재발 방지를 위한 문서다.
## Summary
- 제목:
- Severity:
- 기간:
- 사용자 영향:
- 최종 원인:
- 완화 조치:
- 재발 방지 요약:
## Timeline
| 시각 | 사건 | 근거 | 결정 |
|---|---|---|---|
| | | | |
## Impact
- 영향 기능:
- 영향 사용자:
- 실패율 또는 처리량 변화:
- 데이터 손실 여부:
## Root and Contributing Factors
- 직접 원인:
- 기여 요인:
- 탐지 지연:
- 완화 지연:
## Action Items
| 작업 | 유형 | 소유자 | 기한 | 검증 방법 |
|---|---|---|---|---|
| | 탐지/완화/예방/문서 | | | |사후 보고서는 짧아도 근거가 있어야 한다.
“원인 파악 후 조치 완료” 같은 문장은 나중에 아무것도 설명하지 못한다.
필수 필드
장애 보고서에는 최소한 다음 필드가 있어야 한다.
- 제목: 영향 기능과 현상을 담는다.
- 상태: 조사, 완화, 관찰, 해결 중 어디인지 표시한다.
- Severity: 현재 우선순위를 나타낸다.
- 시작 추정 시각: 영향이 시작된 시각이다.
- 탐지 시각: 팀이 알아차린 시각이다.
- 해결 시각: 사용자 영향이 끝난 시각이다.
- 사용자 영향: 사용자가 못 한 일을 적는다.
- 영향 범위: 전체, 일부 사용자, 특정 tenant, 특정 기능을 구분한다.
- 현재 조치: 이미 한 일과 다음 할 일을 구분한다.
- 근거: 로그, 지표, 신고, 배포 시각, SQL 결과를 연결한다.
- action item: 소유자와 기한이 있는 후속 작업이다.
필수 필드가 많아 보여도 대부분 사고 중 이미 필요한 판단이다.
작성 원칙
보고서는 사실과 추측을 구분해야 한다.
좋은 문장:
- 10:12부터 모바일 주문 생성 API 5xx가 증가했다.
- 10:27에 쿠폰 적용 기능을 비활성화한 뒤 실패율이 18%에서 2%로 낮아졌다.
- 현재 원인은 쿠폰 할인 계산 경로로 좁혀졌지만 확정되지 않았다.
나쁜 문장:
- 서버가 이상하다.
- 아마 DB 문제 같다.
- 조치 완료.
- 담당자가 실수했다.
보고서는 나중에 읽는 사람이 같은 판단을 재현할 수 있어야 한다.
Spring 백엔드 항목
Spring 서비스 보고서에는 다음 항목이 자주 필요하다.
- 영향 endpoint와 HTTP method
- 관련 controller, service, repository
- exception class와 대표 stack 위치
- DB transaction과 외부 API 호출 위치
- 스케줄 작업, batch, consumer 상태
- 최근 배포 버전과 변경 기능
- feature flag나 설정으로 완화한 항목
- 요청 ID, 주문 ID, 사용자 ID 같은 샘플 식별자
이 항목들은 보고서를 코드 리뷰나 재발 방지 작업으로 연결해 준다.
운영 체크리스트
- 장애 중 보고서와 사후 보고서를 분리한다.
- 상태와 Severity를 갱신할 때 시각과 근거를 남긴다.
- 사용자 영향은 내부 시스템명이 아니라 사용자가 못 한 일로 적는다.
- 타임라인에는 사건, 근거, 의사결정을 함께 둔다.
- action item에는 소유자, 기한, 검증 방법을 둔다.
- 보고서의 빈 필드는 “해당 없음”과 “미확인”을 구분한다.
- 재발 방지 작업 완료 후 보고서 링크나 상태를 갱신한다.
장애 신호
- 보고서가 원인 추측만 있고 사용자 영향이 없다.
- 타임라인에 조치 시각은 있지만 결과가 없다.
- action item이 모두 “문서화”나 “주의”로 끝난다.
- 해결 시각과 영향 종료 시각이 섞여 있다.
- 같은 장애를 다시 볼 때 어떤 신호로 복구를 판단했는지 알 수 없다.
- 보고서가 길지만 다음 대응자가 따라 할 수 없다.
이 신호는 템플릿이 사고 대응을 돕지 못한다는 뜻이다.
안전한 개선 조치
- 필수 필드만 먼저 채우고 상세 분석은 사후에 보강한다.
- 추측은 “가설”로 표시하고 근거가 생기면 상태를 바꾼다.
- 사용자 영향 문장을 맨 위에 둔다.
- 타임라인은 대응 중 계속 업데이트한다.
- action item은 탐지, 완화, 예방, 문서로 분류한다.
- 템플릿은 실제 장애 한 건에 적용해 보고 불필요한 필드를 줄인다.
하지 말아야 할 대응
- 빈 템플릿만 만들고 예시를 남기지 않는다.
- 고객 공지와 내부 원인 분석을 같은 문장으로 섞지 않는다.
- 불확실한 원인을 확정된 사실처럼 쓰지 않는다.
- 해결 후 action item 없이 보고서를 닫지 않는다.
- 보고서 필드를 모두 채우기 전까지 장애 대응을 늦추지 않는다.
인프라 담당자와 공유할 자료
- 장애 보고서 링크와 현재 상태
- 영향 기능과 사용자 범위
- 인프라 확인이 필요한 의존성
- 최근 배포와 설정 변경 시각
- 이미 확인한 정상/비정상 신호
- 필요한 로그, 지표, 권한, 복구 작업
장애 보고서는 팀 간 대화의 중심 문서가 되어야 한다.
확인 질문
확인 질문
- 장애 중 보고서가 빠르게 답해야 하는 질문은 무엇인가?
- 현재 영향, Severity, 담당자, 조치, 다음 업데이트가 무엇인지다.
- 사후 보고서가 추가로 답해야 하는 질문은 무엇인가?
- 왜 발생했고 왜 늦게 탐지/완화되었으며 무엇을 바꿔 재발을 줄일 것인지다.
- 좋은 장애 보고서 템플릿의 조건은 무엇인가?
- 필수 판단을 빠르게 채우게 하고 타임라인, 근거, action item을 검증 가능하게 남기는 것이다.
리뷰 체크포인트
- 장애 중 상태 보고와 사후 분석 양식이 구분되어 있는가?
- 사용자 영향과 내부 기술 원인이 분리되어 있는가?
- 타임라인에 근거와 결정이 포함되어 있는가?
- action item이 소유자와 기한을 가지는가?
- “미확인”과 “해당 없음”을 구분해 작성할 수 있는가?