Node.js Performance
Node.js performance problems almost always reduce to one of three things: the event loop is blocked, the garbage collector is working too hard, or data is moving through the process faster than it can be drained. The runtime is fast — V8 produces machine code that competes with Java and Go on hot paths — but its single-threaded execution model means one slow function, one unbounded buffer, or one leaked closure degrades every request in flight, not just the one that caused it.
This page is the practitioner's overview: what to measure, which knobs matter, and how to profile a real service. Each section links to a deep-dive page in Performance Optimization when you need the internals.
The Performance Model
flowchart LR
REQ["Incoming requests"] --> EL["Event loop<br/>(single JS thread)"]
EL --> JS["Your JS<br/>(V8 JIT code)"]
JS --> HEAP["V8 heap<br/>(new + old space)"]
JS --> IO["libuv I/O<br/>(epoll / kqueue / IOCP)"]
JS --> TP["libuv thread pool<br/>(fs, dns.lookup, crypto, zlib)"]
JS --> WT["Worker threads<br/>(your CPU-bound work)"]
HEAP --> GC["Garbage collector<br/>(Scavenge + Mark-Compact)"]
GC -. "pauses" .-> EL
TP -. "callbacks" .-> EL
IO -. "callbacks" .-> EL
Everything that runs JavaScript competes for the same thread. GC pauses, synchronous JSON parsing, regex backtracking and long loops all show up as the same symptom: event loop lag, which turns into latency for every concurrent request.
| Symptom | Usual root cause | First tool |
|---|---|---|
| p99 latency high, CPU at 100% of one core | CPU-bound JS on main thread | --cpu-prof, 0x flame graph |
| p99 latency spikes, CPU moderate | GC pauses or sync I/O | --trace-gc, perf_hooks GC observer |
| RSS climbs until OOMKill | Leak (heap or native) | Heap snapshots, process.memoryUsage() |
| Throughput plateaus, CPU low | Thread pool saturation or downstream waits | UV_THREADPOOL_SIZE, async hooks / traces |
| Memory balloons under load, recovers after | Missing backpressure | Stream audit, writableLength metrics |
V8 Heap and Garbage Collection
Heap Layout in Brief
V8 splits the managed heap into generations based on the observation that most objects die young:
| Space | What lives there | Collected by | Typical size |
|---|---|---|---|
| New space (two semi-spaces) | Freshly allocated objects | Scavenge (copying, parallel) | 16-64 MiB (per --max-semi-space-size × 3) |
| Old space | Objects that survived two scavenges | Mark-Sweep-Compact (incremental, concurrent) | Bounded by --max-old-space-size |
| Large object space | Objects > ~500KB (never moved) | Mark-Sweep | Counts toward old-space limit |
| Code space | JIT-compiled machine code | Mark-Sweep | Small |
The full layout, the Scavenge and Mark-Compact algorithms, write barriers and WeakRef/FinalizationRegistry are covered in Memory Management.
What Actually Costs You
- Scavenges are cheap individually (sub-millisecond to a few ms) but frequent. High allocation rates of short-lived objects multiply them.
- Promotion is where costs compound: objects that survive just long enough to be promoted (request-scoped caches, buffered response bodies held across
await) end up in old space and must be collected by the far more expensive major GC. - Major GC is mostly concurrent, but its final atomic pause scales with the live heap. A 3GB old space can produce pauses in the tens to hundreds of milliseconds.
Sizing the Heap
V8's default old-space limit depends on the Node version and on detected system memory (newer versions read the cgroup limit). Do not rely on the default in containers — set it:
# ~75% of the container memory limit; the rest covers new space,
# Buffers/ArrayBuffers (outside the V8 heap), code and native addons
node --max-old-space-size=1536 server.js # 2GiB container
# Larger young generation: fewer scavenges and less premature promotion
# for allocation-heavy services (costs memory: new space = 3 × semi-space)
node --max-old-space-size=1536 --max-semi-space-size=32 server.js
# Kubernetes: derive from the limit, set via NODE_OPTIONS
env:
- name: NODE_OPTIONS
value: "--max-old-space-size=1536 --max-semi-space-size=32"
resources:
requests: { cpu: "1", memory: 2Gi }
limits: { memory: 2Gi }
How the container memory limit, cgroup working set and OOMKill interact is covered in Kubernetes Resource Management.
WARNING
Raising --max-old-space-size does not fix a leak — it only delays the crash and makes each major GC slower. If the heap grows without bound, find the retainer first. A heap limit should be sized for the legitimate working set plus headroom.
Reading process.memoryUsage()
const mb = (n: number) => Math.round(n / 1024 / 1024);
export function memorySnapshot() {
const m = process.memoryUsage();
return {
rssMb: mb(m.rss), // total resident memory — what the cgroup sees
heapTotalMb: mb(m.heapTotal), // V8 heap reserved
heapUsedMb: mb(m.heapUsed), // V8 heap live + not-yet-collected
externalMb: mb(m.external), // C++ objects bound to JS (incl. Buffers)
arrayBuffersMb: mb(m.arrayBuffers), // ArrayBuffer + Buffer backing stores
};
}
| Pattern | Interpretation |
|---|---|
heapUsed steadily climbing across GCs | JS object leak — take heap snapshots |
heapUsed flat, arrayBuffers/external climbing | Buffer leak (held Buffers, unconsumed streams, native addon) |
heapUsed and external flat, rss climbing | Native leak or allocator fragmentation |
heapUsed sawtooth with stable baseline | Healthy |
Observing GC in Production
import { PerformanceObserver, constants } from "node:perf_hooks";
import { Histogram } from "prom-client";
const gcDuration = new Histogram({
name: "nodejs_gc_pause_seconds",
help: "GC pause duration by kind",
labelNames: ["kind"],
buckets: [0.001, 0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1],
});
const kinds: Record<number, string> = {
[constants.NODE_PERFORMANCE_GC_MINOR]: "minor",
[constants.NODE_PERFORMANCE_GC_MAJOR]: "major",
[constants.NODE_PERFORMANCE_GC_INCREMENTAL]: "incremental",
[constants.NODE_PERFORMANCE_GC_WEAKCB]: "weakcb",
};
new PerformanceObserver((list) => {
for (const entry of list.getEntries()) {
const kind = kinds[(entry.detail as { kind: number }).kind] ?? "unknown";
gcDuration.observe({ kind }, entry.duration / 1000);
}
}).observe({ entryTypes: ["gc"] });
For ad-hoc investigation, node --trace-gc server.js prints one line per collection with heap sizes before and after and the pause time.
The Event Loop
Phases
flowchart TD
T["timers<br/>setTimeout / setInterval"] --> P["pending callbacks<br/>deferred system errors"]
P --> I["idle, prepare<br/>(internal)"]
I --> PO["poll<br/>wait for and run I/O callbacks"]
PO --> C["check<br/>setImmediate"]
C --> CL["close callbacks<br/>socket.on('close')"]
CL --> T
MQ["process.nextTick queue,<br/>then Promise microtasks<br/>(drained after every callback)"]:::micro
classDef micro fill:#fff3cd,stroke:#d4a017
The two facts that matter for performance:
- Microtasks run to completion between callbacks. A promise chain that keeps scheduling more promises (or a recursive
process.nextTick) starves I/O completely. - The poll phase is where the loop waits for I/O. If a callback takes 200ms, nothing else — not a timer, not an incoming socket — is processed for 200ms.
The phase-by-phase walkthrough, setImmediate vs setTimeout(0) ordering, and libuv internals are in Node.js Event Loop Deep Dive.
Measuring Event Loop Lag
Use the built-in histogram — it samples with a native timer and costs almost nothing:
import { monitorEventLoopDelay, performance } from "node:perf_hooks";
import { Gauge } from "prom-client";
const h = monitorEventLoopDelay({ resolution: 10 });
h.enable();
const lagP99 = new Gauge({ name: "nodejs_eventloop_lag_p99_seconds", help: "Event loop delay p99" });
const lagMax = new Gauge({ name: "nodejs_eventloop_lag_max_seconds", help: "Event loop delay max" });
const elu = new Gauge({ name: "nodejs_eventloop_utilization", help: "Fraction of time the loop was busy" });
let lastElu = performance.eventLoopUtilization();
setInterval(() => {
lagP99.set(h.percentile(99) / 1e9);
lagMax.set(h.max / 1e9);
h.reset();
const current = performance.eventLoopUtilization();
elu.set(performance.eventLoopUtilization(current, lastElu).utilization);
lastElu = current;
}, 10_000).unref();
| Metric | Healthy | Investigate | Action |
|---|---|---|---|
| Lag p99 | < 20ms | 50-100ms | > 100ms: something is blocking |
| Lag max | < 100ms | 100-500ms | > 1s: health checks will start failing |
| Event loop utilization (ELU) | < 0.7 | 0.7-0.9 | > 0.9: saturated; scale out or offload |
ELU is a better scaling signal than CPU percentage for Node: a process at 100% CPU with ELU of 0.4 is spending time in GC or thread-pool work, not saturating the JS thread.
TIP
Use ELU or event loop lag as the readiness/load-shedding signal. Returning 503 when lag p99 exceeds a threshold prevents a slow process from accepting more work than it can complete — far better than letting every queued request time out.
The libuv Thread Pool
fs.*, dns.lookup, crypto.pbkdf2/scrypt/randomBytes (async), and zlib run on a shared pool that defaults to 4 threads. Four concurrent bcrypt hashes or slow NFS reads saturate it, and every other fs call queues behind them.
# Must be set before the pool is first used — set it in the environment
UV_THREADPOOL_SIZE=16 node server.js
Note that dns.lookup (used by http.request by default) goes through the pool, while dns.resolve* uses c-ares and does not. A DNS-heavy outbound client can starve file I/O.
Blocking Work and Worker Threads
Finding What Blocks
Common main-thread blockers in real services:
| Blocker | Typical cost | Fix |
|---|---|---|
JSON.parse / JSON.stringify on multi-MB payloads | 10-100ms+ | Stream-parse, paginate, or offload to a worker |
| Catastrophic regex backtracking | Unbounded | Rewrite regex, use RE2 (re2 package), bound input length |
Sync crypto (crypto.pbkdf2Sync, bcrypt sync APIs) | 50-300ms | Async API (thread pool) or worker |
fs.readFileSync in request path | Disk latency | Async fs, or load at startup |
| Sorting / aggregating large arrays | O(n log n) on main thread | Push to DB, chunk with setImmediate, or worker |
| Template rendering of huge pages | 10-50ms | Cache, stream rendering |
zlib.*Sync | Proportional to size | Async zlib (thread pool) |
Node can tell you about synchronous I/O after startup:
node --trace-sync-io server.js
# (node:41233) WARNING: Detected use of sync API
# at readFileSync (node:fs:453:20)
# at loadTemplate (/app/src/render.js:12:18)
Offloading with a Worker Pool
Spawning a worker per task costs tens of milliseconds and ~10MB+ of memory. Keep a pool. piscina is the de-facto standard:
// pool.ts
import Piscina from "piscina";
import { availableParallelism } from "node:os";
export const pool = new Piscina({
filename: new URL("./workers/report.js", import.meta.url).href,
minThreads: 2,
maxThreads: Math.max(2, availableParallelism() - 1),
idleTimeout: 30_000,
maxQueue: 1_000, // reject instead of queueing unboundedly
});
// route handler
app.post("/reports", async (req, reply) => {
try {
const result = await pool.run(
{ rows: req.body.rows },
{ signal: AbortSignal.timeout(5_000) }
);
return reply.send(result);
} catch (err) {
if ((err as Error).name === "AbortError") return reply.code(504).send();
throw err;
}
});
// workers/report.ts — runs in a separate V8 isolate
export default function buildReport({ rows }: { rows: Array<Record<string, number>> }) {
const totals = new Map<string, number>();
for (const row of rows) {
for (const [k, v] of Object.entries(row)) totals.set(k, (totals.get(k) ?? 0) + v);
}
return Object.fromEntries(totals);
}
Workers are not free: arguments are structured-cloned (copied) unless you transfer ArrayBuffers or use SharedArrayBuffer. For a task that takes 2ms, the cloning overhead can exceed the work. Offload when the task is CPU-heavy (≳10ms) relative to its input size.
SharedArrayBuffer, Atomics, transfer lists, and worker vs child_process vs cluster trade-offs are covered in Worker Threads and Parallelism.
Yielding Without Workers
For moderately sized loops, chunking the work and yielding back to the loop keeps latency bounded without the clone cost:
import { setImmediate as yieldToLoop } from "node:timers/promises";
export async function processInChunks<T>(items: T[], fn: (item: T) => void, chunk = 1_000) {
for (let i = 0; i < items.length; i += chunk) {
const end = Math.min(i + chunk, items.length);
for (let j = i; j < end; j++) fn(items[j]);
await yieldToLoop(); // let I/O callbacks and other requests run
}
}
This increases the total time for this task but caps the lag it causes for everyone else.
V8 Optimization: Writing JIT-Friendly Code
V8 compiles hot functions with TurboFan (and Maglev, a mid-tier compiler) based on the types it has observed. Code stays fast as long as those observations remain true.
Hidden Classes and Inline Caches
Objects with the same properties added in the same order share a hidden class (map). Property access sites cache the map they saw:
| Inline cache state | Maps seen at the site | Relative speed |
|---|---|---|
| Monomorphic | 1 | Fastest — single map check + offset load |
| Polymorphic | 2-4 | Slower — linear map checks |
| Megamorphic | > 4 | Much slower — global stub cache lookup |
// Fragile: shape depends on which branch ran
function makeUserBad(row: any) {
const u: any = { id: row.id };
if (row.email) u.email = row.email; // some objects have email, some don't
if (row.admin) u.isAdmin = true; // four possible shapes
return u;
}
// Stable: one shape for every user
function makeUser(row: { id: string; email?: string; admin?: boolean }) {
return {
id: row.id,
email: row.email ?? null,
isAdmin: row.admin === true,
};
}
Common Deoptimization Triggers
| Pattern | Why it hurts |
|---|---|
Adding/deleting properties after construction (delete obj.x) | Changes the hidden class; object may drop to dictionary mode |
Mixing types in one variable or array ([1, "2", 3.5, {}]) | Array elements kind degrades to generic |
Holey arrays (new Array(1000) then sparse writes) | Holey element kinds require prototype checks |
| Functions called with many different object shapes | Megamorphic call/property sites |
arguments leaking, eval, with | Inhibit optimization |
| Integer overflow past Smi range in hot math | Representation change to heap numbers |
# See what V8 optimizes and why it bails out
node --trace-opt --trace-deopt bench.js 2>&1 | grep -E "deoptimiz|bailout" | head -20
Do not chase deopts blindly. Measure first; a deopt in a function that runs ten times is irrelevant. The pipeline (Ignition → Sparkplug → Maglev → TurboFan), elements kinds, and how to read deopt traces are in V8 Engine Optimization.
Streams and Backpressure
Streams let a Node process handle data far larger than its heap. Backpressure is the mechanism that stops a fast producer from overwhelming a slow consumer. Ignoring it is one of the most common causes of "memory explodes under load".
sequenceDiagram
participant R as Readable (S3 download)
participant T as Transform (gzip)
participant W as Writable (HTTP response to slow client)
R->>T: chunk
T->>W: write(chunk)
W-->>T: returns false (buffer > highWaterMark)
Note over T,R: pipeline() pauses upstream
W->>W: drains to socket
W-->>T: 'drain' event
T->>R: resume
R->>T: next chunk
The Bug
// BAD: ignores write()'s return value — buffers the whole file in memory
// when the client is slower than the source
readable.on("data", (chunk) => {
res.write(chunk);
});
readable.on("end", () => res.end());
The Fix: pipeline()
import { pipeline } from "node:stream/promises";
import { createGzip } from "node:zlib";
import { Transform } from "node:stream";
app.get("/export.csv.gz", async (req, res) => {
const rows = db.queryStream("SELECT * FROM orders WHERE created_at > $1", [req.query.since]);
const toCsv = new Transform({
objectMode: true,
transform(row, _enc, cb) {
cb(null, `${row.id},${row.total},${row.created_at.toISOString()}\n`);
},
});
res.setHeader("Content-Type", "text/csv");
res.setHeader("Content-Encoding", "gzip");
try {
// Backpressure, error propagation and cleanup handled for every stage
await pipeline(rows, toCsv, createGzip(), res);
} catch (err) {
req.log.warn({ err }, "export aborted");
// pipeline has already destroyed every stream, including the DB cursor
}
});
pipeline() propagates backpressure, destroys all streams on error (closing DB cursors and file descriptors), and rejects once. Manual .pipe() does not forward errors and leaks the source when the destination fails.
Writing Manually with Backpressure
When you control the producer loop, respect write() and wait for drain:
import { once } from "node:events";
import type { Writable } from "node:stream";
export async function writeAll(dest: Writable, chunks: AsyncIterable<Buffer>) {
for await (const chunk of chunks) {
if (!dest.write(chunk)) {
await once(dest, "drain");
}
}
dest.end();
}
| Knob | Default | Effect |
|---|---|---|
highWaterMark (byte streams) | 64 KiB (Node 22+), 16 KiB earlier | Buffer size before write() returns false |
highWaterMark (object mode) | 16 objects | Same, counted in objects |
writable.writableLength | — | Bytes currently buffered; export as a metric to detect slow consumers |
Profiling
Always profile under realistic load. A profile of an idle server shows startup code; a profile under a synthetic benchmark that hits one endpoint shows only that endpoint. See Load Testing for generating representative traffic, and Node.js Profiling for a tool-by-tool deep dive.
Choosing a Tool
| Question | Tool | Overhead |
|---|---|---|
| Where is CPU time going? | node --cpu-prof, 0x, clinic flame | Low-moderate |
| Is it CPU, I/O, GC, or event loop? | clinic doctor | Low |
| Where are async operations waiting? | clinic bubbleprof | Moderate-high |
| What is allocating memory? | node --heap-prof, clinic heapprofiler | Low (sampling) |
| What is retaining memory? | Heap snapshots (Chrome DevTools) | High — pauses the process |
| Continuous, fleet-wide | Pyroscope / Parca / Datadog continuous profiler | Very low — see Continuous Profiling |
CPU Profiles
# Writes CPU.<date>.<pid>.cpuprofile on exit; open in Chrome DevTools
# (Performance tab → Load profile) or speedscope.app
node --cpu-prof --cpu-prof-dir=/tmp/prof server.js
# Flame graph with 0x (wraps node, generates an interactive HTML flame graph)
npx 0x -o -- node server.js
# ... run load, then Ctrl+C
# Triage: clinic doctor detects the bottleneck category and suggests the next tool
npx clinic doctor --autocannon [ -c 100 -d 30 /api/orders ] -- node server.js
Reading the flame graph: width is time on CPU. Look for wide plateaus at the top of stacks (hot leaf functions) and for unexpected frames — JSON.parse, RegExp, Builtins_*, (garbage collector) — that should not be prominent.
Heap Profiles and Snapshots
# Sampling allocation profile (cheap, safe-ish in staging)
node --heap-prof --heap-prof-dir=/tmp/prof server.js
# Write a heap snapshot when receiving a signal
node --heapsnapshot-signal=SIGUSR2 server.js
kill -USR2 <pid>
# Automatically snapshot as the heap approaches its limit
node --heapsnapshot-near-heap-limit=2 --max-old-space-size=1536 server.js
// Programmatic snapshot from an authenticated admin endpoint
import { writeHeapSnapshot } from "node:v8";
adminRouter.post("/debug/heap-snapshot", (_req, res) => {
const file = writeHeapSnapshot(`/tmp/heap-${process.pid}-${Date.now()}.heapsnapshot`);
res.json({ file });
});
WARNING
Writing a heap snapshot blocks the event loop for seconds (proportional to heap size) and needs roughly as much additional memory as the heap itself. In a container near its limit, taking a snapshot can trigger the very OOMKill you are investigating. Pull the instance out of the load balancer first, and make sure the memory limit has room.
The three-snapshot technique isolates leaks reliably: take snapshot 1 after warm-up, run load, take snapshot 2, run the same load again, take snapshot 3. In DevTools, view snapshot 3 in "Objects allocated between snapshot 1 and 2" mode — anything still alive from that window that grew again is your leak. Follow the Retainers panel up to the GC root to find who is holding it.
Common Leak Patterns
| Pattern | Example | Fix |
|---|---|---|
| Unbounded in-process cache | const cache = new Map() keyed by user/request ID | LRU with max size and TTL (lru-cache) |
| Event listeners never removed | emitter.on("x", handler) per request | once(), remove in finally, or AbortSignal with addEventListener |
| Closures capturing large scope | Timer callback referencing a whole request object | Capture only the fields you need |
| Timers/intervals never cleared | setInterval per connection | Clear on close; .unref() background timers |
| Promises that never settle | Awaiting a reply that never comes; holds the whole async chain | Timeouts via AbortSignal.timeout() |
| Global arrays used as queues | pending.push(job) with no consumer under load | Bounded queue, reject when full |
AsyncLocalStorage stores holding large objects | Request context retains buffers past the response | Store IDs, not payloads |
| Unconsumed HTTP response bodies | fetch() result ignored without reading the body | Always consume or body.cancel() |
| Native/Buffer leaks | Buffers sliced from a huge parent buffer (buf.subarray retains parent) | Buffer.from(slice) to copy small pieces |
// Bounded cache instead of a bare Map
import { LRUCache } from "lru-cache";
export const sessionCache = new LRUCache<string, Session>({
max: 50_000,
ttl: 10 * 60 * 1000,
updateAgeOnGet: true,
});
// Listener tied to the request lifetime via AbortSignal
app.get("/events", (req, res) => {
const ac = new AbortController();
req.on("close", () => ac.abort());
bus.addEventListener(
"order-updated",
(e) => res.write(`data: ${JSON.stringify((e as CustomEvent).detail)}\n\n`),
{ signal: ac.signal } // removed automatically when the client disconnects
);
});
War Story (illustrative)
A Node API was restarting every few hours with heap exhaustion. Snapshots showed hundreds of thousands of ClientRequest objects retained by a Map. The service kept a map of in-flight outbound calls for metrics, deleting entries in the response handler — but calls that timed out at the socket level emitted error instead of response, so their entries lived forever. Under normal traffic the leak was slow; during a downstream partial outage, timeouts spiked and the process died in minutes. The fix was deleting the entry in a finally around the awaited request, and adding a size gauge for the map.
For the full incident workflow — confirming a leak, isolating it across languages, and remediating in production — use the Memory Leak playbook.
Process Model and Scaling
A single Node process uses one core for JavaScript. Use more cores by running more processes:
| Approach | When |
|---|---|
| One process per container, scale with replicas | Kubernetes/ECS — simplest, best isolation, preferred |
cluster module / PM2 cluster mode | VMs or bare metal without an orchestrator |
| Worker threads | CPU-heavy tasks inside one service, shared memory needed |
In Kubernetes, prefer a 1-CPU request per Node replica and scale horizontally; a 4-CPU pod running one Node process wastes three cores unless you run workers or the thread pool is busy.
Production Tuning Checklist
Runtime Flags and Environment
| Setting | Recommendation |
|---|---|
| Node version | Current LTS; each major brings V8 and GC improvements |
NODE_ENV=production | Many frameworks skip dev checks and enable caching |
--max-old-space-size | ~75% of container memory limit |
--max-semi-space-size | 16-64 for allocation-heavy services; measure scavenge frequency |
UV_THREADPOOL_SIZE | Raise (8-16) if you use heavy fs/crypto/zlib/dns.lookup |
--heapsnapshot-near-heap-limit | Enable in staging; in prod only with memory headroom |
--enable-source-maps | Useful for TS stack traces; has a cost on error-heavy paths |
Code and Architecture
-
No
*SyncAPIs in request paths (--trace-sync-ioin staging is clean) - Large JSON payloads are paginated or streamed, not parsed whole
-
All stream chains use
pipeline() -
Every outbound call has a timeout (
AbortSignal.timeout) - HTTP clients reuse connections (keep-alive agent / undici pool)
- Every in-process cache has a max size and TTL
- CPU-heavy work (> ~10ms) goes to a worker pool with a bounded queue
- Hot objects are constructed with a consistent shape
-
Logging is async and structured (pino), not
console.logwith string building -
Concurrency to downstreams is bounded (e.g.
p-limit), notPromise.allover unbounded arrays
Observability
- Event loop lag p99/max and ELU exported
- GC pause histogram by kind exported
-
heapUsed,external,arrayBuffers,rssexported separately - Alerts on lag p99 > 100ms for 5 minutes, and on heap used / heap limit > 85%
- Continuous profiler on at least one replica per service
- Load-shedding or readiness tied to event loop health
// Minimal load shedding on event loop lag
import { monitorEventLoopDelay } from "node:perf_hooks";
const lag = monitorEventLoopDelay({ resolution: 20 });
lag.enable();
const MAX_LAG_MS = 200;
app.addHook("onRequest", async (req, reply) => {
const p99Ms = lag.percentile(99) / 1e6;
if (p99Ms > MAX_LAG_MS && req.url !== "/healthz") {
reply.header("Retry-After", "1").code(503).send({ error: "overloaded" });
}
});
setInterval(() => lag.reset(), 5_000).unref();
Cross-References
- Memory Management — V8 heap spaces, Scavenge, Mark-Compact, WeakRef
- V8 Engine Optimization — compilation tiers, hidden classes, deopts
- Node.js Event Loop Deep Dive — phases, microtasks, libuv thread pool
- Worker Threads and Parallelism — SharedArrayBuffer, Atomics, pools
- Node.js Profiling — profilers in depth
- Node.js Internals — how the runtime is put together
- Benchmarks — measuring changes without fooling yourself
- Memory Leak playbook — incident workflow for leaks
- Kubernetes Resource Management — container limits vs Node heap