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
