Node.js Reference ยท node:sqlite and Runtime Services
Node.js v8.getHeapStatistics() method
Reference for v8.getHeapStatistics() in Node.js: what each heap number means, how to read the heap limit, and how it differs from process.memoryUsage().
v8.getHeapStatistics() returns a plain object with numbers describing the V8 heap of the current thread: how much memory V8 has reserved, how much is used, and, most usefully, the hard limit at which the process will crash with an out-of-memory error.
All values are in bytes. The call is cheap enough to use in health checks and periodic logging.
import v8 from 'node:v8'; const stats = v8.getHeapStatistics(); console.log(stats.heap_size_limit);
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.
Syntax
v8.getHeapStatistics(): HeapInfo
The returned object has these properties:
| Name | Description |
|---|---|
total_heap_size |
Memory V8 has currently reserved for the heap. |
total_heap_size_executable |
The part of it that holds compiled code. |
total_physical_size |
Memory actually committed by the operating system. |
total_available_size |
How much more the heap may grow before it reaches the limit. |
used_heap_size |
Bytes occupied by live and not-yet-collected objects. |
heap_size_limit |
The maximum size of the heap. Exceeding it aborts the process. |
malloced_memory |
Memory allocated by V8 outside the heap with malloc. |
peak_malloced_memory |
The highest value malloced_memory has reached. |
does_zap_garbage |
1 if V8 overwrites freed memory (a debugging mode), otherwise 0. |
number_of_native_contexts |
Count of currently active top-level contexts. A number that keeps growing hints at a leak. |
number_of_detached_contexts |
Contexts that are no longer in use but not yet collected. |
total_global_handles_size, used_global_handles_size |
Memory for global handles held by native code. |
external_memory |
Memory of C++ objects tied to JavaScript objects, such as Buffer backing stores. |
Returns: an object with the numeric properties above. Newer Node versions may add more.
Usage notes
- Per thread. Each worker has its own heap, so the numbers describe the thread that calls the function. Worker limits are set with
resourceLimits. - Buffers are mostly outside the heap. Large
BufferandArrayBufferdata is counted underexternal_memory, not inused_heap_size, so a program holding gigabytes of buffers can look healthy here and still run out of memory. Compare withprocess.memoryUsage(), whosersscovers everything. - The limit depends on the machine. Node chooses a default from the available memory and the architecture. Raise it with
--max-old-space-size=MB(see--max-old-space-size); in containers, make sure the container limit is above it. used_heap_sizeincludes garbage that has not been collected yet. For a leak hunt, force a collection with--expose-gcandglobal.gc()before reading, or watch the trend over time.- Alerting rule of thumb: warn when
used_heap_size / heap_size_limitstays above about 0.8 after a collection. - Per-space detail is available from
v8.getHeapSpaceStatistics().