[TIL] libuv와 OS 메모리 - OOM의 진짜 원인?

┌──────────────────────────────────────────────┐
│  JavaScript 코드 (우리가 쓰는 코드)           │
├──────────────────────────────────────────────┤
│  Node.js API (fs, net, http, stream, ...)    │
│  → JS + C++ 바인딩                           │
├──────────────────────────────────────────────┤
│  V8 Engine          │  Node.js C++ bindings  │
│  (JS 실행, Heap,    │  (node_buffer.cc,      │
│   GC)               │   node_file.cc, ...)   │
├─────────────────────┼────────────────────────┤
│                     │  libuv                  │
│                     │  (이벤트 루프, 비동기    │
│                     │   I/O, 스레드 풀)       │
├──────────────────────────────────────────────┤
│  OS Kernel (syscall, epoll/kqueue, TCP/IP)   │
└──────────────────────────────────────────────┘

libuv 이벤트 루프의 각 phase:
 
   ┌───────────────────────────┐
┌→ │        timers              │  ← setTimeout, setInterval 콜백
│  └────────────┬──────────────┘
│  ┌────────────┴──────────────┐
│  │     pending callbacks     │  ← 이전 루프에서 지연된 I/O 콜백
│  └────────────┬──────────────┘
│  ┌────────────┴──────────────┐
│  │       idle, prepare       │  ← 내부용
│  └────────────┬──────────────┘
│  ┌────────────┴──────────────┐
│  │          poll              │  ← I/O 이벤트 대기 (핵심!)
│  │  (epoll/kqueue/IOCP)      │     여기서 네트워크, 파일 I/O 완료를 감지
│  └────────────┬──────────────┘
│  ┌────────────┴──────────────┐
│  │          check             │  ← setImmediate 콜백
│  └────────────┬──────────────┘
│  ┌────────────┴──────────────┐
│  │     close callbacks       │  ← socket.on('close') 등
│  └────────────┬──────────────┘
└───────────────┘

libuv가 할당하는 메모리 (V8에 보이지 않음):
 
1. 핸들(Handle)
   - uv_tcp_t, uv_udp_t, uv_fs_t, uv_timer_t 등
   - TCP 커넥션 하나당 uv_tcp_t 구조체 하나 (수백 바이트)
   - 10만 커넥션이면 ~수십MB
 
2. 스레드 풀 스택
   - 기본 4개 스레드 (UV_THREADPOOL_SIZE로 조절 가능, 최대 1024)
   - 스레드 하나당 스택 ~2MB (OS 기본값)
   - 기본 설정: 4 × 2MB = ~8MB
 
3. I/O 버퍼
   - 네트워크 데이터 수신 시 libuv가 할당하는 read buffer
   - alloc_cb 콜백으로 크기를 제어할 수 있음

// 스레드 풀 크기 확인 및 조절
console.log(process.env.UV_THREADPOOL_SIZE); // 기본: undefined (4개)
 
// 더 많은 병렬 파일 I/O가 필요하면:
// UV_THREADPOOL_SIZE=16 node server.js
// → 16개 스레드 × ~2MB 스택 = ~32MB 추가 메모리

// libuv src/unix/stream.c (개념적 흐름)
static void uv__read(uv_stream_t* stream) {
  // 1. Node.js에 "버퍼를 할당해줘" 요청 (alloc_cb 호출)
  //    → Node.js는 여기서 Buffer를 할당해서 반환
  buf = stream->alloc_cb(stream, suggested_size);
 
  // 2. OS로부터 데이터를 읽어서 그 버퍼에 채움
  nread = read(stream->io_watcher.fd, buf.base, buf.len);
 
  // 3. Node.js에 "데이터 왔어" 콜백 (read_cb 호출)
  //    → Node.js는 이걸 'data' 이벤트로 JS에 전달
  stream->read_cb(stream, nread, &buf);
}

네트워크 데이터가 JS까지 올라오는 경로:
 
OS kernel (TCP 수신 버퍼)
  ↓ read() syscall
libuv (alloc_cb로 Buffer 할당)
  ↓ read_cb
Node.js C++ 바인딩
  ↓ 'data' event
