skip to content

In Node 24, how do you capture heap snapshots from a production process whose memory climbs for hours, and what does each capture cost the process?

level: seniorimportance: must knowfreq 55%

answer

  1. signal, API call or heap limit
  2. the event loop stops meanwhile
  3. about twice the heap
  4. take two or three, then compare
  5. one isolate per snapshot

basics

~20 s

Start Node with --heapsnapshot-signal or --heapsnapshot-near-heap-limit, or call v8.writeHeapSnapshot() from a protected trigger. Each snapshot blocks the event loop and needs about twice the heap's memory, so take them from an instance out of rotation, then compare two or three.

solid answer

~50 s

Node gives you several triggers. `--heapsnapshot-signal=SIGUSR2` writes a snapshot when the process receives that signal; `v8.writeHeapSnapshot()` does it from code, for example behind an admin-only endpoint, and returns the file name; `--heapsnapshot-near-heap-limit=max_count` writes up to that many snapshots as the heap approaches its limit, which catches the state just before an out-of-memory crash; and an inspector session can take one interactively. The cost is the same for all: generation is synchronous and blocks the event loop for a time that grows with the heap, possibly more than a minute, and it needs memory about twice the heap's size, which can get the process killed. So take snapshots from an instance removed from the load balancer, with memory headroom, then load two or three taken minutes apart into a comparison view and follow the retainers of whatever keeps growing.

code

bash · 10 lines
bash
node --max-old-space-size=700 \
  --heapsnapshot-signal=SIGUSR2 \
  --heapsnapshot-near-heap-limit=2 \
  server.js &
PID=$!

# After taking the instance out of rotation:
kill -USR2 "$PID"   # writes Heap.<date>.<time>.<pid>.0.001.heapsnapshot
sleep 600
kill -USR2 "$PID"   # second snapshot to compare against the first

go deeper

for a junior

Recall that a heap snapshot lists live objects and what retains them, and that v8.writeHeapSnapshot() or --heapsnapshot-signal produce one.

for a middle

Explain the three-snapshot comparison procedure and how retainers lead from a growing object back to the long-lived root that holds it.

for a senior

Show you know the cost in production: a blocked event loop, about double the heap in memory, a sensitive file, and capture from an instance taken out of rotation.

for a principal

Set the standing practice: which flags every service starts with, who may trigger a capture, where files go and how long they are kept.

