이 문서를 통해 아래 질문들에 답할 수 있게 됩니다.
JVM OS 장애 보고서 작성에서 붙잡아야 할 핵심 판단 기준은 무엇인가?보고서는 판단 근거의 압축본이다라는 기준은 어떤 JVM/OS 신호로 확인되는가?- Java/Spring 코드에서
JVM OS 장애 보고서 작성판단 기준은 어떤 장애 신호로 드러나는가?
개요
이 문서의 주제는 JVM OS 장애 보고서 작성이다. JVM/OS 장애 보고서에 필요한 구조, 지표, 판단 근거, 재발 방지 항목을 정리한다.
먼저 붙잡을 기준은 다음 문장이다. 보고서는 판단 근거의 압축본이다. 좋은 장애 보고서는 “무슨 일이 있었나”보다 “어떤 증거로 그렇게 판단했나”를 재현 가능하게 남긴다.
핵심 모델
- 판단 기준: 보고서는 판단 근거의 압축본이다.
- 보고서의 첫 장은 영향 범위, 시작/종료 시각, 사용자 증상, 현재 상태를 짧게 고정한다.
- 타임라인은 배포, traffic, alert, 완화 조치, 지표 변화를 한 줄씩 연결한다.
- 증거는 Application, JVM, OS, external dependency로 나누고 수집 시각과 명령을 남긴다.
- 완화 조치와 근본 원인 수정은 다른 항목으로 쓴다.
- 남은 리스크와 재발 방지 owner/date가 없으면 보고서는 운영 문서로 불완전하다.
문서별 핵심 구분
- 보고서는 결론보다 판단 근거와 타임라인이 중요하다.
- JVM, OS, Application 증거를 같은 시각으로 묶는다.
- 남은 리스크와 재발 방지 항목을 명시해야 한다.
원리
장애 보고서는 사후 설명문이 아니라 다음 대응을 빠르게 만드는 운영 자산이다. 그래서 감정적 표현이나 추측보다 시각, 명령, 지표, 판단, 조치를 남기는 형식이 중요하다.
보고서의 타임라인은 원인과 결과를 구분하는 핵심 자료다. API latency가 먼저 올랐는지, GC pause가 먼저 늘었는지, Hikari pending이 뒤따랐는지, 재시작이 어느 지표를 낮췄는지 한 흐름으로 보여 줘야 한다.
좋은 보고서는 맞힌 원인만 쓰지 않는다. 배제한 후보와 배제 근거를 남겨 다음 장애 때 같은 확인을 반복하지 않게 한다.
Java/Spring 연결
- Spring Boot 보고서에는 Actuator metric query, application log 구간, trace/span, thread dump, GC log를 연결한다.
- JVM 증거에는
VM.command_line,VM.flags, GC pause, heap/non-heap, thread dump 수집 시각을 넣는다. - OS 증거에는 CPU/load, RSS/swap, disk iowait, socket state, FD limit/current count를 넣는다.
- Dependency 증거에는 DB latency, pool active/idle/pending, 외부 API timeout, retry/circuit 상태를 넣는다.
- 변경 이력에는 배포 버전, config/JVM option/systemd/container limit 변경을 포함한다.
코드와 설정 예시
INC=/tmp/incident-$(date +%Y%m%d-%H%M%S)
mkdir -p "$INC"
date -Is > "$INC/timestamp.txt"
jcmd <pid> VM.command_line > "$INC/vm-command-line.txt"
jcmd <pid> Thread.print > "$INC/thread-dump.txt"
ss -s > "$INC/socket-summary.txt"예시는 보고서에 붙일 incident bundle을 만드는 최소 형태다. 파일명과 수집 시각을 고정하면 나중에 metric, log, dump를 같은 타임라인에 맞추기 쉽다.
관찰 명령
date -Is
uptime
journalctl -u my-app --since '1 hour ago' -o short-iso
jcmd <pid> VM.command_line
jcmd <pid> Thread.print | headJVM OS 장애 보고서 작성 관찰 명령은 결론이 아니라 가설 확인 도구다. 운영 중에는 반복 간격, 대상 PID, 수집 시각을 함께 남기고 출력이 큰 명령은 범위를 제한한다.
지표 해석
| 신호 | 먼저 의심할 것 | 다음 확인 |
|---|---|---|
| 타임라인 공백 | 원인/결과 판단 불가 | alert, log, deploy, 조치 시각 |
| 증거 출처 불명 | 재현 불가한 주장 | 명령, metric query, 파일명 |
| 완화와 원인 혼합 | 재발 방지 누락 | mitigation vs root fix |
| 남은 리스크 없음 | 미확인 가정 숨김 | 미수집 자료, 재발 조건 |
보고서의 지표는 결론을 장식하는 숫자가 아니라 판단 근거다. 각 지표에는 수집 시각, 출처, 해석, 반박 가능성을 함께 적는다.
장애 상황에서 보는 순서
- 요약: 영향 범위, 시작/종료 시각, 현재 상태를 5줄 안에 쓴다.
- 타임라인: alert, deploy, traffic 변화, 지표 변화, 완화 조치를 시간순으로 쓴다.
- 증거: Application, JVM, OS, dependency 자료를 수집 시각과 함께 붙인다.
- 판단: 지지 증거와 반박 증거를 나눠 원인 후보를 줄인다.
- 조치: 즉시 완화, 근본 수정, 재발 방지 작업을 분리한다.
- 리스크: 미수집 자료, 남은 가정, owner, due date를 남긴다.
보고서는 장애가 끝난 뒤 한 번에 쓰면 세부 판단이 사라진다. 대응 중에 짧게 기록하고, 사후에는 문장과 근거를 정리하는 방식이 더 정확하다.
실전 팁
- 보고서 초안은 장애 중에 만들고, 장애 후에는 용어와 근거를 정리한다.
- 모든 첨부 파일에는 수집 시각, 대상 PID/host/container, 명령을 남긴다.
- “재시작 후 정상화”는 원인이 아니라 완화 결과다.
- 원인 후보를 지운 근거를 남기면 다음 장애에서 같은 확인을 줄일 수 있다.
- 재발 방지 항목에는 owner와 due date를 붙인다.
주니어 팁
- 보고서에는 “느렸다”보다 “몇 시부터 어느 API p99가 얼마로 올랐다”가 필요하다.
- 명령 출력만 붙이지 말고 그 출력으로 무엇을 판단했는지 한 문장을 붙인다.
- 모르는 것은 숨기지 말고 남은 리스크로 적는다.
시니어 팁
- 보고서 template에는 metric query, log query, dump path, runbook link를 미리 넣어 둔다.
- Postmortem은 비난이 아니라 시스템 개선 문서다. 개인 실수보다 guardrail 부재를 찾는다.
- 재발 방지는 alert, limit, timeout, capacity, test, rollout 절차 중 어디가 바뀌는지 명확해야 한다.
Guru급 팁
- 좋은 보고서는 다음 장애의 runbook을 업데이트한다. 새로 알게 된 명령과 금지할 대응이 문서에 반영되어야 한다.
- 결론의 신뢰도는 증거의 양보다 시간축 정합성에 달려 있다.
- 미확인 리스크를 적는 것은 약점이 아니라 다음 검증 작업을 분명히 하는 일이다.
위험 신호!
- 타임라인 없이 결론부터 쓴다.
- “재시작으로 해결”을 근본 원인으로 적는다.
- 첨부한 dump나 metric query의 수집 시각을 남기지 않는다.
- 배제한 후보와 남은 리스크를 생략한다.
- 재발 방지 항목에 owner와 due date가 없다.
확인 질문
확인 질문
- 장애 보고서의 첫 화면에 있어야 할 정보는 무엇인가?
- 영향 범위, 시작/종료 시각, 사용자 증상, 현재 상태, 가장 유력한 원인과 신뢰도를 짧게 써야 한다.
- 보고서에서 완화 조치와 근본 수정을 분리해야 하는 이유는 무엇인가?
- 완화는 사용자를 보호한 조치이고 근본 수정은 재발을 줄이는 변경이므로 성공 기준과 owner가 다르기 때문이다.
- 남은 리스크를 보고서에 적어야 하는 이유는 무엇인가?
- 확인하지 못한 가정과 재발 조건을 명시해야 후속 검증과 재발 방지 작업이 빠지지 않기 때문이다.