JS 코드의 socket.on('data', callback)

64비트 프로세스의 가상 주소 공간:
 
0x000000000000 ┌────────────────────┐
               │  코드 세그먼트       │  ← 실행 파일, 공유 라이브러리
               ├────────────────────┤
               │  데이터 세그먼트     │  ← 전역 변수
               ├────────────────────┤
               │  Heap (V8 + malloc) │  ← 동적 할당 (위로 성장)
               │       ↓            │
               │     (빈 공간)       │
               │       ↑            │
               │  Stack             │  ← 함수 호출 스택 (아래로 성장)
               ├────────────────────┤
               │  mmap 영역          │  ← 메모리 맵핑 파일, 공유 메모리
               ├────────────────────┤
               │  커널 영역           │
0xFFFFFFFFFFFF └────────────────────┘
 
VSZ = 이 전체 가상 공간의 크기
→ 실제로 물리 메모리에 올라가지 않은 부분도 포함
→ 그래서 VSZ가 매우 커도 실제 메모리 사용은 적을 수 있다

가상 페이지 → 물리 페이지 매핑:
 
가상 주소 공간          물리 메모리 (RAM)
┌──────┐              ┌──────┐
│ 페이지1│ ────→       │ 프레임A│  ← 매핑됨 (RSS에 포함)
├──────┤              ├──────┤
│ 페이지2│ (미접근)     │ 프레임B│  ← 다른 프로세스 사용 중
├──────┤              ├──────┤
│ 페이지3│ ────→       │ 프레임C│  ← 매핑됨 (RSS에 포함)
├──────┤              └──────┘
│ 페이지4│ → swap      디스크
├──────┤              ┌──────┐
│ 페이지5│ (미접근)     │ swap │  ← 물리 메모리에 없음
└──────┘              └──────┘
 
RSS = 페이지1 + 페이지3 = 실제 RAM에 올라간 것만
VSZ = 페이지1~5 전체 = 가상 공간 전체

# Node.js 프로세스의 VSZ와 RSS 확인
ps aux | grep node
# USER  PID  %CPU %MEM   VSZ    RSS  TTY STAT TIME COMMAND
# yeji  1234  0.5  1.2  890000  45000 ...  node server.js
#                       ↑ VSZ    ↑ RSS (KB 단위)

Demand Paging (지연 할당):
 
1. malloc(100MB) 호출
   → OS: "가상 주소 100MB 예약해줄게" (VSZ += 100MB)
   → 물리 메모리는 아직 0 할당 (RSS 변동 없음)
 
2. 첫 번째 페이지에 쓰기: buffer[0] = 1
   → Page Fault 발생! (Minor)
   → OS: "아, 진짜 쓰네. 물리 페이지 하나 할당할게" (RSS += 4KB)
 
3. 두 번째 페이지에 쓰기: buffer[4096] = 1
   → 또 Page Fault
   → OS: 물리 페이지 하나 더 할당 (RSS += 4KB)
 
→ 100MB를 malloc해도, 실제로 1MB만 접근하면 RSS는 ~1MB만 증가한다

// Buffer.alloc(100MB) → 0으로 초기화 → 모든 페이지에 쓰기 발생
// → 즉시 RSS가 ~100MB 증가
 
// Buffer.allocUnsafe(100MB) → 초기화 안 함 → 아직 접근 안 한 페이지는 물리 할당 안 됨
// → RSS는 실제로 접근한 부분만큼만 증가
// (단, 작은 크기에서는 pool을 사용하므로 이 차이가 드러나지 않을 수 있음)

# 프로세스의 page fault 통계 확인 (Linux)
cat /proc/[PID]/stat | awk '{print "minor:", $10, "major:", $12}'
 
# 또는 time 명령으로
/usr/bin/time -v node server.js 2>&1 | grep "page faults"
# Minor (reclaiming) page faults: 15234
# Major (requiring I/O) page faults: 0    ← 0이 정상

# K8s Pod 설정 예시
resources:
  limits:
    memory: "512Mi"   # ← 이게 cgroup 메모리 제한이 된다
  requests:
    memory: "256Mi"

