Files
clean-architecture-backend-…/docs/runbooks/runtime-jvm-oom.md
T
DongHyeonka 83e9bd3dc3 docs(runbooks): JVM OOM runbook의 종료 코드를 실제 JVM 동작에 맞춘다
runtime-jvm-oom runbook이 「컨테이너가 코드 137로 끝난다
(-XX:+ExitOnOutOfMemoryError가 동작함)」고 적는다. 그 옵션으로 JVM이 스스로
끝나면 종료 코드는 3이고 stderr에 「Terminating due to
java.lang.OutOfMemoryError: …」가 남는다. 137은 SIGKILL이다. 힙이 아니라
프로세스 전체 메모리가 컨테이너 한계를 넘어 커널이 죽인 경우이고, 원인과
볼 것이 다르다(번역 묶음 D2c가 확인 필요로 넘긴 것).

증상 절을 둘로 나눴다: 코드 3 + 그 stderr 줄은 이 runbook, 코드 137 +
OOMKilled는 다른 일(힙과 네이티브 메모리의 합, MaxRAMPercentage가 남긴 몫,
힙 덤프 없음).

검증: desktop에서 이 저장소 이미지(caskeleton:0.0.1_local_0000000-default,
9ae52229)를 공유 잠금 아래 java -Xmx4m·-Xmx6m
-XX:+ExitOnOutOfMemoryError -jar application.jar로 띄웠다. 둘 다 rc=3,
stderr 「Terminating due to java.lang.OutOfMemoryError: Java heap space」.
노트북 check-docs.py OK.

한계: ContainerRuntimeOomContractTest Javadoc의 「exit 137」은 테스트 코드라
이 변경에서 고치지 않았다.
2026-11-07 18:30:03 +09:00

1.7 KiB

title, category, error_codes, severity, owner, last_updated, status
title category error_codes severity owner last_updated status
Runbook — JVM_OOM (JVM OutOfMemoryError) INTERNAL
JVM_OOM
P1 oncall 2026-11-07 초안

Runbook: JVM_OOM (runbook://runtime/jvm-oom)

증상

  • 컨테이너가 코드 3으로 끝나고, stderr 마지막 줄이 Terminating due to java.lang.OutOfMemoryError: <종류>다 (예: Java heap space). 이미지의 JAVA_TOOL_OPTIONS가 -XX:+ExitOnOutOfMemoryError를 켜기 때문이다(src/Dockerfile).
  • 앱은 끝나기 전에 error.code=JVM_OOM 로그를 남기지 않는다. 이 코드를 로그에 쓰는 코드가 없다.
  • 코드 137(SIGKILL)과 OOMKilled: true는 이 runbook의 일이 아니다. 프로세스 전체 메모리가 컨테이너 한계를 넘어 커널이 죽인 것이다. 힙과 그 밖의 네이티브 메모리(스레드 스택, 라이브러리의 네이티브 할당 등)를 합친 크기를 보고, -XX:MaxRAMPercentage가 힙 밖에 남긴 몫이 모자라는지 본다. JVM이 손쓸 틈 없이 죽으므로 힙 덤프도 없다.

진단

  • 힙 덤프를 본다. 이미지의 JAVA_TOOL_OPTIONS가 -XX:+HeapDumpOnOutOfMemoryError와 -XX:HeapDumpPath=/var/tmp/heap을 켠다(src/Dockerfile).
  • 죽기 전 메모리 사용 추세를 본다.
  • 메모리 누수를 찾는다: 커지기만 하는 캐시, 상한 없는 목록, 쌓이는 세션.

조치

  • 컨테이너를 바로 다시 띄운다(k8s는 liveness probe로 알아서 다시 띄운다).
  • 반복되면 힙(-Xmx, 이미지는 -XX:MaxRAMPercentage)을 늘리거나 누수를 고친다.

에스컬레이션

  • P1: 여러 pod가 동시에 죽으면 즉시.
  • 힙 분석은 SRE·인프라 팀을 부른다.

초안: 서비스가 도메인을 채운 뒤 본문을 쓴다.