Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท node:sqlite and Runtime Services

Node.js v8.writeHeapSnapshot() method

Reference for v8.writeHeapSnapshot() and getHeapSnapshot() in Node.js: capture the heap to a .heapsnapshot file, options, costs and how to use it to find leaks.

A heap snapshot is a complete picture of the objects in memory at one moment, including their sizes and which objects keep which others alive. v8.writeHeapSnapshot() writes one to disk as a .heapsnapshot file, a JSON document that Chrome DevTools can open in its Memory tab.

Snapshots are the standard way to answer "what is using all my memory?". Take one when the process is healthy, another after it has grown, and compare them.

NODE
import v8 from 'node:v8';

const file = v8.writeHeapSnapshot();
console.log(file);

Try it

Node.js Writing a snapshot to a file

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 Reading the structure and streaming the snapshot

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.writeHeapSnapshot([filename[, options]]): string
v8.getHeapSnapshot([options]): stream.Readable
Name Description
filename Where to write. If omitted, Node picks a name like Heap.<date>.<pid>.<thread>.<seq>.heapsnapshot in the current directory (or in --diagnostic-dir).
options.exposeInternals If true, include internal Node.js and V8 objects. Default false.
options.exposeNumericValues If true, expose numeric values in artificial fields. Default false.

Returns: writeHeapSnapshot() returns the file name it wrote. getHeapSnapshot() returns a readable stream of the snapshot JSON.

Errors: an error is thrown if the file cannot be created, for example when the directory does not exist or is not writable.

Usage notes

  • It stops the world. Building a snapshot pauses your JavaScript and can take seconds for a big heap. Do it on one instance that you have taken out of rotation, not on every server at once.
  • It needs memory. Plan for roughly twice the heap size of extra memory while the snapshot is built. A process that is already at its limit may crash while trying.
  • Files are large. A snapshot is often as big as the heap itself. Write to a disk with enough room and compress before downloading.
  • Automatic snapshots. node --heapsnapshot-signal=SIGUSR2 app.js writes one when the signal arrives; --heapsnapshot-near-heap-limit=N writes up to N snapshots when the process approaches its heap limit.
  • Workers. A snapshot of a worker thread is available with worker.getHeapSnapshot().
  • Reading a snapshot. Open it in Chrome DevTools (Memory, Load). Use the Comparison view between two snapshots and sort by "Size Delta", then look at the Retainers panel to see what holds an object alive.
  • Security. Snapshots contain your strings: tokens, passwords and user data. Treat the files as secrets.