On this page

Node.js Performance

Node.js performance problems almost always reduce to one of three things: the event loop is blocked, the garbage collector is working too hard, or data is moving through the process faster than it can be drained. The runtime is fast — V8 produces machine code that competes with Java and Go on hot paths — but its single-threaded execution model means one slow function, one unbounded buffer, or one leaked closure degrades every request in flight, not just the one that caused it.

This page is the practitioner's overview: what to measure, which knobs matter, and how to profile a real service. Each section links to a deep-dive page in Performance Optimization when you need the internals.

The Performance Model

flowchart LR
    REQ["Incoming requests"] --> EL["Event loop<br/>(single JS thread)"]
    EL --> JS["Your JS<br/>(V8 JIT code)"]
    JS --> HEAP["V8 heap<br/>(new + old space)"]
    JS --> IO["libuv I/O<br/>(epoll / kqueue / IOCP)"]
    JS --> TP["libuv thread pool<br/>(fs, dns.lookup, crypto, zlib)"]
    JS --> WT["Worker threads<br/>(your CPU-bound work)"]
    HEAP --> GC["Garbage collector<br/>(Scavenge + Mark-Compact)"]
    GC -. "pauses" .-> EL
    TP -. "callbacks" .-> EL
    IO -. "callbacks" .-> EL

Everything that runs JavaScript competes for the same thread. GC pauses, synchronous JSON parsing, regex backtracking and long loops all show up as the same symptom: event loop lag, which turns into latency for every concurrent request.

SymptomUsual root causeFirst tool
p99 latency high, CPU at 100% of one coreCPU-bound JS on main thread--cpu-prof, 0x flame graph
p99 latency spikes, CPU moderateGC pauses or sync I/O--trace-gc, perf_hooks GC observer
RSS climbs until OOMKillLeak (heap or native)Heap snapshots, process.memoryUsage()
Throughput plateaus, CPU lowThread pool saturation or downstream waitsUV_THREADPOOL_SIZE, async hooks / traces
Memory balloons under load, recovers afterMissing backpressureStream audit, writableLength metrics

V8 Heap and Garbage Collection

Heap Layout in Brief

V8 splits the managed heap into generations based on the observation that most objects die young:

SpaceWhat lives thereCollected byTypical size
New space (two semi-spaces)Freshly allocated objectsScavenge (copying, parallel)16-64 MiB (per --max-semi-space-size × 3)
Old spaceObjects that survived two scavengesMark-Sweep-Compact (incremental, concurrent)Bounded by --max-old-space-size
Large object spaceObjects > ~500KB (never moved)Mark-SweepCounts toward old-space limit
Code spaceJIT-compiled machine codeMark-SweepSmall

The full layout, the Scavenge and Mark-Compact algorithms, write barriers and WeakRef/FinalizationRegistry are covered in Memory Management.

What Actually Costs You

  • Scavenges are cheap individually (sub-millisecond to a few ms) but frequent. High allocation rates of short-lived objects multiply them.
  • Promotion is where costs compound: objects that survive just long enough to be promoted (request-scoped caches, buffered response bodies held across await) end up in old space and must be collected by the far more expensive major GC.
  • Major GC is mostly concurrent, but its final atomic pause scales with the live heap. A 3GB old space can produce pauses in the tens to hundreds of milliseconds.

Sizing the Heap

V8's default old-space limit depends on the Node version and on detected system memory (newer versions read the cgroup limit). Do not rely on the default in containers — set it:

# ~75% of the container memory limit; the rest covers new space,
# Buffers/ArrayBuffers (outside the V8 heap), code and native addons
node --max-old-space-size=1536 server.js          # 2GiB container

# Larger young generation: fewer scavenges and less premature promotion
# for allocation-heavy services (costs memory: new space = 3 × semi-space)
node --max-old-space-size=1536 --max-semi-space-size=32 server.js
# Kubernetes: derive from the limit, set via NODE_OPTIONS
env:
  - name: NODE_OPTIONS
    value: "--max-old-space-size=1536 --max-semi-space-size=32"
resources:
  requests: { cpu: "1", memory: 2Gi }
  limits:   { memory: 2Gi }

How the container memory limit, cgroup working set and OOMKill interact is covered in Kubernetes Resource Management.

