2nd/10_Wiki/Topic_Programming/Coding/Perf_Node_Profiling.md

id, title, category, status, source_trust_level, verification_status, created_at, updated_at, tags, tech_stack, applied_in, aliases

id	title	category	status	source_trust_level	verification_status	created_at	updated_at	tags	tech_stack	applied_in	aliases
perf-node-profiling	Node Profiling — CPU / Memory / Async hooks	Coding	draft	B	conceptual	2026-05-09	2026-05-09	performance node profiling vibe-coding	language applicable_to Node / TS Backend		clinic 0x flamegraph heapdump async hooks --inspect

Node Profiling

"느림" 감으로 X — profile. CPU = clinic flame / 0x, Memory = heapdump, Event loop = clinic doctor. Production = --inspect + Chrome DevTools.

📖 핵심 개념

• CPU profile: 어느 함수가 시간 소모.
• Heap snapshot: 메모리 누가 보유.
• Event loop lag: 비동기 정체.
• Async hooks: async chain 추적.

💻 코드 패턴

Clinic.js (가장 단순)

yarn add -D clinic

clinic doctor -- node app.js
# 실행 → 부하 (autocannon) → Ctrl+C
# HTML report: doctor 가 진단 (CPU bound? I/O? memory?)

clinic flame -- node app.js
# Flame graph — 시간 hot spot

clinic bubbleprof -- node app.js
# Async operation 시각화

clinic heapprofiler -- node app.js
# Memory allocation

0x (flame graph)

npx 0x app.js
# 또는
0x -- node app.js

--inspect (Chrome DevTools)

node --inspect app.js
# 또는 prod (조심)
node --inspect=0.0.0.0:9229 app.js

# Chrome → chrome://inspect → DevTools
# CPU profile, heap snapshot, allocation timeline

→ Production attach 가능 (보안 주의).

CPU profile (programmatic)

import { Session } from 'node:inspector';

const session = new Session();
session.connect();

session.post('Profiler.enable', () => {
  session.post('Profiler.start', () => {
    setTimeout(() => {
      session.post('Profiler.stop', (err, { profile }) => {
        require('fs').writeFileSync('profile.cpuprofile', JSON.stringify(profile));
        // Chrome DevTools → Performance → load profile
      });
    }, 30_000);
  });
});

Heap snapshot

import { writeHeapSnapshot } from 'node:v8';

// Trigger: signal 또는 API
process.on('SIGUSR2', () => {
  const path = `heap-${Date.now()}.heapsnapshot`;
  writeHeapSnapshot(path);
  console.log('snapshot:', path);
});

// 분석: Chrome DevTools → Memory → Load snapshot

kill -USR2 $PID

→ "Comparison" view 로 두 snapshot 비교 → leak.

Memory leak 패턴

// ❌ Global Map 만 쌓임
const cache = new Map();
app.get('/x', (req, res) => {
  cache.set(req.id, req.data); // 영원 — leak
});

// ✅ TTL / LRU
import LRU from 'lru-cache';
const cache = new LRU({ max: 1000, ttl: 60_000 });

Event loop lag

import { monitorEventLoopDelay } from 'node:perf_hooks';

const h = monitorEventLoopDelay({ resolution: 20 });
h.enable();

setInterval(() => {
  console.log('p99 lag:', h.percentile(99) / 1e6, 'ms');
  h.reset();
}, 5000);

→ 50ms+ = problem. CPU bound 또는 sync I/O 의심.

Async hooks (실험적, 비싸)

import { createHook, executionAsyncId } from 'node:async_hooks';

const stack = new Map();
const hook = createHook({
  init: (asyncId, type, triggerAsyncId) => {
    stack.set(asyncId, { type, parent: triggerAsyncId });
  },
  destroy: (asyncId) => stack.delete(asyncId),
});
hook.enable();

→ AsyncLocalStorage 의 internal. Trace 추적.

AsyncLocalStorage (context)

import { AsyncLocalStorage } from 'node:async_hooks';

const als = new AsyncLocalStorage<{ requestId: string; userId?: string }>();

app.use((req, res, next) => {
  als.run({ requestId: uuid() }, next);
});

// 어디서나
log.info({ ...als.getStore(), msg: 'event' });

Production tracing (low overhead)

// OpenTelemetry auto-instrumentation (위 OTel 문서 참조)
// Sentry profiling
import * as Sentry from '@sentry/node';
import { ProfilingIntegration } from '@sentry/profiling-node';

Sentry.init({ dsn, profilesSampleRate: 0.1, integrations: [new ProfilingIntegration()] });

→ Continuous profiling — 항상 켜져있음.

perf_hooks 측정

import { performance } from 'node:perf_hooks';

const t = performance.now();
await heavyWork();
console.log('took', performance.now() - t, 'ms');

// PerformanceObserver
import { PerformanceObserver, performance } from 'node:perf_hooks';
const obs = new PerformanceObserver((items) => {
  for (const e of items.getEntries()) console.log(e.name, e.duration);
});
obs.observe({ type: 'measure' });

performance.mark('start');
await ...;
performance.mark('end');
performance.measure('myWork', 'start', 'end');

V8 flags (debugging)

node --max-old-space-size=4096 app.js     # heap 4GB
node --trace-gc app.js                     # GC log
node --prof app.js                         # CPU profile (raw)
node --prof-process isolate-*.log          # process

Memory limit

# Default V8 = ~1.5 GB on 64-bit
NODE_OPTIONS="--max-old-space-size=4096" node app.js

Hot path 측정 (JIT)

// 반복 측정 — JIT warmup
for (let i = 0; i < 10000; i++) myHotFn(); // warm
const t = performance.now();
for (let i = 0; i < 100000; i++) myHotFn();
console.log((performance.now() - t) / 100000, 'us per call');

🤔 의사결정 기준

증상	도구
CPU 100%	Flame graph (0x / clinic)
Memory 자라남	Heap snapshot diff
응답 느려짐 점진	Event loop lag
가끔 spike	Continuous profile (Sentry)
Async tracing	OTel + auto-instrumentation
Production attach	--inspect=0.0.0.0:9229 (보안)

❌ 안티패턴

• console.time 만 + 추측: 정확 X. profiler.
• Production --inspect 공개: 누구나 attach. SSH tunnel.
• Async hook prod 항상: 큰 overhead. 디버깅 시만.
• Heap snapshot prod 큰 process: GC pause + freeze.
• JIT warmup 무시: 첫 call 측정.
• Memory limit 안 설정 prod: 무한 자라남.
• Sample rate 100% prod: 비용. 1-10%.

🤖 LLM 활용 힌트

• Clinic doctor 가 진단 시작.
• Heap snapshot diff 가 leak.
• Event loop lag 가 핵심 SLI.
• Production = Sentry / OTel sampled.

🔗 관련 문서

• Native_Memory_Profiling
• DevOps_Observability_Stack
• Backpressure_Patterns