Files
clean-architecture-backend-…/docs/runbooks/internal-error-spike.md
T
DongHyeonka 23139722e8 fix(compose): heap dump 경로를 컨테이너 메모리 한계 안의 tmpfs에 두지 않는다
문제: 기본 compose.yaml은 -XX:HeapDumpPath=/var/tmp/heap을 512m tmpfs로
붙였다. 컨테이너는 mem_limit 512m·swap 없음이고 힙은 그 75%(384m)다.
tmpfs에 쓴 페이지는 같은 컨테이너 메모리 한계에 잡힌다. 그래서
OutOfMemoryError 때 덤프를 쓰는 동안 컨테이너가 OOM kill(137)될 수 있었고,
runbook이 기대하는 깨끗한 끝(코드 3, ExitOnOutOfMemoryError)이 사라졌다.
덤프가 끝까지 써져도 tmpfs는 컨테이너가 끝나면 함께 사라져 읽을 수 없었다.
Dockerfile 주석은 오케스트레이터에 그 경로를 tmpfs로 붙이라고 했고,
internal-error-spike runbook은 없는 파일 이름(heapdump-<pid>.hprof)을 적었다.

고른 방법:
- 기본 compose.yaml은 그 경로에 아무것도 붙이지 않는다. 루트가 읽기
  전용이라 JVM은 파일을 만들지 못하고 바로 코드 3으로 끝난다. 덤프를 남기는
  dev lane(named volume heap-dumps)은 그대로다.
- scripts/verify-compose-profile-contracts.sh(prCheck의
  verifyComposeProfiles)가 모든 lane에서 그 경로의 tmpfs를 거절한다. 경로는
  Dockerfile의 -XX:HeapDumpPath에서 읽는다.
- Dockerfile 주석과 runbook 둘(runtime-jvm-oom 「진단」, internal-error-spike)에
  덤프를 남기는 법(Kubernetes emptyDir without medium: Memory·PV, dev lane
  volume)과 실제 파일 이름(java_pid<pid>.hprof)을 적었다.
- 버린 대안: 기본 compose에 named volume을 붙이기 — 기본 조립은 디스크에
  아무것도 남기지 않는다는 결정(compose.yaml 「No volume」 주석)과 다르다.
- 고치며 찾은 것(RR9-03-30): ComposeMergeCharacterizationTest는 어느 lane에서도
  돌지 않았다. integrationTest lane은 requires로 적은 클래스 넷만 고른다
  (StrictTestLanePlugin). 그 시험이 보던 기본·dev 조합 렌더링과 계약 스크립트는
  verifyComposeProfiles가 18개 lane으로 이미 본다. 시험과, 그 lane에 compose
  파일을 입력으로 선언하던 블록을 지웠다.

검증(desktop):
- RED: 기준 ca1fbfde + 검사 스크립트만으로 :verifyComposeProfiles 실패
  (기본 compose를 쓰는 lane마다 「heap dump path ... as a tmpfs」).
- 탐침(eclipse-temurin:21-jdk, 읽기 전용 루트, 메모리 192m·swap 없음,
  -Xmx96m으로 OutOfMemoryError):
  경로에 아무것도 없음 → "Unable to create /var/tmp/heap: Read-only file
  system", 코드 3. tmpfs → 덤프를 쓰다 코드 137(OOM kill). 디스크 마운트 →
  덤프 101MB가 남고 코드 3.
- GREEN: :verifyComposeProfiles(18 lane), :app-bootstrap:integrationTest,
  repositoryContractTest, spotlessCheck — 71건 실패 0, skip 1, rc=0.
2026-11-13 03:55:38 +09:00

3.2 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-05-22 초안

Runbook: 5xx Internal error spike

1. Trigger

이 runbook은 다음 alert가 울리면 쓴다.

  • alert name: http_5xx_error_rate_critical
  • alert payload 필수 field: operation, error.code, error.category, request_id, traceId, runbook_link
  • 임계: 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, traceId 확보
  4. error.code 분포 확인: INTERNAL_ERROR vs JVM_OOM vs INTERNAL_AUTH_MISCONFIGURATION

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: {service="app"} | http.status>=500 | stats count by 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의 traceId로 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 분석
    • 외부 의존성 설정 오류 (INTERNAL_AUTH_MISCONFIGURATION) → config secret 확인
    • 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 자동화 절차 점검

Stub 상태 안내: 이 runbook은 skeleton 단계의 stub. 도메인 도입 시 실제 deploy 파이프라인·heap dump 보관 경로·rollback 자동화 명령으로 보강 필요.