WARNING

Raising --max-old-space-size does not fix a leak — it only delays the crash and makes each major GC slower. If the heap grows without bound, find the retainer first. A heap limit should be sized for the legitimate working set plus headroom.

Reading process.memoryUsage()

const mb = (n: number) => Math.round(n / 1024 / 1024);

export function memorySnapshot() {
  const m = process.memoryUsage();
  return {
    rssMb: mb(m.rss),               // total resident memory — what the cgroup sees
    heapTotalMb: mb(m.heapTotal),   // V8 heap reserved
    heapUsedMb: mb(m.heapUsed),     // V8 heap live + not-yet-collected
    externalMb: mb(m.external),     // C++ objects bound to JS (incl. Buffers)
    arrayBuffersMb: mb(m.arrayBuffers), // ArrayBuffer + Buffer backing stores
  };
}
PatternInterpretation
heapUsed steadily climbing across GCsJS object leak — take heap snapshots
heapUsed flat, arrayBuffers/external climbingBuffer leak (held Buffers, unconsumed streams, native addon)
heapUsed and external flat, rss climbingNative leak or allocator fragmentation
heapUsed sawtooth with stable baselineHealthy

Observing GC in Production

import { PerformanceObserver, constants } from "node:perf_hooks";
import { Histogram } from "prom-client";

const gcDuration = new Histogram({
  name: "nodejs_gc_pause_seconds",
  help: "GC pause duration by kind",
  labelNames: ["kind"],
  buckets: [0.001, 0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1],
});

const kinds: Record<number, string> = {
  [constants.NODE_PERFORMANCE_GC_MINOR]: "minor",
  [constants.NODE_PERFORMANCE_GC_MAJOR]: "major",
  [constants.NODE_PERFORMANCE_GC_INCREMENTAL]: "incremental",
  [constants.NODE_PERFORMANCE_GC_WEAKCB]: "weakcb",
};

new PerformanceObserver((list) => {
  for (const entry of list.getEntries()) {
    const kind = kinds[(entry.detail as { kind: number }).kind] ?? "unknown";
    gcDuration.observe({ kind }, entry.duration / 1000);
  }
}).observe({ entryTypes: ["gc"] });

For ad-hoc investigation, node --trace-gc server.js prints one line per collection with heap sizes before and after and the pause time.

The Event Loop

Phases

flowchart TD
    T["timers<br/>setTimeout / setInterval"] --> P["pending callbacks<br/>deferred system errors"]
    P --> I["idle, prepare<br/>(internal)"]
    I --> PO["poll<br/>wait for and run I/O callbacks"]
    PO --> C["check<br/>setImmediate"]
    C --> CL["close callbacks<br/>socket.on('close')"]
    CL --> T
    MQ["process.nextTick queue,<br/>then Promise microtasks<br/>(drained after every callback)"]:::micro
    classDef micro fill:#fff3cd,stroke:#d4a017

The two facts that matter for performance:

  1. Microtasks run to completion between callbacks. A promise chain that keeps scheduling more promises (or a recursive process.nextTick) starves I/O completely.
  2. The poll phase is where the loop waits for I/O. If a callback takes 200ms, nothing else — not a timer, not an incoming socket — is processed for 200ms.

The phase-by-phase walkthrough, setImmediate vs setTimeout(0) ordering, and libuv internals are in Node.js Event Loop Deep Dive.

Measuring Event Loop Lag

Use the built-in histogram — it samples with a native timer and costs almost nothing:

import { monitorEventLoopDelay, performance } from "node:perf_hooks";
import { Gauge } from "prom-client";

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

const lagP99 = new Gauge({ name: "nodejs_eventloop_lag_p99_seconds", help: "Event loop delay p99" });
const lagMax = new Gauge({ name: "nodejs_eventloop_lag_max_seconds", help: "Event loop delay max" });
const elu = new Gauge({ name: "nodejs_eventloop_utilization", help: "Fraction of time the loop was busy" });

let lastElu = performance.eventLoopUtilization();

