docs(10_Wiki): Topic_Business/General/Graphic/Programming을 Topics/ 하위로 이동

최상위 10_Wiki/Topic_*였던 4개 카테고리 폴더를 10_Wiki/Topics/Topic_* 로 재배치. 콘텐츠 변경 없음(순수 폴더 이동) — Topics/ 하위 나머지 폴더는 이미 지난 커밋에서 전부 정리된 상태(잔존 항목은 에이전트 운영 상태 및 사용자가 보존을 요청한 업데이트0615/무제 3.canvas 뿐).
2026-07-05 00:44:01 +09:00
parent e9cbf23ab5
commit 9a135bd19d
6127 changed files with 0 additions and 0 deletions
@@ -0,0 +1,175 @@
+---
+id: wiki-2026-0508-nodejs-memory-tuning
+title: Node.js Memory Tuning
+category: 10_Wiki/Topics
+status: verified
+canonical_id: self
+aliases: [V8 Heap Tuning, Node Heap Limit, max-old-space-size]
+duplicate_of: none
+source_trust_level: A
+confidence_score: 0.9
+verification_status: applied
+tags: [nodejs, v8, performance, memory, gc]
+raw_sources: []
+last_reinforced: 2026-05-10
+github_commit: pending
+tech_stack:
+  language: JavaScript
+  framework: 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)
+```bash
+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)
+```yaml
+env:
+  - name: NODE_OPTIONS
+    # 매 limit 의 ~80% 의 leave headroom for native + libuv
+    value: "--max-old-space-size=3200"
+resources:
+  limits:
+    memory: "4Gi"
+```
+
+### Programmatic — heap stats
+```js
+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
+```js
+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)
+```js
+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)
+```js
+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
+```js
+// 매 large Buffer.allocUnsafe 의 pool — > 8KB 매 bypass
+import { Buffer } from 'node:buffer';
+Buffer.poolSize = 64 * 1024;   // default 8 KB
+```
+
+### `--heap-prof` for sampling
+```bash
+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 정리 |