[Troubleshooting] Docker OOMKilled (Exit Code 137) 에러의 진실: 컨테이너 메모 누수 방어 및 리소스 최적화 아키텍처

"새벽에 이커머스 결제 컨테이너가 죽어버렸습니다. 로그를 뒤져보니 아무런 에러 코드도 없고 단지 `Exit Code 137` 하나만 덩그러니 남아있습니다."

도커(Docker)와 쿠버네티스(Kubernetes) 기반의 마이크로서비스 아키텍처를 운영하는 데브옵스(DevOps) 엔지니어들을 가장 공포에 떨게 하는 에러, 바로 OOMKilled (Out of Memory Killed) 현상이다. 애플리케이션의 버그라면 스택 트레이스(Stack Trace)라도 남아 코드를 고칠 텐데, 이 현상은 범인이 애플리케이션이 아니기 때문에 로그조차 남지 않고 프로세스가 흔적 없이 암살당한다.

이 미스터리한 살인 사건의 범인은 바로 리눅스 커널(Linux Kernel)의 OOM Killer다. 본 가이드에서는 왜 운영체제가 자신이 품고 있는 도커 컨테이너를 가차 없이 죽여버리는지 그 매커니즘을 해체하고, 메모리 누수로 인한 인프라 붕괴를 원천 차단하는 방어 아키텍처를 단호하게 제시한다.

1단계: 핵심 원인 분석 (Exit Code 137의 의미)

137이라는 숫자는 수학적인 의미를 갖는다. 리눅스에서 128 + 9 (SIGKILL) = 137이다. 즉, 누군가 "묻지도 따지지도 말고 즉시 죽어라"라는 9번 시그널(Kill)을 보냈다는 뜻이다. 도커 컨테이너 내부의 자바(Java), 파이썬(Python) 프로세스가 할당된 메모리(RAM) 한계치를 초과하여 호스트 OS 전체를 멈추게 할 위험이 감지되는 순간, 리눅스 커널은 생존을 위해 가장 메모리를 많이 파먹는 뚱뚱한 컨테이너를 찾아내 단칼에 목을 친다.

2단계: 해결책 - Cgroups 리소스 하드 리미트(Hard Limit) 통제

많은 개발자가 "서버 램이 32GB나 되는데 왜 컨테이너가 죽나요?"라고 묻는다. 도커를 실행할 때 메모리 제한(Limit)을 걸어두지 않으면, 컨테이너 내의 프로세스(JVM 등)는 호스트의 32GB 전체가 자기 것인 줄 착각하고 무한히 힙(Heap) 메모리를 팽창시킨다. 이를 막기 위해서는 `docker-compose.yml`이나 `docker run` 명령어에 반드시 엄격한 제약을 걸어 운영체제의 Cgroups(Control Groups)가 이를 통제하게 만들어야 한다.

# 완벽하게 리소스가 통제된 docker-compose.yml 방어 아키텍처
version: '3.8'
services:
  backend-api:
    image: my-backend-api:latest
    deploy:
      resources:
        limits:
          cpus: '1.0'           # CPU 코어 최대 1개만 사용
          memory: 1024M         # 컨테이너의 절대적 하드 리미트 (이 이상 쓰면 OOMKilled)
        reservations:
          cpus: '0.2'           # 최소 보장 CPU
          memory: 512M          # 최소 보장 메모리
    environment:
      # (중요) Java 기반일 경우, JVM이 도커 리미트를 인식하도록 옵션 필수 부여
      - JAVA_OPTS="-XX:MaxRAMPercentage=75.0"

위와 같이 `limits`를 설정하면, 프로세스가 메모리를 무한정 요구하더라도 1024M에서 정확히 벽에 부딪힌다. 자바(JVM)나 Node.js 같은 언어들은 이 한계에 도달하면 스스로 가비지 컬렉터(Garbage Collector)를 미친 듯이 가동하여 메모리를 확보하며 살아남는다.

3단계: 추가 최적화 (Swappiness 및 OOM_Score_Adj)