setInterval(() => {
  lagP99.set(h.percentile(99) / 1e9);
  lagMax.set(h.max / 1e9);
  h.reset();

  const current = performance.eventLoopUtilization();
  elu.set(performance.eventLoopUtilization(current, lastElu).utilization);
  lastElu = current;
}, 10_000).unref();
MetricHealthyInvestigateAction
Lag p99< 20ms50-100ms> 100ms: something is blocking
Lag max< 100ms100-500ms> 1s: health checks will start failing
Event loop utilization (ELU)< 0.70.7-0.9> 0.9: saturated; scale out or offload

ELU is a better scaling signal than CPU percentage for Node: a process at 100% CPU with ELU of 0.4 is spending time in GC or thread-pool work, not saturating the JS thread.

TIP

Use ELU or event loop lag as the readiness/load-shedding signal. Returning 503 when lag p99 exceeds a threshold prevents a slow process from accepting more work than it can complete — far better than letting every queued request time out.

The libuv Thread Pool

fs.*, dns.lookup, crypto.pbkdf2/scrypt/randomBytes (async), and zlib run on a shared pool that defaults to 4 threads. Four concurrent bcrypt hashes or slow NFS reads saturate it, and every other fs call queues behind them.

# Must be set before the pool is first used — set it in the environment
UV_THREADPOOL_SIZE=16 node server.js

Note that dns.lookup (used by http.request by default) goes through the pool, while dns.resolve* uses c-ares and does not. A DNS-heavy outbound client can starve file I/O.

Blocking Work and Worker Threads

Finding What Blocks

Common main-thread blockers in real services:

BlockerTypical costFix
JSON.parse / JSON.stringify on multi-MB payloads10-100ms+Stream-parse, paginate, or offload to a worker
Catastrophic regex backtrackingUnboundedRewrite regex, use RE2 (re2 package), bound input length
Sync crypto (crypto.pbkdf2Sync, bcrypt sync APIs)50-300msAsync API (thread pool) or worker
fs.readFileSync in request pathDisk latencyAsync fs, or load at startup
Sorting / aggregating large arraysO(n log n) on main threadPush to DB, chunk with setImmediate, or worker
Template rendering of huge pages10-50msCache, stream rendering
zlib.*SyncProportional to sizeAsync zlib (thread pool)

Node can tell you about synchronous I/O after startup:

node --trace-sync-io server.js
# (node:41233) WARNING: Detected use of sync API
#     at readFileSync (node:fs:453:20)
#     at loadTemplate (/app/src/render.js:12:18)

Offloading with a Worker Pool

Spawning a worker per task costs tens of milliseconds and ~10MB+ of memory. Keep a pool. piscina is the de-facto standard:

// pool.ts
import Piscina from "piscina";
import { availableParallelism } from "node:os";

export const pool = new Piscina({
  filename: new URL("./workers/report.js", import.meta.url).href,
  minThreads: 2,
  maxThreads: Math.max(2, availableParallelism() - 1),
  idleTimeout: 30_000,
  maxQueue: 1_000, // reject instead of queueing unboundedly
});

// route handler
app.post("/reports", async (req, reply) => {
  try {
    const result = await pool.run(
      { rows: req.body.rows },
      { signal: AbortSignal.timeout(5_000) }
    );
    return reply.send(result);
  } catch (err) {
    if ((err as Error).name === "AbortError") return reply.code(504).send();
    throw err;
  }
});
// workers/report.ts — runs in a separate V8 isolate
export default function buildReport({ rows }: { rows: Array<Record<string, number>> }) {
  const totals = new Map<string, number>();
  for (const row of rows) {
    for (const [k, v] of Object.entries(row)) totals.set(k, (totals.get(k) ?? 0) + v);
  }
  return Object.fromEntries(totals);
}

Workers are not free: arguments are structured-cloned (copied) unless you transfer ArrayBuffers or use SharedArrayBuffer. For a task that takes 2ms, the cloning overhead can exceed the work. Offload when the task is CPU-heavy (≳10ms) relative to its input size.

SharedArrayBuffer, Atomics, transfer lists, and worker vs child_process vs cluster trade-offs are covered in Worker Threads and Parallelism.

Yielding Without Workers

For moderately sized loops, chunking the work and yielding back to the loop keeps latency bounded without the clone cost:

import { setImmediate as yieldToLoop } from "node:timers/promises";

