liveBook · Manning

heapUsed

As explained in JavaScript in Depth

The portion of a JavaScript engine's managed heap currently occupied by live or otherwise retained objects.

A rising memory graph does not automatically mean JavaScript objects are leaking. heapUsed measures the managed-heap space currently occupied by live JavaScript objects—the portion the garbage collector can reclaim. It rises during allocation and falls when unreachable objects are collected; heapTotal is reserved heap capacity, not current usage. section 11.1.1

Reading a memory mystery

Sample process.memoryUsage() under load and plot heapUsed. Normal allocation produces a sawtooth: usage climbs, garbage collection lowers it, and successive troughs remain roughly level. A leak produces the same shape with progressively higher troughs because objects survive collection cycles and accumulate in the old generation. If heapUsed rises while external remains stable, investigate retained JavaScript objects; if external rises while heapUsed stays stable, investigate Buffers or ArrayBuffers instead. section 11.2.1 section 11.1.1

setInterval(() => {
  const mem = process.memoryUsage();
  console.log(
    `rss: ${(mem.rss / 1024 / 1024).toFixed(1)} MB  ` +
    `heapUsed: ${(mem.heapUsed / 1024 / 1024).toFixed(1)} MB  ` +
    `external: ${(mem.external / 1024 / 1024).toFixed(1)} MB`
  );
}, 5000);

A periodic process.memoryUsage() sample makes heapUsed trends visible alongside rss and external memory. section 11.1.1

Interpret heapUsed with the surrounding memory metrics:

  • Compare heapUsed with heapTotal: approaching the available heap threshold can cause the engine to request more heap; failure to expand can trigger an out-of-memory error. section 11.1.1
  • Do not treat heapUsed as process memory: rss also includes the runtime binary, native addons, thread stacks, and other resident allocations. section 11.1.1
  • Use --trace-gc to distinguish a leak from allocation pressure; increasing Scavenge frequency, Mark-Compact events, or declining mu indicate collection pressure rather than necessarily retained objects. section 11.2.1 section 11.6

How JavaScript in Depth covers it

How deep it goes
Explains allocation, collection, heap expansion, sawtooth graphs, and metric-based diagnosis, then defers retention causes to heap snapshots and retainer chains.
Examples
Uses process.memoryUsage() output, periodic sampling, healthy sawtooth graphs, rising leak troughs, and Buffer or ArrayBuffer comparisons.
What it assumes
Assumes JavaScript objects and garbage collection, while defining managed heap, retained objects, external memory, and process-level memory distinctions.
What you can do after
Diagnose memory growth with process.memoryUsage(), heapUsed trends, metric comparisons, and --trace-gc before taking heap snapshots.
How it connects
Connects heapUsed with garbage collection, heapTotal, rss, external memory, memory leaks, heap snapshots, and retainer chains.

Related concepts

This explainer was generated by Manning's knowledge graph from the text of JavaScript in Depth. The section links point to the parts of the book it draws on.