skip to content

In Node.js, how do you read --trace-gc output to tell a memory leak apart from a heap that is merely under heavy garbage collection pressure?

level: seniorimportance: should knowfreq 35%

answer

  1. one line per collection
  2. the number after the arrow
  3. a floor that keeps rising
  4. time between collections versus time in them

basics

~20 s

Each --trace-gc line shows heap used before and after one collection. A leak shows as full collections whose after-value rises every time and frees little; pressure shows as frequent collections that keep returning to the same level while taking a large share of time.

solid answer

~40 s

`node --trace-gc` prints one line per collection: the process id, the isolate, milliseconds since start, the kind (`Scavenge` for the young generation, `Mark-sweep` for a full collection in the Node guides' samples), then heap used and, in parentheses, total heap before and after, the time spent, and the reason. For a **leak**, look at the full collections: the used size after each one keeps climbing and each frees less, until lines near the limit free almost nothing and V8 fails with `JavaScript heap out of memory`. For **GC pressure**, the after-values return to a stable floor, but collections come so often that the time between them approaches the time spent in them. A leak is fixed in code that retains objects; pressure is fixed by allocating less, or by benchmarking `--max-semi-space-size`.

code

plaintext · 2 lines
plaintext
[40977:0x128008000]  2066 ms: Mark-sweep (reduce) 99.6 (102.5) -> 99.6 (102.5) MB, 46.7 / 0.0 ms  (average mu = 0.154, current mu = 0.155) allocation failure
[40977:0x128008000]  2123 ms: Mark-sweep (reduce) 99.6 (102.5) -> 99.6 (102.5) MB, 47.7 / 0.0 ms  (average mu = 0.165, current mu = 0.175) allocation failure

go deeper

for a junior

Recall that --trace-gc prints one line per collection, and that the figures before and after the arrow are heap used before and after it.

for a middle

Explain Scavenge for the young generation versus full collections of the old space, and why survivors are promoted between them.

for a senior

Read a trace into a verdict: a rising after-GC floor means a leak to chase with snapshots, a stable floor with collections back to back means allocation pressure.

for a principal

Weigh the levers: code changes that allocate less, a benchmarked semi-space size, or a smaller packed heap, against the memory each costs per instance.

## Turning traces on `--trace-gc` is a V8 flag that makes Node print one line to the console for every garbage collection. The Node guide notes that `--trace_gc` with an underscore works too. ```bash node --trace-gc server.js ``` It is **not** on the list of V8 options allowed in `NODE_OPTIONS`, so put it on the command line. To trace only a window of a running process's life, `v8.setFlagsFromString('--trace-gc')` turns it on from code and `'--notrace-gc'` turns it off; the docs warn that changing V8 flags after start-up can behave unpredictably, so treat that as a diagnostic tool, not a permanent setting. For metrics rather than log lines, a `PerformanceObserver` from `node:perf_hooks` observing the `'gc'` entry type receives one entry per collection, with its duration. ## Anatomy of a line The Node guide's example line: ```plaintext [13973:0x110008000] 44 ms: Scavenge 2.4 (3.2) -> 2.0 (4.2) MB, 0.5 / 0.0 ms (average mu = 1.000, current mu = 1.000) allocation failure ``` | Token | Meaning | |---|---| | `13973` | Process id | | `0x110008000` | The isolate, that is, which JavaScript heap | | `44 ms` | Time since the process started | | `Scavenge` | Kind of collection | | `2.4 (3.2)` | Heap used (total heap) before, in MB | | `-> 2.0 (4.2)` | Heap used (total heap) after, in MB | | `0.5 / 0.0 ms` and the `mu` figures | Time spent in this collection | | `allocation failure` | Why it ran: here, the space was full | Two kinds dominate: - **`Scavenge`** collects the **young generation**, where new objects are allocated. It is frequent and short. Objects that survive two scavenges are promoted to the old space. - **`Mark-sweep`** (as printed in the Node guides' samples) collects the **old space**, where long-lived objects live. It is rarer and costs more. The exact labels vary between V8 versions; the before-and-after numbers are what you read. ## The leak signature A leak is memory that stays reachable, so no collector can free it. In the trace that looks like: 1. **Full collections whose after-value keeps rising.** Plot the number after the arrow on each `Mark-sweep` line; a leak gives a floor that climbs and never comes back. 2. **Each full collection frees less**, and full collections become more frequent as the old space fills. 3. **Near the limit**, lines such as `Mark-sweep (reduce) 99.6 (102.5) -> 99.6 (102.5) MB` free nothing, reasons like `allocation failure scavenge might not succeed` appear, and V8 ends the process with `FATAL ERROR: Ineffective mark-compacts near heap limit Allocation failed - JavaScript heap out of memory` or `Reached heap limit`. The Node guide adds a confirmation trick: lower `--max-old-space-size` so the heap reaches its limit sooner, run until it fails, then raise the limit by about ten percent and repeat. If the same pattern recurs at every size, it is a leak; if the process settles at some size, the heap simply needed that much and you can keep the limit there. ## The pressure signature Under pressure nothing is retained wrongly; the process just allocates fast: - The after-values **return to a stable level**, collection after collection. - **Scavenges are very frequent**, because short-lived objects fill the young generation quickly. - The ratio of time **between** collections to time **in** them shrinks. The guide's rule of thumb: if the time between two collections is less than the time spent in them, the application is severely starving; if it is much greater, the application is relatively healthy. Remedies differ from a leak's: - Allocate less on hot paths: avoid building large intermediate arrays and strings per request. - Benchmark `--max-semi-space-size`. A larger semi-space means fewer scavenges at the cost of more memory; because the young generation is three semi-spaces, each extra MiB of semi-space adds 3 MiB to the heap. - If time between collections and time in them are both very long, the guide suggests the application could probably use a smaller heap. ## From trace to cause A trace tells you **whether** memory is leaking and how badly; it does not tell you **what** is retained. Once the rising floor confirms a leak, heap snapshots taken minutes apart and compared show which objects grow and what keeps them alive. Traces are cheap enough to leave on during a reproduction; snapshots are expensive and come second.

  • Why does NODE_OPTIONS=--trace-gc not work when the same flag works on the node command line?
    `NODE_OPTIONS` accepts only an allowlist of options, and the V8 options on that list include `--max-old-space-size` and `--max-semi-space-size` but not `--trace-gc`. Node exits with an error when `NODE_OPTIONS` carries an option that is not allowed. Put the flag on the command line, or switch it on from code with `v8.setFlagsFromString('--trace-gc')`.
  • How do you export garbage collection time as a metric instead of parsing log lines?
    Create a `PerformanceObserver` from `node:perf_hooks` and observe `entryTypes: ['gc']`. Each collection arrives as a `PerformanceEntry` whose `duration` is the time it took, so you can sum or histogram it per minute. A rising share of wall time spent in GC is the pressure signal, without stdout noise.

  • Frequent Scavenge lines on their own prove a memory leak.
  • The number after the arrow is the memory each collection freed.
  • 'allocation failure' in a trace line means the process is out of memory.
  • --trace-gc output shows which objects are leaking.
  • Raising --max-old-space-size fixes a heap whose floor keeps rising.