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?
answer
- one line per collection
- the number after the arrow
- a floor that keeps rising
- time between collections versus time in them
basics
~20 sEach --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[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 failurego deeper
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.
Explain Scavenge for the young generation versus full collections of the old space, and why survivors are promoted between them.
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.
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.