## What a heap snapshot is A **heap snapshot** is a complete dump of one V8 isolate's JavaScript heap: every object, its size, and the references between objects. Loaded into a heap inspector such as the Memory tab of Chromium's DevTools, it shows what is alive and, through **retainers**, why it is still alive. It is the tool that turns "memory climbs until the process is killed" into "this `Map` in the session module holds 400,000 entries". Restarting the process clears the symptom and destroys the evidence. ## Ways to trigger one in Node 24 | Trigger | How | Good for | |---|---|---| | `--heapsnapshot-signal=signal` | Start with e.g. `--heapsnapshot-signal=SIGUSR2`, then `kill -USR2 <pid>` | On-demand captures with no code change; disabled unless the flag is set | | `v8.writeHeapSnapshot([filename])` | Call from code; returns the file name it wrote | A protected admin endpoint or your own signal handler | | `v8.getHeapSnapshot()` | Returns a `Readable` stream of the JSON | Streaming the snapshot somewhere other than local disk | | `--heapsnapshot-near-heap-limit=max_count` | Start with the flag; Node writes up to `max_count` snapshots as the heap nears its limit | The state just before an out-of-memory crash | | Inspector | `--inspect`, then the Memory tab | Local or staging investigation | A few details matter in production: - Do not use `SIGUSR1` for your own trigger: Node reserves it to start the inspector. - An endpoint that calls `writeHeapSnapshot()` must not be reachable by anyone else, since a snapshot contains the strings held in memory, secrets and personal data included, and each call stalls the process. - `--heapsnapshot-near-heap-limit` is best effort. Generating a snapshot can trigger garbage collection that lowers usage, so several files may appear before the crash, and Node does not guarantee exactly `max_count`. `v8.setHeapSnapshotNearHeapLimit(limit)` turns on the same behaviour from code and is a no-op if the flag is already set. - A snapshot covers **one isolate**. The main thread's snapshot contains nothing from `worker_threads`; capture a worker's with `writeHeapSnapshot()` inside it or with `worker.getHeapSnapshot()` from the parent. ## What each capture costs Every method pays the same three costs: 1. **The event loop stops.** Generation is synchronous; no request, timer or I/O callback runs until it finishes, and the Node guide warns it can take more than a minute on a large heap. Health checks can time out meanwhile. 2. **Memory roughly doubles.** The docs say creating a snapshot requires memory about twice the size of the heap at that moment, which can push the process over a container's memory limit and get it killed mid-capture. This is one more reason to keep V8's heap limit well below the container's. 3. **Disk and handling.** The file is large, growing with the heap, and contains application data, so it needs space, access control and deletion afterwards. So capture from an instance you can afford to lose: take it out of the load balancer first, or run a canary copy that receives the same traffic. ## Finding the leak by comparison One snapshot shows what is big; it does not show what is **growing**. The Node guide's procedure gives a clean difference: 1. Let the process finish start-up and warm its caches. 2. Exercise the suspected path, so its one-time allocations happen. 3. Take the first snapshot. 4. Keep exercising the same path for a while, preferably with nothing else running. 5. Take a second snapshot, and ideally a third. 6. Load the older file first and the newer second, select the newer one and switch the view from **Summary** to **Comparison**. 7. Sort by the positive delta, then follow the retainers of the growing objects back to something long-lived. What you find in Node services is usually one of a few shapes: - A module-level `Map` or object used as a cache with no eviction, alive for the life of the process because the module is. - Listener arrays on `process`, a shared emitter or a pooled socket, each closure holding a request. - `Timeout` objects from a `setInterval` that is never cleared, keeping their callbacks and closures alive. - Closures that capture a large object when they only needed one field. ## Cheaper alternatives When a full snapshot is too expensive, `--heap-prof` samples allocations and writes a heap profile at exit, and `v8.queryObjects(ctor)`, no longer experimental since Node 24.13.1, counts live instances of a class after a full collection, which suits a leak regression test.

  • Why can --heapsnapshot-near-heap-limit fail to leave any snapshot in a container?
    Writing a snapshot takes both V8 heap memory and native memory. Node adjusts the heap to make room, but if the heap limit sits close to the container's memory limit, the extra native memory pushes the process past the container's limit and it is killed before the file is complete. Keep the heap limit well below the container limit so the snapshot has room.
  • The leak is in code that runs inside worker threads; how do you snapshot it?
    A snapshot covers a single isolate, so the main thread's file never includes worker objects. Call `v8.writeHeapSnapshot()` inside the worker, whose file name carries the worker's thread id, or call `worker.getHeapSnapshot()` from the parent, which returns a promise for a readable stream of that worker's snapshot.
  • How can a test catch the leak again without taking heap snapshots?
    `v8.queryObjects(ctor)` counts objects whose prototype chain includes that constructor after a full garbage collection, and returns counts or short summaries rather than references. A test can run the suspect operation many times and assert the count of, say, your `Session` class stays flat. It is no longer experimental since Node 24.13.1.

  • A heap snapshot is cheap enough to take from an in-rotation instance.
  • One snapshot is enough to tell what is leaking.
  • A main-thread snapshot includes objects held by worker threads.
  • Restarting the service nightly counts as finding the leak.
  • --heapsnapshot-near-heap-limit always writes exactly max_count files.

Assumes Node 24: --heapsnapshot-near-heap-limit is no longer experimental since 24.13.1, and v8.setHeapSnapshotNearHeapLimit() was marked stable in 24.0.0.