export async function processInChunks<T>(items: T[], fn: (item: T) => void, chunk = 1_000) {
  for (let i = 0; i < items.length; i += chunk) {
    const end = Math.min(i + chunk, items.length);
    for (let j = i; j < end; j++) fn(items[j]);
    await yieldToLoop(); // let I/O callbacks and other requests run
  }
}

This increases the total time for this task but caps the lag it causes for everyone else.

V8 Optimization: Writing JIT-Friendly Code

V8 compiles hot functions with TurboFan (and Maglev, a mid-tier compiler) based on the types it has observed. Code stays fast as long as those observations remain true.

Hidden Classes and Inline Caches

Objects with the same properties added in the same order share a hidden class (map). Property access sites cache the map they saw:

Inline cache stateMaps seen at the siteRelative speed
Monomorphic1Fastest — single map check + offset load
Polymorphic2-4Slower — linear map checks
Megamorphic> 4Much slower — global stub cache lookup
// Fragile: shape depends on which branch ran
function makeUserBad(row: any) {
  const u: any = { id: row.id };
  if (row.email) u.email = row.email;    // some objects have email, some don't
  if (row.admin) u.isAdmin = true;       // four possible shapes
  return u;
}

// Stable: one shape for every user
function makeUser(row: { id: string; email?: string; admin?: boolean }) {
  return {
    id: row.id,
    email: row.email ?? null,
    isAdmin: row.admin === true,
  };
}

Common Deoptimization Triggers

PatternWhy it hurts
Adding/deleting properties after construction (delete obj.x)Changes the hidden class; object may drop to dictionary mode
Mixing types in one variable or array ([1, "2", 3.5, {}])Array elements kind degrades to generic
Holey arrays (new Array(1000) then sparse writes)Holey element kinds require prototype checks
Functions called with many different object shapesMegamorphic call/property sites
arguments leaking, eval, withInhibit optimization
Integer overflow past Smi range in hot mathRepresentation change to heap numbers
# See what V8 optimizes and why it bails out
node --trace-opt --trace-deopt bench.js 2>&1 | grep -E "deoptimiz|bailout" | head -20

Do not chase deopts blindly. Measure first; a deopt in a function that runs ten times is irrelevant. The pipeline (Ignition → Sparkplug → Maglev → TurboFan), elements kinds, and how to read deopt traces are in V8 Engine Optimization.

Streams and Backpressure

Streams let a Node process handle data far larger than its heap. Backpressure is the mechanism that stops a fast producer from overwhelming a slow consumer. Ignoring it is one of the most common causes of "memory explodes under load".

sequenceDiagram
    participant R as Readable (S3 download)
    participant T as Transform (gzip)
    participant W as Writable (HTTP response to slow client)
    R->>T: chunk
    T->>W: write(chunk)
    W-->>T: returns false (buffer > highWaterMark)
    Note over T,R: pipeline() pauses upstream
    W->>W: drains to socket
    W-->>T: 'drain' event
    T->>R: resume
    R->>T: next chunk

The Bug

// BAD: ignores write()'s return value — buffers the whole file in memory
// when the client is slower than the source
readable.on("data", (chunk) => {
  res.write(chunk);
});
readable.on("end", () => res.end());

The Fix: pipeline()

import { pipeline } from "node:stream/promises";
import { createGzip } from "node:zlib";
import { Transform } from "node:stream";

app.get("/export.csv.gz", async (req, res) => {
  const rows = db.queryStream("SELECT * FROM orders WHERE created_at > $1", [req.query.since]);

  const toCsv = new Transform({
    objectMode: true,
    transform(row, _enc, cb) {
      cb(null, `${row.id},${row.total},${row.created_at.toISOString()}\n`);
    },
  });

  res.setHeader("Content-Type", "text/csv");
  res.setHeader("Content-Encoding", "gzip");

  try {
    // Backpressure, error propagation and cleanup handled for every stage
    await pipeline(rows, toCsv, createGzip(), res);
  } catch (err) {
    req.log.warn({ err }, "export aborted");
    // pipeline has already destroyed every stream, including the DB cursor
  }
});

pipeline() propagates backpressure, destroys all streams on error (closing DB cursors and file descriptors), and rejects once. Manual .pipe() does not forward errors and leaks the source when the destination fails.

Writing Manually with Backpressure

When you control the producer loop, respect write() and wait for drain:

