Observation and diagnostics · Intermediate

Event-loop delay: measure how late loop work runs

Use Node.js monitorEventLoopDelay with explicit units and windows, while distinguishing loop delay from request latency and CPU utilization.

Ask Logeia about this articleTry the three questionsReview your answers

Updated

On this page
  1. Loop delay is not request latency
  2. Collect a histogram over a defined window
  3. Reproduce a bounded blocking interval locally
  4. Use other observations to narrow the cause
  5. Do not average window percentiles
  6. Compare changes under equivalent work
  7. Ask Logeia about this articleCheck your understanding

Loop delay is not request latency

Event-loop delay describes situations in which loop work cannot proceed at its expected time. It is not the complete duration of a request and does not directly separate all network or database waiting. Synchronous work in Node.js can delay timers and other tasks on the same loop. A slow request can also spend time awaiting an external response asynchronously while the loop remains available. Define the boundary being measured before interpreting it. Loop delay and request latency can be related, but neither can simply be renamed as the other or assumed to provide a complete breakdown of the same interval.

Collect a histogram over a defined window

The perf_hooks monitorEventLoopDelay API creates a histogram sampled at a configured resolution. Enable it for collection and disable it after the selected interval. Reported delay values such as mean, maximum, and percentiles are in nanoseconds; dividing by one million converts them to milliseconds. Do not confuse those output units with the resolution option’s units. Check observation duration and whether sufficient samples exist, especially immediately after startup. A peak accumulated over an unspecified lifetime cannot be attributed confidently to one current request. Define the finite measurement window so that the reported histogram has an interpretable operational scope.

Reproduce a bounded blocking interval locally

To understand the monitor, start collection in a separate local test process and introduce a bounded synchronous task after initial sampling. Timers can stage ordinary sampling, deliberate blocking, and final reporting. This artificial workload is a diagnostic demonstration rather than code to insert into a live service. Exact measurements depend on operating-system scheduling and surrounding load, so do not require the reported maximum to equal the chosen blocking duration exactly. The exercise checks units, collection boundaries, and the effect of synchronous occupation. It does not establish a production benchmark or a universal threshold for identifying an unhealthy server.

Node.js 22
const { monitorEventLoopDelay, performance } = require('node:perf_hooks');
const histogram = monitorEventLoopDelay({ resolution: 10 });
histogram.enable();
setTimeout(() => {
  const end = performance.now() + 40;
  while (performance.now() < end) { /* bounded local blocking example */ }
}, 50);
setTimeout(() => {
  histogram.disable();
  const result = { mean_ms: histogram.mean / 1e6,
    p99_ms: histogram.percentile(99) / 1e6, max_ms: histogram.max / 1e6 };
  if (!Number.isFinite(result.mean_ms)) throw new Error('No usable samples');
  console.log(result);
}, 250);

Use other observations to narrow the cause

A large delay does not identify one responsible function. Candidate causes include long synchronous JavaScript, garbage collection, native work, or lack of CPU scheduling opportunity. Compare time-aligned CPU profiles and collection information. Event-loop utilization is also not identical to process CPU utilization. Worker threads and multiple processes make the identity of the monitored loop important. An improvement on one loop does not automatically establish better request performance across the service. Compare request distributions, queues, and completion rates as well. The monitor detects a timing symptom; narrowing the mechanism requires evidence that addresses the competing explanations.

Do not average window percentiles

Averaging one-minute p99 values does not yield the p99 of an hour. Windows can contain different sample counts and distributions. Retain appropriate underlying information or use a suitable histogram aggregation strategy. If reset is used, record that subsequent values describe a new window. A high percentile from a sparse interval may also be unstable. Most importantly, this histogram’s percentile describes event-loop-delay samples, not the percentile of request response durations. Label the measured population explicitly in dashboards and alerts. Otherwise a technically correct percentile calculation can be attached to the wrong service-level interpretation.

Compare changes under equivalent work

After splitting synchronous work, moving suitable work to workers, or bounding input size, repeat the measurement under equivalent input and load. Better responsiveness can trade against total throughput or transfer cost. Worker designs still need bounded queues, data-transfer accounting, and cancellation cleanup. Changing interval, resolution, or units also changes comparison assumptions. Check reduced delay, successful requests, and equal work results as separate outcomes. Disabling the monitor only removes the observation; it is not an improvement in the underlying system. A useful conclusion connects a specific implementation change to consistent measurements and preserved correctness.

Reading and practice are recorded separately in this browser, for each language.

Learn this in order

Build your CS foundations · STEP 12

Choose a learning path