job·outbox·internal-error-spike runbook이 근거를 템플릿 개발 때의 설계 번호(D2·D4·D7·D8, K8S-POD-LC-C2, WAF-REL05-C3, TPE-JDK21-C6, OUT_OF_BRANCH_SCOPE), 옛 feature 브랜치 이름의 wiki 링크, 커밋 sha bbe944bd로 적는다. 파생 서비스의 운영자는 그 번호와 브랜치를 찾을 수 없어 근거를 읽지 못한다. 번호마다 그 뜻을 문장으로 쓴다: 한도 없는 queue가 무너지는 이유, CallerRunsPolicy가 요청 지연을 늘리는 이유, 종료 대기 19s와 k8s grace period의 SIGKILL, 다시 해도 같은 오류는 곧바로 DLQ로. PARKED가 생긴 버전은 커밋 sha 대신 V22 migration으로 가리킨다. 「관련 branch」 줄은 지우고, 「관련 runbook」의 wiki 링크는 상대 링크로 바꾼다. 위험: 문서만 바뀐다. 절차와 SQL 블록은 그대로다. 검증: python3 scripts/check-work-docs.py --history docs/runbooks에서 걸린 줄 0, check-docs.py OK. Refs: round9 그룹 A 범위 밖 후속 6
3.8 KiB
3.8 KiB
title, category, error_codes, severity, owner, last_updated, status
| title | category | error_codes | severity | owner | last_updated | status | |||
|---|---|---|---|---|---|---|---|---|---|
| Runbook — 5xx Internal error spike | INTERNAL |
|
P1 | oncall | 2026-11-13 | 초안 |
Runbook: 5xx Internal error spike
1. Trigger
이 runbook은 아래 신호로 서비스가 만든 경보가 울리면 쓴다. 이 템플릿은 경보 규칙을 두지 않는다. 경보 이름과 싣는 값은 서비스가 정한다.
- 경보에 실을 만한 값: MDC
request_id·trace_id, ERROR 줄의 고정 문구(unhandled exception on <경로>,failure classified as <code> (category=…, retryable=…)),http.server.requests의status. 5xx 줄에는error.code·error.category구조화 칸이 없고 코드는 메시지 글자로만 남는다(ServerFailureLog) - 임계: 5xx error rate > 5% 5분 지속 OR > 10% 1분
2. First Response (5분 이내)
Step 1 — 확인
- 가장 최근 deploy 시각 확인 (CI/CD dashboard, artifact registry digest)
- JVM metric 확인: heap usage, GC pause, CPU, thread count
- log에서 실패 request 1건 추출 →
request_id,trace_id확보 - 실패 종류 가르기: ERROR 줄 고정 문구
unhandled exception on(분류 안 된 실패,INTERNAL_ERROR) vsfailure classified as <code>(분류된 5xx) vssecurity failure: code=INTERNAL_AUTH_MISCONFIGURATION. OOM은 로그 코드가 아니라runtime-jvm-oom.md의 신호로 본다
Step 2 — 임시 격리
- 직전 deploy가 의심되면 즉시 rollback (artifact registry에서 직전 image digest pin)
- OOM 패턴이면 affected pod evict → ASG/HPA로 replacement 유도
- LB에서 unhealthy pod 격리 (readiness probe failure 유도)
3. Diagnosis
- log query: ERROR 줄을 위 고정 문구별로 센다(예:
{service="app"} |= "unhandled exception on"). 로그에는http.status·error.code칸이 없다 - metric panel:
jvm_memory_used_bytes{area="heap"},jvm_gc_pause_seconds,process_cpu_seconds_total,http_server_requests_seconds_count{status=~"5.."} - trace: 실패 request의
trace_id로 span chain 확인 → stack trace에서 root exception 추출 - heap dump 위치:
/var/tmp/heap/java_pid<pid>.hprof(-XX:HeapDumpPath=/var/tmp/heap). 그 경로에 디스크 볼륨을 붙인 배포에만 남는다. 읽는 법은docs/runbooks/runtime-jvm-oom.md「진단」 - 가능한 원인:
- 직전 deploy의 회귀 버그 → rollback
- JVM OOM (메모리 leak 또는 부하 증가) → heap dump 분석(
runtime-jvm-oom.md) - JWT decoder 설정 오류 (
INTERNAL_AUTH_MISCONFIGURATION) → issuer 설정과 discovery(auth-decoder-misconfiguration.md) - thread starvation (pool 고갈) → thread dump (
jstack <pid>)
4. Mitigation
- 단기: 직전 deploy rollback, OOM pod replacement, traffic 일시 감소(scale-out 또는 rate-limit 강화)
- config 오류면 secret/configmap rollback
- 장기: heap dump 기반 leak 수정, capacity planning 재검토
5. Escalation
- 다음 on-call로 page: 10분 내 회복 안 되면 incident commander 호출, severity 1 incident 선언
- 데이터 손상 의심되면 DBA team page
6. Recovery / Verification
- 회복 확인 metric: 5xx rate < 0.5% 5분 지속, JVM heap usage < 70%, GC pause p99 < 500ms
- post-incident:
- rollback 원인 RCA 작성 (배포 게이트 강화 필요 여부)
- heap dump 분석 결과 공유
- JVM ergonomics(
-XX:MaxRAMPercentage) 재검토 - rollback 자동화 절차 점검
7. Related
- error-codes.yaml rows:
INTERNAL_ERROR,INTERNAL_AUTH_MISCONFIGURATION,JVM_OOM - metrics.yaml:
jvm_memory_used_bytes,jvm_gc_pause_seconds,http_server_requests_seconds_count
Stub 상태 안내: 이 runbook은 skeleton 단계의 stub. 도메인 도입 시 실제 deploy 파이프라인·heap dump 보관 경로·rollback 자동화 명령으로 보강 필요.