import { once } from "node:events";
import type { Writable } from "node:stream";

export async function writeAll(dest: Writable, chunks: AsyncIterable<Buffer>) {
  for await (const chunk of chunks) {
    if (!dest.write(chunk)) {
      await once(dest, "drain");
    }
  }
  dest.end();
}
KnobDefaultEffect
highWaterMark (byte streams)64 KiB (Node 22+), 16 KiB earlierBuffer size before write() returns false
highWaterMark (object mode)16 objectsSame, counted in objects
writable.writableLength—Bytes currently buffered; export as a metric to detect slow consumers

Profiling

Always profile under realistic load. A profile of an idle server shows startup code; a profile under a synthetic benchmark that hits one endpoint shows only that endpoint. See Load Testing for generating representative traffic, and Node.js Profiling for a tool-by-tool deep dive.

Choosing a Tool

QuestionToolOverhead
Where is CPU time going?node --cpu-prof, 0x, clinic flameLow-moderate
Is it CPU, I/O, GC, or event loop?clinic doctorLow
Where are async operations waiting?clinic bubbleprofModerate-high
What is allocating memory?node --heap-prof, clinic heapprofilerLow (sampling)
What is retaining memory?Heap snapshots (Chrome DevTools)High — pauses the process
Continuous, fleet-widePyroscope / Parca / Datadog continuous profilerVery low — see Continuous Profiling

CPU Profiles

# Writes CPU.<date>.<pid>.cpuprofile on exit; open in Chrome DevTools
# (Performance tab → Load profile) or speedscope.app
node --cpu-prof --cpu-prof-dir=/tmp/prof server.js

# Flame graph with 0x (wraps node, generates an interactive HTML flame graph)
npx 0x -o -- node server.js
# ... run load, then Ctrl+C

# Triage: clinic doctor detects the bottleneck category and suggests the next tool
npx clinic doctor --autocannon [ -c 100 -d 30 /api/orders ] -- node server.js

Reading the flame graph: width is time on CPU. Look for wide plateaus at the top of stacks (hot leaf functions) and for unexpected frames — JSON.parse, RegExp, Builtins_*, (garbage collector) — that should not be prominent.

Heap Profiles and Snapshots

# Sampling allocation profile (cheap, safe-ish in staging)
node --heap-prof --heap-prof-dir=/tmp/prof server.js

# Write a heap snapshot when receiving a signal
node --heapsnapshot-signal=SIGUSR2 server.js
kill -USR2 <pid>

# Automatically snapshot as the heap approaches its limit
node --heapsnapshot-near-heap-limit=2 --max-old-space-size=1536 server.js
// Programmatic snapshot from an authenticated admin endpoint
import { writeHeapSnapshot } from "node:v8";

adminRouter.post("/debug/heap-snapshot", (_req, res) => {
  const file = writeHeapSnapshot(`/tmp/heap-${process.pid}-${Date.now()}.heapsnapshot`);
  res.json({ file });
});

WARNING

Writing a heap snapshot blocks the event loop for seconds (proportional to heap size) and needs roughly as much additional memory as the heap itself. In a container near its limit, taking a snapshot can trigger the very OOMKill you are investigating. Pull the instance out of the load balancer first, and make sure the memory limit has room.

The three-snapshot technique isolates leaks reliably: take snapshot 1 after warm-up, run load, take snapshot 2, run the same load again, take snapshot 3. In DevTools, view snapshot 3 in "Objects allocated between snapshot 1 and 2" mode — anything still alive from that window that grew again is your leak. Follow the Retainers panel up to the GC root to find who is holding it.

Common Leak Patterns

PatternExampleFix
Unbounded in-process cacheconst cache = new Map() keyed by user/request IDLRU with max size and TTL (lru-cache)
Event listeners never removedemitter.on("x", handler) per requestonce(), remove in finally, or AbortSignal with addEventListener
Closures capturing large scopeTimer callback referencing a whole request objectCapture only the fields you need
Timers/intervals never clearedsetInterval per connectionClear on close; .unref() background timers
Promises that never settleAwaiting a reply that never comes; holds the whole async chainTimeouts via AbortSignal.timeout()
Global arrays used as queuespending.push(job) with no consumer under loadBounded queue, reject when full
AsyncLocalStorage stores holding large objectsRequest context retains buffers past the responseStore IDs, not payloads
Unconsumed HTTP response bodiesfetch() result ignored without reading the bodyAlways consume or body.cancel()
Native/Buffer leaksBuffers sliced from a huge parent buffer (buf.subarray retains parent)Buffer.from(slice) to copy small pieces
// Bounded cache instead of a bare Map
import { LRUCache } from "lru-cache";

