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.
import v8 from 'node:v8'; const file = v8.writeHeapSnapshot(); console.log(file);
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.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.jswrites one when the signal arrives;--heapsnapshot-near-heap-limit=Nwrites up toNsnapshots 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.