Measuring the heap

Shallow size vs retained size — the distinction that matters

This lesson is the engine-level companion to performance/04-gc/06-gc-production (which covers the ops side — alerting, limits, restarts). Here: how to read the heap directly.

A heap snapshot is a full dump of the object graph at one instant — every object, its size, and its references. Two size numbers per object, and confusing them wastes hours:

• Shallow size — the memory the object itself occupies (its own fields), excluding what it references. An array’s shallow size is tiny even if it holds millions of huge objects.
• Retained size — the memory that would be freed if this object were deleted, i.e. the object plus everything reachable only through it. This is the number that tells you the cost of a leak: a small object with a huge retained size is anchoring a big subtree.

You hunt leaks by retained size, not shallow size. The leaked Map has a trivial shallow size but a retained size of every entry it alone keeps alive.

The dominator tree

To compute retained size, V8 builds the dominator tree of the object graph. Object A dominates object B if every path from a root to B passes through A — meaning if A is freed, B necessarily becomes unreachable too. An object’s retained size is the total shallow size of everything it dominates.

The dominator tree is the leak-hunter’s map: walk down from the roots and find the object whose retained size is large and unexpected. Its dominated subtree is exactly what it is keeping alive — and the path from a root to it is the retainer path you must cut.

The three-snapshot technique

A single snapshot shows what is in the heap, but not what is growing. The classic leak-finding method is three snapshots:

1. Snapshot 1 — establish a baseline after warm-up.
2. Exercise the suspected operation N times (navigate, run the request, etc.).
3. Snapshot 2.
4. Exercise it N more times.
5. Snapshot 3.

DevTools’ “Objects allocated between snapshots” comparison shows objects born after snapshot 1 that are still alive at snapshot 3. In a healthy operation those should be near zero (everything transient got collected); a leak shows a count growing linearly with N. Sort the survivors by retained size, open one, and read its retainer path to the root. That sequence — diff, sort by retained, read retainer — is the whole workflow.

Allocation timeline and sampling

Snapshots are point-in-time; the allocation timeline (DevTools) and allocation sampling answer “where is the churn coming from?” by attributing allocations to the call stacks that made them, over time. Sampling is low-overhead enough for production-ish use. This is how you find a hot allocation site driving GC pressure (the lesson-02 minor-GC problem), distinct from a retention leak.

Node and programmatic counters

You don’t always have DevTools attached. Numbers you can log:

• process.memoryUsage() → { rss, heapTotal, heapUsed, external, arrayBuffers }. heapUsed = live V8 heap objects; heapTotal = committed V8 heap; rss = total resident process memory (includes native, stacks, code); external / arrayBuffers = memory held by C++ objects bound to JS (Buffers, ArrayBuffers). Climbing heapUsed ⇒ JS retention leak; climbing external/arrayBuffers with flat heapUsed ⇒ a Buffer/native leak; high rss with flat heapUsed ⇒ fragmentation.
• v8.getHeapStatistics() / getHeapSpaceStatistics() — per-space sizes (new vs old vs large-object), used_heap_size, heap_size_limit. Lets you watch old space specifically.
• --trace-gc / --trace-gc-verbose — log every GC event with heap-before/heap-after and pause time. Plot old-space-after over time: monotonic growth = leak; oscillation around a mean = the GC keeping up.
• --max-old-space-size=<MB> — the old-space cap; raising it buys headroom but does not fix a leak (it only delays the OOM and lengthens major-GC pauses). The default is roughly 2 GB on modern 64-bit Node but version-dependent — measure, don’t assume.
• v8.writeHeapSnapshot() — dump a .heapsnapshot from inside the process (e.g. on a signal) to load into DevTools offline. Invaluable in production where you cannot attach a debugger.

In the browser, performance.measureUserAgentSpecificMemory() gives a cross-origin-isolated, breakdown-by-type estimate of the page’s memory — the supported successor to the old non-standard performance.memory.