컨테이너가 메모리 한계에 다다랐을 때 하드디스크를 메모리처럼 사용하는 스왑(Swap) 현상이 발생하면 서버 전체의 I/O 병목이 발생해 사이트가 멈춘다. 엔터프라이즈 환경에서는 `memory-swap` 값을 `memory` 값과 동일하게 맞추어 스왑을 원천 차단(Disable)하는 것이 정석이다. 또한 호스트 OS가 핵심 데이터베이스 컨테이너를 죽이는 것을 막고 싶다면, 도커 실행 시 `--oom-score-adj=-500` 옵션을 주어 킬러의 타겟 순위에서 해당 컨테이너를 밑으로 빼돌려야 한다.

아키텍트의 시선 (Insight)

OOMKilled는 인프라의 장애가 아니다. 탐욕스럽게 메모리를 먹어 치우는 당신의 애플리케이션 코드를 돌아보라는 시스템의 강력한 채찍질이다. 자원을 무한정 늘려 에러를 덮는 아마추어적인 접근을 버려라. Cgroups의 엄격한 리소스 통제(Limit)와 예약(Reservation) 아키텍처를 도입하여, 어떤 트래픽의 파도 속에서도 서버 전체의 무결성을 지켜내는 강인한 격벽(Bulkhead)을 구축하라.

댓글

댓글 쓰기

이 블로그의 인기 게시물

[Troubleshooting] 504 Gateway Timeout 에러 완벽 방어: 파이썬(Python) Celery와 Redis 기반 비동기 백그라운드 아키텍처

"어드민(Admin) 페이지에서 10만 건짜리 매출 데이터 엑셀 다운로드 버튼을 누르면, 화면이 30초 동안 멈춰있다가 결국 하얀 바탕에 '504 Gateway Timeout' 에러만 뜹니다." 엔터프라이즈 B2B 솔루션이나 사내 인트라넷을 개발하는 백엔드 팀이 가장 뼈아프게 마주하는 시스템의 붕괴점이다. 초보 개발자들은 이 에러를 보면 Nginx 프록시 설정 파일( nginx.conf )을 열어서 proxy_read_timeout 값을 30초에서 300초로 무식하게 늘려버린다. 하지만 이는 시한폭탄의 타이머를 늦췄을 뿐, 여러 명의 직원이 동시에 다운로드를 누르면 결국 웹 서버 워커(Worker)가 모두 고갈되어 사이트 전체가 마비되는 대참사로 이어진다. 본 가이드에서는 클라이언트를 기다리게 만드는 무능한 동기식(Synchronous) 설계의 한계를 해체하고, 메시지 브로커(Message Broker)를 활용하여 작업을 백그라운드로 우아하게 던져버리는 비동기(Asynchronous) 아키텍처를 단호하게 제시한다. 1단계: 핵심 원인 분석 (동기식 HTTP 통신의 족쇄) 웹 브라우저와 Nginx(또는 AWS ALB) 간의 HTTP 통신은 철저히 동기식이다. 사용자가 요청을 보내면, 응답이 올 때까지 브라우저와 프록시 서버는 연결 통로(Connection)를 잡고 하염없이 기다린다. 만약 DB에서 10만 건의 데이터를 조회하고 엑셀로 변환하는 데 60초가 걸린다면? 30초를 한계치로 설정해 둔 Nginx는 "이 서버는 죽었다"고 판단하고 연결을 강제로 끊어버린 뒤 클라이언트에게 504 에러를 던지는 것이다. 2단계: 완벽한 해결책 - Celery + Redis 비동기 아키텍처 해결책은 무거운 작업을 웹 서버(Django, FastAPI 등)가 직접 처리하지 않게 분리(Decoupling)하는 것이다. 웹 서버는 "작업 접수 완료!"라는 짧은 대답만 0.1초 만에 유저에게 ...
자세한 내용 보기

[Troubleshooting] 리액트(React) & 뷰(Vue) SPA 웹사이트 GA4 페이지뷰 누락 완벽 해결 아키텍처

