Heap snapshots and flame graphs: finding leaks and hot paths in production Node

Taking the snapshot: get the heap out of the process

A V8 heap snapshot is a complete graph of every reachable object at one instant, with the edges that keep each object alive. You have three ways to capture one, and the right choice depends on whether the process is healthy, hard to reach, or about to die.

From inside the process, v8.writeHeapSnapshot() dumps a .heapsnapshot file synchronously — it stops the world for the duration, which on a multi-GB heap can be seconds, so never call it on a hot path. Wire it to a signal handler so you can trigger it on demand:

const v8 = require("node:v8");
process.on("SIGUSR2", () => {
  const file = `/tmp/heap-${Date.now()}.heapsnapshot`;
  console.log("writing", v8.writeHeapSnapshot(file));
});
// kill -SIGUSR2 <pid>  — captures a snapshot without an attached debugger

For a process you can reach over the inspector, start it with --inspect and open chrome://inspect in Chrome; the Memory tab takes and diffs snapshots interactively. And for the case in the hook — a process that dies before you can catch it — --heapsnapshot-near-heap-limit=2 tells V8 to automatically write up to two snapshots as it approaches the heap limit, so you get the dump from the exact moment of failure instead of guessing.

Before any snapshot, v8.getHeapStatistics() is the cheap first read: used_heap_size, heap_size_limit, and number_of_native_contexts (a steadily rising context count is itself a classic leak signature). Sample it on an interval and you have the monotonic-growth signal that justifies pulling a full snapshot.

const v8 = require("node:v8");
setInterval(() => {
  const s = v8.getHeapStatistics();
  console.log(JSON.stringify({
    used: s.used_heap_size,
    limit: s.heap_size_limit,
    contexts: s.number_of_native_contexts,
    detached: s.number_of_detached_contexts,
  }));
}, 30_000).unref();

Reading the snapshot: shallow vs retained, and the retaining path

A snapshot is useless until you know which two sizes you are looking at. Shallow size is the memory the object itself occupies — for a plain object, just its headers and field slots, often tiny. Retained size is the memory that would be freed if this object were deleted: the object plus everything reachable only through it. A 200-byte Map with a shallow size of 200 bytes can have a retained size of 400MB because it is the sole thing keeping 400MB of entries alive. Retained size is what you sort by to find a leak; shallow size will hide the culprit at the bottom of the list.

The retaining path answers the actual question — why is this still alive? It is the chain of references from a GC root down to the object. If it terminates at a global, a module-level const, a closure, or an active timer, that is your leak’s anchor. The dominator of an object is the node that every retaining path must pass through; deleting a dominator frees its whole subtree, which is why dominator-tree view groups a leak into one collapsible block instead of ten thousand individual entries.

The hard part in practice is separating your objects from V8 internals. A raw snapshot is full of (system), (compiled code), Map (the hidden-class kind, not the JS Map), and (array) nodes that are V8 bookkeeping, not your data. Filter the Summary view by your own constructor names, sort by retained size, and follow the retaining path — the bytes you can act on are almost always rooted in your own closures, caches, or event-emitter listener arrays.

The three-snapshot technique: name the survivors

A single snapshot tells you what is big now; it cannot tell you what is growing. The three-snapshot technique turns “big” into “leaking” by isolating objects that are allocated during work and then never released.

Concretely, in Chrome DevTools’ Memory tab: take snapshot 1 after the process has settled. Drive the suspected workload (replay N identical requests). Take snapshot 2. Drive the same workload again. Take snapshot 3. Now switch the dropdown to Comparison and compare snapshot 3 against snapshot 1 — or use the “Objects allocated between snapshot 1 and snapshot 2” selector. Anything that was allocated during the exercise and is still alive two snapshots later is suspect: a non-leaking workload allocates and releases, so its delta returns to zero. A leak shows a # New count that grows by the same amount each round and a # Deleted of zero. That linear, repeatable growth — not raw size — is the signature you trust.

CPU profiling and flame graphs: where the time goes

A leak is a memory question; a hot endpoint is a CPU question, and the tool is a profiler, not a snapshot. The V8 sampling profiler interrupts the process thousands of times a second and records the call stack each time; the share of samples a function appears in approximates the share of CPU it consumed.

The lowest-friction capture is node --cpu-prof app.js, which writes a .cpuprofile you load straight into the Chrome DevTools Performance tab. The classic, dependency-free path is node --prof app.js, which emits a raw isolate-*.log of V8 ticks; node --prof-process isolate-*.log turns it into a human-readable summary with a “ticks” breakdown and a bottom-up call tree. For a flame graph specifically, 0x app.js or clinic flame -- node app.js renders the stacks as an interactive SVG.

# One-shot CPU profile, no deps — opens in DevTools › Performance
node --cpu-prof --cpu-prof-dir=/tmp/prof server.js

# V8 tick processor: raw log → ranked summary
node --prof server.js
node --prof-process isolate-*.log > processed.txt

# Flame graph
npx 0x -- node server.js

Reading a flame graph is mechanical once you know the axes. Width is time, not call order — a frame’s width is the fraction of samples it was on the stack, so the widest frames are where CPU went. The y-axis is stack depth: a box sits on top of its caller. A function’s self time is its own width minus the widths of its children stacked above it; a wide frame with nothing on top is doing the work itself (a tight loop, a sync JSON.parse, a regex), while a wide frame that is wide only because of a tall stack above it is just a hot caller. Plateaus — wide flat tops — are your optimization targets. The horizontal order means nothing; do not read it left-to-right as a timeline.