Monitoring event-loop lag

Why one slow task freezes everything

Node runs your JavaScript on a single thread. The event loop is a loop that picks up the next ready callback — an expired timer, a completed I/O, a resolved promise — runs it to completion, and only then looks for the next one. There is no preemption: while your callback is executing, nothing else in the process can run. So a single synchronous CPU burst or blocking call — zlib.gzipSync, crypto.pbkdf2Sync, a 5MB JSON.parse, fs.readFileSync on a cold disk — doesn’t just slow that one operation. It holds the thread, and every timer, every socket read, every queued HTTP callback waits behind it. That waiting time is event-loop lag: the gap between when a callback should have run and when the loop actually got to it.

The failure mode is brutal under concurrency. With one request in flight a 250ms block costs that one request 250ms. With 200 requests in flight, the block lands in the middle of the queue and adds up to 250ms of latency to a chunk of those 200 — none of which did anything wrong. This is why the hook’s per-route dashboards lied: the export route’s own latency looked fine, but it was poisoning the tail latency of everything else. The slow code and the slow symptom were on different graphs.

import http from "node:http";
import zlib from "node:zlib";

http.createServer((req, res) => {
  // ❌ blocks the single thread for the whole compression — every other
  // in-flight request's callback waits behind this one.
  const body = zlib.gzipSync(bigPayload);   // ~250ms of pure CPU
  res.setHeader("content-encoding", "gzip");
  res.end(body);
}).listen(3000);

The loop phases (and where lag accrues)

The loop runs in fixed phases, each draining its own callback queue before moving on: timers (setTimeout/setInterval callbacks whose time is up) → pending callbacks (some deferred system callbacks) → poll (where I/O completions are picked up and where the loop blocks waiting for I/O if nothing else is due) → check (setImmediate callbacks) → close (e.g. socket.on('close')). Between every callback, Node drains the microtask queues: process.nextTick first, then resolved promises.

The practical consequence: lag accrues wherever a callback overstays. A heavy setTimeout body delays the next timer; a heavy promise .then delays the next I/O the poll phase wanted to deliver. And process.nextTick is a sharp edge — because it drains before promises and before the loop advances a phase, a recursive nextTick can starve the loop entirely, blocking I/O forever while doing “tiny” work each tick.

// process.nextTick drains before the loop continues — recursion here
// starves I/O completely, even though each call looks trivial.
function spin() { process.nextTick(spin); }
spin();              // ❌ the poll phase never gets to run again

Measuring lag: monitorEventLoopDelay

The right tool is in core: perf_hooks.monitorEventLoopDelay. It samples the loop on a timer at a fixed resolution (default 10ms) and records, in a high-resolution histogram, how late each sample was. You read percentiles off it — and percentiles are the whole point, because lag is bursty: a mean of 2ms can hide a p99 of 400ms during compaction or a GC pause. Watch the tail (p99/max), not the mean. All values are in nanoseconds.

import { monitorEventLoopDelay } from "node:perf_hooks";

const h = monitorEventLoopDelay({ resolution: 20 }); // sample every 20ms
h.enable();

setInterval(() => {
  console.log({
    meanMs: (h.mean / 1e6).toFixed(2),       // healthy: sub-millisecond
    p99Ms:  (h.percentile(99) / 1e6).toFixed(2),
    maxMs:  (h.max / 1e6).toFixed(2),
  });
  h.reset();                                  // start a fresh window
}, 1000).unref();

The naive alternative is timer drift: schedule setInterval(fn, 100) and measure how much later than 100ms each tick actually fires; the overshoot is the lag. It’s cheap and dependency-free but coarse — it only samples at your interval and gives you no histogram, so it misses sub-interval spikes and can’t tell you a p99. For production, monitorEventLoopDelay is strictly better. Going further, libraries like toobusy-js poll lag continuously and let you shed load: when lag crosses a threshold, reject new requests with 503 immediately instead of accepting work you can’t serve, keeping the already-accepted requests fast.

Timing the suspect: performance.mark, measure, observe

Once lag is high, you still have to find which call is blocking. perf_hooks.performance gives you the high-resolution clock and a structured way to time spans without Date.now() math. Use performance.mark(name) to drop timestamps, performance.measure(name, start, end) to record the duration between two marks, and a PerformanceObserver to receive those entries as they’re emitted — so timing is decoupled from the hot path.

import { performance, PerformanceObserver } from "node:perf_hooks";

const obs = new PerformanceObserver((list) => {
  for (const e of list.getEntries()) {
    if (e.duration > 50) console.warn(`SLOW ${e.name}: ${e.duration.toFixed(1)}ms`);
  }
});
obs.observe({ entryTypes: ["measure"] });

performance.mark("gzip:start");
const body = zlib.gzipSync(bigPayload);
performance.mark("gzip:end");
performance.measure("gzip", "gzip:start", "gzip:end"); // shows up in the observer

For ad-hoc checks, performance.now() is a monotonic, sub-millisecond timer (unaffected by wall-clock changes) — const t = performance.now(); …; performance.now() - t is the right way to micro-time a suspect call.