Writing the Incident Report

한국어 원문으로 표시합니다.

목표

이번 환경에 제공된 합성 원본 로그를 근거로, 비엔지니어가 읽을 수 있는 장애 보고서 한 장을 쓸 수 있게 됩니다.

왜 중요한가

FDE 의 장애 대응은 시스템이 아니라 보고서에서 끝납니다. 기술적으로 완벽히 고쳐도 보고가 늦거나 모호하면 고객의 기억에는 불안만 남습니다.

이 실습이 강제하는 네 가지는 전부 현장의 규칙입니다. 영향이 원인보다 먼저 — 읽는 사람이 가장 먼저 알아야 할 것은 지금 누가 무엇을 못 하는가입니다. 숫자로 쓰기 — 형용사는 사람마다 다르게 해석되고 그 차이가 나중에 분쟁이 됩니다. 사람을 지목하지 않기 — 고객사 보고서에 담당자가 지목되면 다음 장애에서 그 사람은 정보를 숨기고, 그 대가는 다음번 탐지 지연으로 돌아옵니다. 다음 보고 시각 약속 — 원인을 모르는 단계에서 해결 시각을 약속하는 것은 도박이지만, 다음 보고 시각은 현재 확인된 상황에서 담당자가 지킬 수 있도록 정합니다.

채점은 필수 절·일부 수치·길이·기술 용어를 확인하며 문장 전체의 사실성이나 고객 행동의 안전성을 판정하지 않습니다. 원본에 없는 사실을 쓰지 않았는지는 아래 근거 범위와 대조해 직접 검토해야 합니다.

접근 로그의 오류 응답은 주문별 처리·청구 실패를 증명하지 않습니다. 이 자료에는 주문 원장이나 청구 대조 결과가 없으므로 중복 청구가 없다고 단정하거나 즉시 다시 결제하라고 안내하지 마세요. 확인된 서비스 증상, 확인 중인 주문별 결과, 고객이 먼저 확인할 내역을 구분합니다. 복구 후 오류가 줄었다는 관측과 과거 주문의 처리 결과도 서로 다른 질문입니다.

필수 절 여섯 개 — ## 영향, ## 현재 상태, ## 잠정 원인, ## 타임라인, ## 다음 단계, ## 고객 안내

단계

/root/incident.md 를 만드세요.
위 여섯 개 절을 모두 넣고, ## 영향 이 ## 잠정 원인 보다 앞에 오게 하세요.
## 영향 절에 망가진 경로(/api/pay)와 원본에서 센 정확한 오류 응답 건수를 단위(건)와 함께 넣으세요.
## 잠정 원인 절에 문제가 된 배포 버전(2.7.0)과 느려진 테이블(payments)을 넣으세요.
## 타임라인 절에 03:19, 03:27, 03:31, 03:36, 03:39 다섯 시각을 모두 넣으세요.
문서 전체에서 로그의 담당자 계정명을 쓰지 말고, 책임을 묻는 표현(실수·잘못·과실·탓)도 쓰지 마세요.
다음 보고: 로 시작하는 줄을 넣고 시각이나 주기를 적으세요.
## 고객 안내 절을 공백 제외 30자 이상으로 쓰되, 타임아웃·쿼리·500·payments·2.7.0 을 쓰지 말고 결제 라는 말로 무슨 일이 있었는지 설명하세요.

참고

실습별 파일은 자동으로 이어지지 않습니다. 이전 실습의 요약 파일이 없어도 이번 환경의 원본으로 조사할 수 있습니다.
접근 로그 /opt/data/web.log, 앱 로그 /opt/data/app.jsonl, 배포 이력 /opt/data/deploy.log, 느린 조회 기록 /opt/data/db-slow.log, 알람 이력 /opt/data/alert.log를 읽으세요. 원본은 이미 제공되며 새로 만들거나 덮지 않습니다.
오류 응답 건수는 오류를 본 요청 수입니다. 주문별 성공 여부·청구 횟수는 이 자료만으로 확인되지 않으므로 확인 중으로 남깁니다.
8번의 의도는 "파드가 재시작 루프에 빠졌습니다" 를 "서버가 반복적으로 꺼졌다 켜지는 상태라 접속이 끊깁니다" 로 옮기는 연습입니다.
흔한 실수 1: 6번에서 로그의 actor=oncall-kim 값을 그대로 옮겨 적는 것.
흔한 실수 2: 8번에서 기술 절의 문장을 복사해 붙이는 것. 같은 내용을 다른 말로 다시 써야 합니다.

보고서 파일 만들기

/root/incident.md 를 만드세요.

/root/incident.md 를 만드세요. 뼈대만 있어도 되지만 내용이 있어야 합니다.

필수 절 갖추기

위 여섯 개 절을 모두 넣고, ## 영향 이 ## 잠정 원인 보다 앞에 오게 하세요.

여섯 개 절이 필요하고, 영향이 잠정 원인보다 먼저 나와야 합니다.

영향을 숫자로 쓰기

## 영향 절에 망가진 경로(/api/pay)와 원본에서 센 정확한 오류 응답 건수를 단위(건)와 함께 넣으세요.

영향 절에 어느 경로가 망가졌는지와 오류 건수가 들어가야 합니다. 형용사가 아니라 숫자입니다.

근본 원인 값 쓰기

## 잠정 원인 절에 문제가 된 배포 버전(2.7.0)과 느려진 테이블(payments)을 넣으세요.

잠정 원인 절에 문제가 된 배포 버전과 느려진 테이블 이름이 들어가야 합니다.

타임라인 절 채우기

## 타임라인 절에 03:19, 03:27, 03:31, 03:36, 03:39 다섯 시각을 모두 넣으세요.

다섯 개 시각이 모두 타임라인 절 안에 있어야 합니다. 앞 코스에서 구한 값들입니다.

비난 없는 문장으로 쓰기

문서 전체에서 로그의 담당자 계정명을 쓰지 말고, 책임을 묻는 표현(실수·잘못·과실·탓)도 쓰지 마세요.

로그의 actor 값을 옮기지 말고, 책임을 묻는 표현도 쓰지 마세요.

다음 보고 시점 약속하기

다음 보고: 로 시작하는 줄을 넣고 시각이나 주기를 적으세요.

'다음 보고:' 로 시작하는 줄에 시각이나 주기를 적으세요.

고객 언어로 번역하기

## 고객 안내 절을 공백 제외 30자 이상으로 쓰되, 타임아웃·쿼리·500·payments·2.7.0 을 쓰지 말고 결제 라는 말로 무슨 일이 있었는지 설명하세요.

고객 안내 절에는 기술 용어가 들어가면 안 됩니다. 어떤 업무가 영향을 받았는지를 일상어로 쓰세요.