--- title: Runbook — JVM_OOM (JVM OutOfMemoryError) category: INTERNAL error_codes: [JVM_OOM] severity: P1 owner: oncall last_updated: 2026-11-07 status: 초안 --- # Runbook: JVM_OOM (`runbook://runtime/jvm-oom`) ## 증상 - 컨테이너가 코드 3으로 끝나고, stderr 마지막 줄이 `Terminating due to java.lang.OutOfMemoryError: <종류>`다 (예: `Java heap space`). 이미지의 `JAVA_TOOL_OPTIONS`가 `-XX:+ExitOnOutOfMemoryError`를 켜기 때문이다(`Dockerfile`). - 앱은 끝나기 전에 `error.code=JVM_OOM` 로그를 남기지 않는다. 이 코드를 로그에 쓰는 코드가 없다. - 코드 137(SIGKILL)과 `OOMKilled: true`는 이 runbook의 일이 아니다. 프로세스 전체 메모리가 컨테이너 한계를 넘어 커널이 죽인 것이다. 힙과 그 밖의 네이티브 메모리(스레드 스택, 라이브러리의 네이티브 할당 등)를 합친 크기를 보고, `-XX:MaxRAMPercentage`가 힙 밖에 남긴 몫이 모자라는지 본다. JVM이 손쓸 틈 없이 죽으므로 힙 덤프도 없다. ## 진단 - 힙 덤프를 본다. 이미지의 `JAVA_TOOL_OPTIONS`가 `-XX:+HeapDumpOnOutOfMemoryError`와 `-XX:HeapDumpPath=/var/tmp/heap`을 켠다(`Dockerfile`). 파일은 `/var/tmp/heap/java_pid.hprof`다. - 덤프는 그 경로에 디스크 볼륨을 붙였을 때만 남는다. - Kubernetes: `medium: Memory`가 없는 emptyDir나 PersistentVolume. emptyDir는 컨테이너가 다시 떠도 남는다. `kubectl cp :/var/tmp/heap/java_pid1.hprof .`로 꺼낸다. - compose dev lane: named volume `heap-dumps`. `docker compose cp app:/var/tmp/heap/<파일> .`로 꺼낸다. - 기본 `compose.yaml`: 그 경로에 아무것도 붙이지 않는다. 루트가 읽기 전용이라 JVM이 파일을 못 만들고 바로 코드 3으로 끝난다. tmpfs는 쓰지 않는다. 컨테이너 메모리 한계에 함께 잡혀 덤프 중 OOM kill(코드 137)이 나고, 컨테이너가 끝나면 함께 사라진다. - 죽기 전 메모리 사용 추세를 본다. - 메모리 누수를 찾는다: 커지기만 하는 캐시, 상한 없는 목록, 쌓이는 세션. ## 조치 - 컨테이너를 바로 다시 띄운다(k8s는 liveness probe로 알아서 다시 띄운다). - 반복되면 힙(`-Xmx`, 이미지는 `-XX:MaxRAMPercentage`)을 늘리거나 누수를 고친다. ## 에스컬레이션 - P1: 여러 pod가 동시에 죽으면 즉시. - 힙 분석은 SRE·인프라 팀을 부른다. --- > **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다.