export const sessionCache = new LRUCache<string, Session>({
  max: 50_000,
  ttl: 10 * 60 * 1000,
  updateAgeOnGet: true,
});
// Listener tied to the request lifetime via AbortSignal
app.get("/events", (req, res) => {
  const ac = new AbortController();
  req.on("close", () => ac.abort());

  bus.addEventListener(
    "order-updated",
    (e) => res.write(`data: ${JSON.stringify((e as CustomEvent).detail)}\n\n`),
    { signal: ac.signal } // removed automatically when the client disconnects
  );
});

War Story (illustrative)

A Node API was restarting every few hours with heap exhaustion. Snapshots showed hundreds of thousands of ClientRequest objects retained by a Map. The service kept a map of in-flight outbound calls for metrics, deleting entries in the response handler — but calls that timed out at the socket level emitted error instead of response, so their entries lived forever. Under normal traffic the leak was slow; during a downstream partial outage, timeouts spiked and the process died in minutes. The fix was deleting the entry in a finally around the awaited request, and adding a size gauge for the map.

For the full incident workflow — confirming a leak, isolating it across languages, and remediating in production — use the Memory Leak playbook.

Process Model and Scaling

A single Node process uses one core for JavaScript. Use more cores by running more processes:

ApproachWhen
One process per container, scale with replicasKubernetes/ECS — simplest, best isolation, preferred
cluster module / PM2 cluster modeVMs or bare metal without an orchestrator
Worker threadsCPU-heavy tasks inside one service, shared memory needed

In Kubernetes, prefer a 1-CPU request per Node replica and scale horizontally; a 4-CPU pod running one Node process wastes three cores unless you run workers or the thread pool is busy.

Production Tuning Checklist

Runtime Flags and Environment

SettingRecommendation
Node versionCurrent LTS; each major brings V8 and GC improvements
NODE_ENV=productionMany frameworks skip dev checks and enable caching
--max-old-space-size~75% of container memory limit
--max-semi-space-size16-64 for allocation-heavy services; measure scavenge frequency
UV_THREADPOOL_SIZERaise (8-16) if you use heavy fs/crypto/zlib/dns.lookup
--heapsnapshot-near-heap-limitEnable in staging; in prod only with memory headroom
--enable-source-mapsUseful for TS stack traces; has a cost on error-heavy paths

Code and Architecture

  • No *Sync APIs in request paths (--trace-sync-io in staging is clean)
  • Large JSON payloads are paginated or streamed, not parsed whole
  • All stream chains use pipeline()
  • Every outbound call has a timeout (AbortSignal.timeout)
  • HTTP clients reuse connections (keep-alive agent / undici pool)
  • Every in-process cache has a max size and TTL
  • CPU-heavy work (> ~10ms) goes to a worker pool with a bounded queue
  • Hot objects are constructed with a consistent shape
  • Logging is async and structured (pino), not console.log with string building
  • Concurrency to downstreams is bounded (e.g. p-limit), not Promise.all over unbounded arrays

Observability

  • Event loop lag p99/max and ELU exported
  • GC pause histogram by kind exported
  • heapUsed, external, arrayBuffers, rss exported separately
  • Alerts on lag p99 > 100ms for 5 minutes, and on heap used / heap limit > 85%
  • Continuous profiler on at least one replica per service
  • Load-shedding or readiness tied to event loop health
// Minimal load shedding on event loop lag
import { monitorEventLoopDelay } from "node:perf_hooks";

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

const MAX_LAG_MS = 200;

app.addHook("onRequest", async (req, reply) => {
  const p99Ms = lag.percentile(99) / 1e6;
  if (p99Ms > MAX_LAG_MS && req.url !== "/healthz") {
    reply.header("Retry-After", "1").code(503).send({ error: "overloaded" });
  }
});

setInterval(() => lag.reset(), 5_000).unref();

Cross-References