Skip to content
Tutorials Center
My learning

Topics

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.

NODE
import v8 from 'node:v8';

const stats = v8.getHeapStatistics();
console.log(stats.heap_size_limit);

Try it

Node.js Reading the heap numbers

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.

Node.js Allocating and watching usage

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

NODE
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 Buffer and ArrayBuffer data is counted under external_memory, not in used_heap_size, so a program holding gigabytes of buffers can look healthy here and still run out of memory. Compare with process.memoryUsage(), whose rss covers 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_size includes garbage that has not been collected yet. For a leak hunt, force a collection with --expose-gc and global.gc() before reading, or watch the trend over time.
  • Alerting rule of thumb: warn when used_heap_size / heap_size_limit stays above about 0.8 after a collection.
  • Per-space detail is available from v8.getHeapSpaceStatistics().