cgroup 메모리 제한의 범위:
 
cgroup memory limit (512MB)
┌─────────────────────────────────────────────────┐
│                                                  │
│  Node.js 프로세스 RSS                             │
│  ├── V8 Heap (heapUsed + 빈 공간)                │
│  ├── Buffer / ArrayBuffer (external)             │
│  ├── libuv (핸들, 스레드 스택)                    │
│  ├── JIT 코드 (Code Space)                       │
│  ├── 공유 라이브러리 (.so 파일 매핑)              │
│  └── 기타 (스택, 환경 변수 등)                    │
│                                                  │
│  + 커널 메모리 (page cache, slab 등) ← 이것도!    │
│                                                  │
└─────────────────────────────────────────────────┘
                ↑
   이 전체 합이 512MB를 넘으면 → OOM Killer 발동

# 프로세스의 oom_score 확인 (Linux)
cat /proc/[PID]/oom_score        # 0~1000, 높을수록 먼저 죽음
cat /proc/[PID]/oom_score_adj    # -1000~1000, 관리자가 조정 가능
 
# cgroup 메모리 사용량 확인 (cgroup v2)
cat /sys/fs/cgroup/memory.current     # 현재 사용량 (bytes)
cat /sys/fs/cgroup/memory.max         # 제한 (bytes)
 
# K8s에서 확인
kubectl top pod [pod-name]
kubectl describe pod [pod-name] | grep -A5 "Last State"
# OOMKilled이면 exit code 137 (128 + 9 = SIGKILL)

잘못된 설정:
  cgroup limit:          512MB
  --max-old-space-size:  1024MB   ← V8은 1GB까지 Heap을 키울 수 있다고 생각
 
  → V8이 Heap을 600MB로 키우려는 순간
  → RSS가 cgroup 512MB를 넘김
  → OS가 SIGKILL (exit 137)
  → V8의 "JavaScript heap out of memory" 메시지도 안 뜸!
 
올바른 설정:
  cgroup limit:          512MB
  --max-old-space-size:  384MB    ← 나머지 ~128MB는 Buffer, libuv, 스택 등에 여유

// 프로그래밍 방식으로 cgroup 제한을 읽어서 자동 설정하는 패턴
const os = require('os');
const fs = require('fs');
 
function getMemoryLimit() {
  try {
    // cgroup v2
    const limit = fs.readFileSync('/sys/fs/cgroup/memory.max', 'utf8').trim();
    if (limit !== 'max') return parseInt(limit);
  } catch {}
 
  try {
    // cgroup v1
    const limit = fs.readFileSync(
      '/sys/fs/cgroup/memory/memory.limit_in_bytes', 'utf8'
    ).trim();
    const parsed = parseInt(limit);
    // 매우 큰 값이면 제한 없음
    if (parsed < os.totalmem()) return parsed;
  } catch {}
 
  return os.totalmem(); // cgroup 없으면 시스템 전체 메모리
}
 
const limitMB = Math.floor(getMemoryLimit() / 1024 / 1024);
console.log(`Memory limit: ${limitMB}MB`);
// → 이 값의 약 75%를 --max-old-space-size로 설정하는 것이 안전

// 종합 메모리 모니터링
const v8 = require('v8');
const os = require('os');
 
function memoryReport() {
  const proc = process.memoryUsage();
  const heap = v8.getHeapStatistics();
 
  return {
    // OS 레벨
    rss_mb: (proc.rss / 1024 / 1024).toFixed(1),
    system_total_mb: (os.totalmem() / 1024 / 1024).toFixed(0),
    system_free_mb: (os.freemem() / 1024 / 1024).toFixed(0),
 
    // V8 Heap
    heap_used_mb: (proc.heapUsed / 1024 / 1024).toFixed(1),
    heap_total_mb: (proc.heapTotal / 1024 / 1024).toFixed(1),
    heap_limit_mb: (heap.heap_size_limit / 1024 / 1024).toFixed(0),
 
    // Off-heap
    external_mb: (proc.external / 1024 / 1024).toFixed(1),
    array_buffers_mb: (proc.arrayBuffers / 1024 / 1024).toFixed(1),
 
    // 계산값: "설명 안 되는" 메모리
    // RSS - (heapTotal + external) = libuv, 스택, 코드, page cache 등
    unaccounted_mb: (
      (proc.rss - proc.heapTotal - proc.external) / 1024 / 1024
    ).toFixed(1),
  };
}
 
