Files
clean-architecture-backend-…/docs/runbooks/internal-error-spike.md
T
DongHyeonka 13ffb6cfb1 docs(runbooks): runbook 본문의 옛 설계 번호와 커밋 sha를 설명으로 바꾼다
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
2026-11-13 19:30:12 +09:00

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
INTERNAL_ERROR
INTERNAL_AUTH_MISCONFIGURATION
JVM_OOM
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 — 확인

  1. 가장 최근 deploy 시각 확인 (CI/CD dashboard, artifact registry digest)
  2. JVM metric 확인: heap usage, GC pause, CPU, thread count
  3. log에서 실패 request 1건 추출 → request_id, trace_id 확보
  4. 실패 종류 가르기: ERROR 줄 고정 문구 unhandled exception on(분류 안 된 실패, INTERNAL_ERROR) vs failure classified as <code>(분류된 5xx) vs security 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 자동화 절차 점검
  • 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 자동화 명령으로 보강 필요.