In Node.js, what do the rss, heapUsed, heapTotal and external fields of process.memoryUsage() measure, and why can RSS grow while the heap stays flat?
answer
- one number for the whole process
- the V8 heap is only part of it
- Buffers live off the heap
- arrayBuffers is counted inside external
- glibc malloc fragmentation
basics
~20 sheapUsed and heapTotal describe V8's JavaScript heap, external counts memory outside it such as Buffer and ArrayBuffer storage, and rss is the whole process's resident memory. RSS can climb with a flat heap when Buffers, native code or allocator fragmentation grow.
solid answer
~40 s`process.memoryUsage()` returns bytes. `heapTotal` is what V8 has allocated for its heap and `heapUsed` is what live JavaScript objects occupy inside it. `external` is memory of C++ objects bound to JavaScript objects, and `arrayBuffers`, which is included in `external`, is the storage behind `ArrayBuffer`s, `SharedArrayBuffer`s and every `Buffer`. `rss` is resident memory for the entire process: the heap, off-heap allocations, compiled code, thread stacks and native libraries. So a service that holds on to Buffers grows `external`, `arrayBuffers` and `rss` while `heapUsed` stays flat, and on glibc systems `rss` can also creep from `malloc` fragmentation while the heap stays stable. RSS is the closest of these to what a memory limit outside the process enforces, so watch all three, not just the heap.
code
javascript · 14 linesimport { memoryUsage } from 'node:process';
import { Buffer } from 'node:buffer';
const mib = (n) => `${Math.round(n / 1024 / 1024)} MiB`;
function show(label) {
const m = memoryUsage();
console.log(label, 'rss', mib(m.rss), 'heapUsed', mib(m.heapUsed),
'external', mib(m.external), 'arrayBuffers', mib(m.arrayBuffers));
}
show('before');
const kept = [];
for (let i = 0; i < 200; i++) kept.push(Buffer.alloc(1024 * 1024, 1));
show('after ');go deeper
Recall the five fields of process.memoryUsage() and that rss covers the whole process while heapUsed covers only live JavaScript objects.
Explain what lives outside the V8 heap, why Buffers show up in external and arrayBuffers rather than heapUsed, and why rss lags a falling heap.
Read a growth pattern: which field rises tells you whether to take heap snapshots, look for retained Buffers, or suspect native memory and allocator fragmentation.
Decide what a fleet exports and alerts on: rss against the memory limit, heapUsed against heap_size_limit, and external, so off-heap growth is never invisible.
## The fields and what each one counts `process.memoryUsage()` returns an object of byte counts describing the current Node.js process. The fields measure different things, and confusing them is the most common way to misread a memory graph. | Field | What it measures | Scope | |---|---|---| | `heapTotal` | Memory V8 has allocated for its JavaScript heap, used or not | Calling thread | | `heapUsed` | Memory occupied by live JavaScript objects in that heap | Calling thread | | `external` | Memory of C++ objects bound to JavaScript objects managed by V8 | Calling thread | | `arrayBuffers` | Storage for `ArrayBuffer`s and `SharedArrayBuffer`s, including all `Buffer`s; also counted in `external` | Calling thread | | `rss` | Resident set size: physical memory occupied by the process, including all C++ and JavaScript objects and code | Whole process | **RSS** (resident set size) is the operating system's view: pages of this process currently held in RAM. Everything else is V8's or Node's own accounting of a part of that. ## What lives outside the V8 heap The JavaScript heap holds objects, strings, arrays and closures. A great deal of a Node process's memory is not there: - **Buffer and ArrayBuffer contents.** A `Buffer` is a small JavaScript object pointing at a backing store allocated outside the heap. A 10 MiB `Buffer` barely moves `heapUsed`; it moves `external` and `arrayBuffers` at once, and `rss` as its pages are written. - **Native allocations** made by Node's C++ layer, by bundled libraries such as the TLS and compression code, and by native addons. - **Compiled code and V8's own metadata**, which count in `rss`. - **Thread stacks** for the main thread, libuv's threadpool and any worker threads. - **Allocator overhead.** The Node documentation notes that on Linux and other systems where glibc is common, an application can show sustained `rss` growth with stable `heapTotal` because of fragmentation in the glibc `malloc` implementation. None of this is bounded by `--max-old-space-size`, which limits V8's old space. That is why a process can stay well inside its heap limit and still exceed a memory ceiling imposed from outside. ## Reading a growth pattern Sample the fields over hours, not once, and look at which one moves: 1. **`heapUsed` has a rising floor**, that is, its low point after collections keeps climbing. Something in JavaScript is retaining objects: a cache without eviction, listeners, timers, closures. Heap snapshots will show it. 2. **`external` and `arrayBuffers` rise with `rss`, `heapUsed` flat.** Buffers are being retained: a queue of chunks nobody drains, request bodies kept in a map, a stream whose consumer stopped. The small `Buffer` objects that point at that storage are still in the heap, so a heap snapshot can still find what holds them. 3. **`rss` rises alone** while heap and external are stable. Suspect native memory: an addon, or allocator fragmentation. Heap snapshots will not explain it. 4. **`heapTotal` stays high after `heapUsed` drops.** V8 can keep pages it allocated rather than hand them back to the OS at once, so `rss` lags behind a falling heap. That alone is not a leak. ## Worker threads change the scope Each `worker_threads.Worker` runs its own V8 isolate with its own heap. Called inside a worker, `heapTotal`, `heapUsed`, `external` and `arrayBuffers` describe **that thread only**, while `rss` is valid for the **entire process**. Summing the main thread's heap figures is not the process's footprint; `rss` is. ## Measuring cheaply in production - `process.memoryUsage()` iterates over each page to gather its figures, which can be slow for a large process. For a frequent metric, `process.memoryUsage.rss()` returns the same `rss` value faster. - `v8.getHeapStatistics()` adds `heap_size_limit` (the ceiling V8 will enforce), `used_heap_size`, `external_memory`, and `number_of_detached_contexts`, which the docs describe as a potential leak when it stays non-zero. - `process.constrainedMemory()` reports the memory limit the OS imposes on the process, from cgroups on Linux, and `0` when there is none or it is unknown; `process.availableMemory()` reports how much of it is still free. - A single `heapUsed` reading is noise: it rises between collections and drops after each one, so compare its low points, or values read just after a collection, across hours rather than minutes. Export `rss`, `heapUsed` and `external` side by side. A dashboard that shows only `heapUsed` will look healthy right up to the moment the process is killed for memory it never displayed.
- In a process running worker threads, which process.memoryUsage() fields describe only the calling thread?`heapTotal`, `heapUsed`, `external` and `arrayBuffers` refer to the current thread, because each worker has its own V8 isolate and heap. `rss` is valid for the entire process. To see a worker's heap you read it inside that worker, and to judge the process against a memory ceiling you read `rss`.
- Why might a metrics loop call process.memoryUsage.rss() instead of process.memoryUsage()?`process.memoryUsage()` iterates over each page to gather its figures, which can be slow when the process is large. `process.memoryUsage.rss()` returns the same `rss` value faster. A common split is `rss` on every scrape and the full object, or `v8.getHeapStatistics()`, at a lower rate.
- If heapUsed drops after a burst of traffic, why does rss often stay high?Freed objects make room inside pages V8 already holds; `heapTotal` and the pages behind it are not necessarily returned to the operating system at once, and the native allocator also keeps freed memory for reuse. So `rss` lags a falling heap. A high but flat `rss` after a burst is reuse, not a leak; a rising floor over hours is what to chase.
- heapUsed is the number an external memory limit is enforced against.
- Buffers live on the V8 heap, so --max-old-space-size caps them.
- RSS rising with a flat heap proves a JavaScript object leak.
- Inside a worker thread, rss reports only that worker's memory.
- When heapUsed falls, rss falls with it straight away.