"웹사이트 트래픽은 엄청난데, 구글 애널리틱스(GA4)를 보면 사용자들이 페이지를 하나만 보고 100% 이탈한 것으로 나옵니다." 리액트(React), 뷰(Vue), 넥스트(Next.js) 등으로 개발된 현대적인 SPA(Single Page Application) 웹사이트를 운영하는 퍼포먼스 마케터들이 가장 먼저 겪는 치명적인 데이터 누수 현상이다. 눈으로 볼 때는 분명히 사용자가 '메인 페이지 → 상품 페이지 → 결제 페이지'로 이동하고 있는데, GA4 대시보드에는 오직 '메인 페이지' 조회수 1건만 찍혀 있다. 이 에러를 방치하면 마케팅 부서는 어떤 페이지가 전환을 일으키는지 전혀 추적할 수 없게 되어 광고비를 허공에 날리게 된다. 본 가이드에서는 SPA 라우팅의 본질적 한계를 해체하고, 구글 태그 매니저(GTM)를 활용해 자바스크립트의 가상 이동을 완벽하게 추적하는 '가상 페이지뷰(Virtual Pageview)' 아키텍처를 단호하게 제시한다. 1단계: 핵심 원인 분석 (물리적 새로고침의 부재) 기존의 전통적인 웹사이트는 링크를 클릭할 때마다 브라우저가 '물리적으로(Physically)' 새로고침되며 구글 애널리틱스 스크립트가 매번 다시 실행되었다. 하지만 SPA는 최초 1회만 사이트를 로드한 뒤, 화면의 껍데기만 자바스크립트로 바꿔치기한다. 브라우저 입장에서는 URL 주소창의 글자만 바뀌었을 뿐 새로고침이 일어나지 않았기 때문에, GA4 스크립트는 "사용자가 계속 첫 페이지에 머물고 있다"고 착각하는 것이다. 2단계: 1차 방어선 - 향상된 측정(Enhanced Measurement)의 한계 인지 GA4 설정에 들어가면 '향상된 측정' 기능 내에 '브라우저 기록 이벤트를 기반으로 한 페이지 변경'을 추적하는 옵션이 기본적으로 켜져 있다. 초보자들은 이것만 믿고 안심하지만, 복잡한 매개변수가 붙거나 비동기(Asyn...
자세한 내용 보기

[Troubleshooting] AWS Lambda 콜드 스타트(Cold Start) 지연 완벽 해결: Provisioned Concurrency 및 메모리 최적화 아키텍처

"비용을 줄이려고 백엔드 API를 AWS Lambda로 옮겼는데, 사용자가 처음 접속할 때마다 로딩이 5초나 걸려서 새로고침을 연타합니다." 서버를 직접 관리하지 않아도 되는 서버리스(Serverless) 아키텍처의 달콤한 환상에 빠진 B2B 스타트업들이 가장 먼저 부딪히는 거대한 빙산, 바로 '콜드 스타트(Cold Start)' 현상이다. AWS Lambda는 요청이 들어올 때만 컨테이너를 띄워 코드를 실행하고, 일정 시간 요청이 없으면 자원을 회수해 버린다. 문제는 이 '컨테이너를 새로 띄우고(Init) 런타임을 구동하는' 찰나의 과정이 유저에게는 끔찍한 서비스 지연(Latency)으로 체감된다는 것이다. 개발자들은 이 문제를 해결한답시고 5분마다 CloudWatch 이벤트를 날려 람다를 억지로 깨워두는(Ping) 원시적인 '웜업(Warm-up)' 꼼수를 쓴다. 하지만 트래픽이 동시에 폭주하여 여러 개의 컨테이너가 병렬로 떠야 할 때, 이 꼼수는 아무런 힘도 쓰지 못하고 무너진다. 본 가이드에서는 OS 런타임 레벨에서 콜드 스타트를 해체하고, 엔터프라이즈급 지연 제로(Zero-Latency) 아키텍처를 단호하게 제시한다. 1단계: 핵심 원인 분석 (Init Phase의 병목) 콜드 스타트 지연의 80%는 코드가 실행되는 시간이 아니라, 코드가 실행될 '환경'을 세팅하는 데서 발생한다. 특히 VPC(가상 사설망) 내부에 Lambda를 배포하여 RDS(데이터베이스)와 통신하게 만들 경우, 과거에는 ENI(탄력적 네트워크 인터페이스)를 생성하는 데만 수 초가 소요되었다. 또한 Java나 C# 같이 무거운 JVM 런타임을 사용하는 언어는 파이썬(Python)이나 Node.js보다 태생적으로 콜드 스타트가 3배 이상 길 수밖에 없다. 2단계: 1차 방어선 - 메모리 과대 적재(Over-provisioning) 가장 빠르고 극적인 해결책은 Lambda의 메모리 할당량을 ...
자세한 내용 보기