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.
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.