// 주기적 로깅
setInterval(() => {
  console.log(JSON.stringify(memoryReport()));
}, 30_000);

# 프로세스 상세 메모리 맵
cat /proc/[PID]/status | grep -E "VmRSS|VmSize|VmSwap|RssAnon|RssFile"
# VmSize:   890000 kB   ← VSZ
# VmRSS:     45000 kB   ← RSS
# RssAnon:   30000 kB   ← 익명 메모리 (Heap, 스택 등)
# RssFile:   15000 kB   ← 파일 매핑 (공유 라이브러리, page cache)
# VmSwap:        0 kB   ← swap된 메모리 (0이 정상!)
 
# 메모리 영역별 상세 맵
pmap -x [PID] | tail -1
# total kB   890000   45000   30000
#            VSZ      RSS     Dirty
 
# cgroup 메모리 사용량 (컨테이너 환경)
cat /sys/fs/cgroup/memory.current
cat /sys/fs/cgroup/memory.max
cat /sys/fs/cgroup/memory.stat | head -5

// memory-layers.js
// 실행: node --expose-gc memory-layers.js
 
function printAll(label) {
  global.gc && global.gc();
  const mem = process.memoryUsage();
  const unaccounted = mem.rss - mem.heapTotal - mem.external;
  console.log(`\n[${label}]`);
  console.log(`  RSS:         ${(mem.rss / 1024 / 1024).toFixed(1)}MB`);
  console.log(`  Heap Used:   ${(mem.heapUsed / 1024 / 1024).toFixed(1)}MB`);
  console.log(`  Heap Total:  ${(mem.heapTotal / 1024 / 1024).toFixed(1)}MB`);
  console.log(`  External:    ${(mem.external / 1024 / 1024).toFixed(1)}MB`);
  console.log(`  Unaccounted: ${(unaccounted / 1024 / 1024).toFixed(1)}MB`);
  //                            ↑ libuv, 스택, 코드, page cache 등
}
 
printAll('초기 상태');
 
// 1. JS 객체 → heapUsed 증가
const jsObjects = [];
for (let i = 0; i < 100_000; i++) {
  jsObjects.push({ i, data: 'x'.repeat(100) });
}
printAll('JS 객체 10만 개');
 
// 2. Buffer → external 증가, heapUsed 거의 불변
const buffers = [];
for (let i = 0; i < 50; i++) {
  buffers.push(Buffer.alloc(1024 * 1024)); // 50MB
}
printAll('Buffer 50MB');
 
// 3. TCP 서버 → libuv 핸들 할당 (unaccounted 증가)
const net = require('net');
const server = net.createServer((socket) => {
  // 커넥션마다 uv_tcp_t 핸들이 libuv에서 할당됨
  socket.on('data', () => {});
});
server.listen(0, () => {
  // 자기 자신에게 커넥션 100개 생성
  const connections = [];
  for (let i = 0; i < 100; i++) {
    const client = net.connect(server.address().port);
    connections.push(client);
  }
  setTimeout(() => {
    printAll('TCP 커넥션 100개');
    // → unaccounted가 약간 증가한 것을 관찰할 수 있다
    //   (각 커넥션의 uv_tcp_t + 소켓 버퍼)
 
    // 정리
    connections.forEach(c => c.destroy());
    server.close();
  }, 1000);
});

JS → V8 → Node.js → libuv → OS
 
각 계층에서 메모리가 할당되고, 각각 다른 방식으로 추적/관리된다:
 
JS 객체     → V8 Heap      → heapUsed       → V8 GC가 관리
Buffer      → off-heap     → external       → GC + C++ destructor
libuv       → C malloc     → (보이지 않음)   → libuv 내부 관리
OS          → 가상 메모리    → RSS/VSZ        → 커널이 관리
cgroup      → 물리 메모리    → memory.current → OOM Killer