2nd/10_Wiki/Topics/Backend/Nodejs Memory Tuning.md

id, title, category, status, canonical_id, aliases, duplicate_of, source_trust_level, confidence_score, verification_status, tags, raw_sources, last_reinforced, github_commit, tech_stack

id	title	category	status	canonical_id	aliases	duplicate_of	source_trust_level	confidence_score	verification_status	tags	raw_sources	last_reinforced	github_commit	tech_stack
wiki-2026-0508-nodejs-memory-tuning	Node.js Memory Tuning	10_Wiki/Topics	verified	self	V8 Heap Tuning Node Heap Limit max-old-space-size	none	A	0.9	applied	nodejs v8 performance memory gc		2026-05-10	pending	language framework JavaScript Node.js 22 LTS

Node.js Memory Tuning

매 한 줄

"매 V8 heap 의 explicit budget + GC trace 의 observe". Node.js 의 default heap 매 ~4 GB (64-bit) 의 OS-derived — 매 process 의 actual workload 의 맞춰 매 --max-old-space-size, --max-semi-space-size 의 tune. 2026 Node 22 LTS 의 V8 12.4 — 매 Maglev tier, pointer compression default 의 활용.

매 핵심

매 V8 heap layout

• Young generation (semi-space): 매 short-lived — 매 Scavenge GC, 매 fast.
• Old generation: 매 promoted — 매 Mark-Compact.
• Code/Map/Large object space: 매 separate.
• Pointer compression: 매 4-byte tagged pointer (4 GB heap 의 limit) — 매 default since Node 14.

매 GC modes

• Scavenge (minor): 매 ms order, 매 frequent.
• Mark-Sweep-Compact (major): 매 100s of ms, 매 STW phase.
• Concurrent marking: 매 background — STW 의 reduce.
• Incremental marking: 매 chunk-by-chunk.

매 응용

1. 큰 JSON parsing — heap 의 raise + streaming parser 의 use.
2. Long-running server — leak detection (heap snapshot diff).
3. Worker thread — per-thread heap budget.
4. Container env (k8s) — request/limit 와 V8 의 align.

💻 패턴

CLI flags (Node 22)

NODE_OPTIONS="--max-old-space-size=8192 \
              --max-semi-space-size=128 \
              --expose-gc \
              --trace-gc \
              --trace-gc-verbose" \
  node server.js

Container-aware (k8s)

env:
  - name: NODE_OPTIONS
    # 매 limit 의 ~80% 의 leave headroom for native + libuv
    value: "--max-old-space-size=3200"
resources:
  limits:
    memory: "4Gi"

Programmatic — heap stats

import v8 from 'node:v8';
import { performance } from 'node:perf_hooks';

setInterval(() => {
  const s = v8.getHeapStatistics();
  console.log({
    used_mb: (s.used_heap_size / 1e6).toFixed(1),
    total_mb: (s.total_heap_size / 1e6).toFixed(1),
    limit_mb: (s.heap_size_limit / 1e6).toFixed(1),
    external_mb: (s.external_memory / 1e6).toFixed(1),
  });
}, 5000);

Heap snapshot on threshold

import v8 from 'node:v8';
import fs from 'node:fs';

function snapshotIfHigh(thresholdRatio = 0.85) {
  const s = v8.getHeapStatistics();
  if (s.used_heap_size / s.heap_size_limit > thresholdRatio) {
    const path = `heap-${Date.now()}.heapsnapshot`;
    v8.writeHeapSnapshot(path);
    console.error('Heap snapshot:', path);
  }
}
setInterval(snapshotIfHigh, 60_000);

GC observer (perf_hooks)

import { PerformanceObserver, constants } from 'node:perf_hooks';

new PerformanceObserver((list) => {
  for (const e of list.getEntries()) {
    const kind = e.detail?.kind;
    if (e.duration > 50) {
      console.warn('Long GC', { kind, ms: e.duration.toFixed(1) });
    }
  }
}).observe({ entryTypes: ['gc'], buffered: false });

Streaming JSON (avoid heap blowup)

import { parser } from 'stream-json';
import { streamArray } from 'stream-json/streamers/StreamArray.js';
import fs from 'node:fs';

fs.createReadStream('big.json')
  .pipe(parser())
  .pipe(streamArray())
  .on('data', ({ value }) => process(value));

Buffer pool tuning

// 매 large Buffer.allocUnsafe 의 pool — > 8KB 매 bypass
import { Buffer } from 'node:buffer';
Buffer.poolSize = 64 * 1024;   // default 8 KB

--heap-prof for sampling

node --heap-prof --heap-prof-interval=524288 server.js
# → Chrome DevTools 의 .heapprofile 의 load

매 결정 기준

상황	Approach
Container limit 4 GB	--max-old-space-size=3200 (~80%)
OOM at startup	Streaming parse + lazy load
Long GC pauses	Reduce old-gen pressure (pool, reuse) + bigger semi-space
Memory leak suspect	Heap snapshot diff (3 snapshots, 30s apart)
Worker threads	Per-worker heap budget — sum < container limit
> 4 GB heap	--no-pointer-compression 의 disable (slower, more RAM)

기본값: --max-old-space-size = 0.8 × container_limit, GC trace in prod 의 sample.

🔗 Graph

• 부모: V8
• Adjacent: Pointer Compression

🤖 LLM 활용

언제: flag lookup, OOM diagnosis playbook, snapshot 의 interpret. 언제 X: 매 specific leak — heap snapshot 의 actual data 의 require.

❌ 안티패턴

• Default heap 의 trust in container: 매 OOMKilled — explicit --max-old-space-size.
• global.gc() polling: 매 mask 의 leak — root cause 의 fix.
• Heap limit = container limit: 매 native + libuv overhead 무시 — 80% 의 leave.
• Synchronous huge JSON.parse: 매 STW — streaming parser 의 use.
• Heap snapshot in hot path: 매 STW seconds — threshold trigger 의 만.

🧪 검증 / 중복

• Verified (nodejs.org docs v22; v8.dev blog; Node Diagnostics Working Group).
• 신뢰도 A.

🕓 Changelog

날짜	변경
2026-05-08	Phase 1
2026-05-10	Manual cleanup — V8 heap tuning + GC trace + snapshot 정리