liveBook · Manning

monitorEventLoopDelay

As explained in JavaScript in Depth

A Node.js performance API that measures event-loop delay and reports delay statistics, typically through a histogram.

A 200 ms event-loop delay means queued work waited 200 ms before the loop could reach it; it does not mean one function ran for 200 ms. Long synchronous operations, accumulated smaller operations, or garbage-collection pauses can produce the delay. section 11.1.8

Node.js exposes monitorEventLoopDelay() through node:perf_hooks. It samples at a configured resolution and records nanosecond delay values in a histogram with minimum, maximum, mean, standard deviation, and percentile statistics. The p99 is usually more revealing than the median: a low p50 can coexist with severe latency spikes. section 11.1.8

const { monitorEventLoopDelay } = require('node:perf_hooks');
const h = monitorEventLoopDelay({ resolution: 20 });
h.enable();
 
setInterval(() => {
  console.log(`p50: ${(h.percentile(50) / 1e6).toFixed(1)} ms  ` +
              `p99: ${(h.percentile(99) / 1e6).toFixed(1)} ms`);
  h.reset();
}, 5000);

Collects event-loop delay at 20 ms resolution, reports p50 and p99 every five seconds, and resets the histogram between intervals. section 11.1.8

Use the measurement to narrow performance investigations:

  • Treat low p99 delay as evidence that the loop is keeping up; investigate genuinely expensive functions with CPU profiling. section 11.3.1
  • Correlate elevated delay with --trace-gc; aligned Mark-Compact events implicate garbage collection. section 11.3.1
  • When GC is not responsible, use the CPU profile to distinguish one dominant synchronous function from accumulated callbacks, bursts of small operations, or microtask draining. section 11.3.1
  • Remember that promise-heavy workloads can expose a blind spot: microtask execution is not captured reliably by this delay measurement. section 11.6

How JavaScript in Depth covers it

How deep it goes
Explains histogram sampling, nanosecond statistics, percentile interpretation, and diagnostic branching, but not measurement internals.
Examples
Uses a Node.js histogram that reports p50 and p99 every five seconds, then resets its measurements.
What it assumes
Assumes familiarity with event loops, synchronous execution, garbage collection, microtasks, and CPU profiling.
What you can do after
Diagnose latency spikes by collecting percentiles, correlating GC traces, and selecting CPU profiling when delay remains elevated.
How it connects
Connects event-loop delay with garbage collection, CPU profiling, synchronous JavaScript, microtasks, and event-loop utilization.

Related concepts

This explainer was generated by Manning's knowledge graph from the text of JavaScript in Depth. The section links point to the parts of the book it draws on.