What is event loop lag and why does it add latency to every request?

Event loop lag is the gap between when a callback becomes eligible to run and when the loop actually runs it. A setTimeout scheduled for 10 ms that fires at 85 ms has 75 ms of lag. The same delay applies to I/O callbacks: a socket can be readable and a database reply can be sitting in the kernel buffer, but nothing in your code sees it until the loop gets back to polling.

Node runs your JavaScript on a single thread. When one callback runs synchronously for a long time, whether it is parsing a large JSON body, running a pathological regex, hashing synchronously, or iterating a large array, nothing else in that process makes progress. Every in-flight request waits behind it, including requests that need only a few microseconds of CPU. The added latency is the same for all of them, so lag shows up directly in your tail latency.

Timeline: one blocking task delays everything queued behind it

Time (ms) Main thread Waiting in queue
0 Request A handler starts a 60 ms synchronous parse —
10 still parsing Timer due at 10 ms
25 still parsing Timer, DB reply for request B
40 still parsing Timer, DB reply B, new connection C
60 parse finishes —
60+ Timer runs (50 ms late), then B's reply, then C —

This is why lag is the most direct "too busy to serve" signal. CPU percentage averages over time and hides short stalls. Request latency mixes in downstream slowness. Lag measures exactly how long the process was unable to respond. Backend and platform engineers running latency-sensitive Node.js services, such as APIs, gateways, and real-time backends, should track it alongside request latency.

         Node.js process: one thread runs all JavaScript
 +----------------------------------------------------------------+
 |                                                                |
 |   +---------------------+        +------------------------+    |
 |   | Call stack (busy)   |        | Callback queue         |    |
 |   | Request A handler:  |<-------| timer due @ 10 ms      |    |
 |   | 60 ms sync parse    | blocked| DB reply, request B    |    |
 |   +---------------------+        | new connection C       |    |
 |              |                   +------------------------+    |
 |              | done @ 60 ms                    ^               |
 |              v                               |                 |
 |   +---------------------+        +------------------------+    |
 |   | Loop resumes:       |        | libuv / kernel:        |    |
 |   | timer (50 ms late)  |        | socket readable, DB    |    |
 |   | -> B reply -> C     |        | bytes already buffered |    |
 |   +---------------------+        +------------------------+    |
 |                                                                |
 +----------------------------------------------------------------+

  time 0         10        25        40        60  ms
       |=========|=========|=========|=========|  A blocks the loop
                 ^ timer   ^ B reply ^ conn C
                 |<---------- lag 50 ms ------>|  timer finally runs

A 60 ms synchronous parse in request A holds the only JavaScript thread. The timer, B's database reply and C's new connection are already queued but cannot run until the parse finishes, so the timer runs 50 ms late and the other two wait as well.

Who should use event loop lag monitoring?

Use it if you run long-lived Node.js processes where a stalled thread hurts users or downstream systems:

  • Backend engineers owning HTTP or GraphQL APIs. Every request shares one JavaScript thread per process, so a single slow synchronous path raises latency for all concurrent requests. Lag tells you when that is happening.
  • Teams running WebSocket servers, gateways, and real-time backends. These hold many open connections per process. Missed heartbeats, delayed message fan-out, and timeouts on otherwise healthy connections often trace back to a blocked loop.
  • Platform and SRE engineers who own alerting and capacity. Lag combined with event loop utilization separates "this process needs more capacity" from "this process has a blocking code path," which is a decision you make when sizing fleets and setting autoscaling.
  • Anyone running Node in containers with CPU limits. Throttling appears as lag, so the metric surfaces quota problems that request latency alone attributes to "the app is slow."
  • Queue consumers and background workers with latency expectations. If jobs have deadlines or you share a process between job handling and a health endpoint, lag shows when work is starving everything else.

It is less useful for short-lived processes, services whose heavy work runs entirely off the main thread, near-idle services, and services with sub-millisecond budgets. Those cases are covered in "When to avoid it" at the end of this article.

How does it work? Inside perf_hooks.monitorEventLoopDelay

perf_hooks.monitorEventLoopDelay() returns a histogram object that measures how late the event loop is. You pass an options object with a resolution value in milliseconds (the default is 10). That value sets the sampling interval: the monitor schedules a timer on the event loop, and each time it fires, it records how long it actually took to come back around. If synchronous work held the thread, the timer fires late and a larger value lands in the histogram.

Sampling does nothing until you call enable(). disable() stops it, so you can scope measurement to a window or turn it off during shutdown. The histogram exposes min, max, mean, stddev, a percentile(p) method for a single value such as p99, and a percentiles map of every recorded percentile. A reset() method clears the data, which is what makes windowed reporting possible.

All values are in nanoseconds. A p99 of 12000000 means 12 ms. Convert before exporting, or your dashboards will be off by six orders of magnitude.

Readings never sit at zero, even on an idle process, because each sample is the time elapsed between timer firings. That includes the scheduled interval itself, so with the default resolution, a healthy process reports values just above 10 ms. The signal is how far readings sit above that baseline, not the absolute number.

End to end, a monitoring setup has three parts: the histogram samples the loop continuously, a collector reads percentiles on a fixed interval and resets the histogram, and your metrics system stores those per-window values for dashboards and alerts. The sections that follow cover each part.

A minimal use creates the histogram with a chosen resolution, calls enable(), and later reads percentile(99) divided by 1e6 to get milliseconds.

// Requires Node.js; run with: node loop-delay.js
const { monitorEventLoopDelay } = require('node:perf_hooks');

// Sample every 20 ms. Each sample includes this interval as a baseline.
const histogram = monitorEventLoopDelay({ resolution: 20 });

// Nothing is recorded until enable() is called.
histogram.enable();

// Simulate a burst of synchronous work that blocks the thread for ~200 ms.
setTimeout(() => {
  const end = Date.now() + 200;
  while (Date.now() < end) {} // busy-wait: the sampling timer cannot fire
}, 500);

// Report every 2 seconds, then clear the data for the next window.
const NS_PER_MS = 1e6;
const toMs = (ns) => (ns / NS_PER_MS).toFixed(2);

const report = setInterval(() => {
  console.log({
    minMs: toMs(histogram.min),
    meanMs: toMs(histogram.mean),
    stddevMs: toMs(histogram.stddev),
    p99Ms: toMs(histogram.percentile(99)),
    maxMs: toMs(histogram.max),
  });
  histogram.reset(); // start a fresh window
}, 2000);

// Stop sampling after a few windows so the process can exit cleanly.
setTimeout(() => {
  clearInterval(report);
  histogram.disable();
}, 6100);

Creates an event loop delay histogram with a 20 ms resolution, enables it, blocks the loop once, and reports nanosecond values converted to milliseconds per window; expect min near the 20 ms baseline and a first-window max around 200 ms.

How do you export windowed lag percentiles as metrics?

Run collection on a fixed export interval that matches your scrape or push cadence, for example every 10 or 15 seconds. On each tick, read percentile(50), percentile(99) and max from the histogram. All three are reported in nanoseconds, so divide by 1e6 before emitting. Publish them as gauges, not counters, and label them with an instance identifier such as hostname or pod name. Lag is a per-process property, and averaging it across a fleet hides the one process that is stalling.

After reading the values, call reset() so the next window starts empty. Without it, the histogram accumulates every sample since enable(). Hours of healthy samples then dominate the distribution, so p99 drifts toward a stable value and a new two-second stall barely moves it. Your dashboard flattens at exactly the moment you need it to spike.

reset() also means a histogram can have only one owner. If two consumers read and reset the same instance on different schedules, such as a metrics exporter and a debug endpoint, each one clears data the other has not read yet. Both end up reporting fragments of arbitrary length. Give each consumer its own monitor, or route all reads through a single collector.

The resolution option, in milliseconds, sets how often the timer samples. A finer resolution catches shorter blocks but does slightly more sampling work and reports more jitter. A coarser one is cheaper but can miss brief stalls entirely. The default of 10 ms is a reasonable starting point for most services.

Each worker thread runs its own event loop, so a monitor created on the main thread sees nothing that happens inside workers. Create a separate monitor in each worker and label its metrics with the thread.

const { monitorEventLoopDelay } = require('node:perf_hooks');
const { threadId } = require('node:worker_threads');
const os = require('node:os');

const EXPORT_INTERVAL_MS = 15000; // match your scrape/push cadence
const NS_PER_MS = 1e6;

// Placeholder: replace with your metrics client's gauge setter.
function emitGauge(name, valueMs, labels) {
  console.log(JSON.stringify({ name, value: valueMs, labels }));
}

// One histogram, one owner: only this collector reads and resets it.
// resolution is in ms; 10 is the default. Lower catches shorter stalls.
const histogram = monitorEventLoopDelay({ resolution: 10 });
histogram.enable();

// threadId is 0 on the main thread. Workers must run this file themselves,
// because each worker has its own event loop.
const labels = { instance: os.hostname(), thread: String(threadId) };

const timer = setInterval(() => {
  // All histogram values are in nanoseconds; convert before emitting.
  emitGauge('event_loop_lag_p50_ms', histogram.percentile(50) / NS_PER_MS, labels);
  emitGauge('event_loop_lag_p99_ms', histogram.percentile(99) / NS_PER_MS, labels);
  emitGauge('event_loop_lag_max_ms', histogram.max / NS_PER_MS, labels);

  // Start the next window empty so each export reflects only that window.
  // Without this, old healthy samples dilute new stalls.
  histogram.reset();
}, EXPORT_INTERVAL_MS);

// Don't keep the process alive just for metrics.
timer.unref();

A single collector reads p50, p99 and max from a monitorEventLoopDelay histogram every 15 seconds, converts nanoseconds to milliseconds, emits per-instance and per-thread gauges, then resets the histogram so each window stands alone.

What are the alternatives to monitorEventLoopDelay?

The older approach schedules a setInterval and compares when the callback actually ran against when it was expected to run. The difference is the lag. It works on any Node version, but it records only the most recent value. A 400 ms stall between two scrapes disappears unless you write your own code to keep a running maximum. You also own the timing details yourself: which clock to read, what to do about drift accumulating across ticks, and how much the probe's own interval smooths out short stalls.

monitorEventLoopDelay samples at a fixed resolution and stores every sample in a histogram. That gives you percentiles, a mean, and a max for the whole window, so short spikes still show up.

performance.eventLoopUtilization() measures something different. It reports the fraction of wall time the loop spent running callbacks rather than waiting for I/O. If you pass it the previous reading, it returns the delta for that window. The intended pattern is to read utilization and lag percentiles on the same timer, then reset the histogram.

Technique Retains Answers
Timer drift Last value only "Was the last tick late?"
monitorEventLoopDelay Full distribution per window "How late, how often?"
eventLoopUtilization Busy/idle ratio per window "How close to capacity?"

These two signals mean the most when you read them together:

  • High utilization with steadily elevated lag: the process is saturated. Add capacity or reduce the work done per request.
  • Low utilization with a high p99 or max lag: the loop is mostly idle, but some synchronous task occasionally blocks it, such as a large JSON.parse or synchronous crypto. More instances will not fix this. You need to find the specific code path that blocks.
const { monitorEventLoopDelay, performance } = require('node:perf_hooks');

// Sample loop delay every 20 ms into a histogram (values are in nanoseconds).
const lag = monitorEventLoopDelay({ resolution: 20 });
lag.enable();

const WINDOW_MS = 10_000;
const toMs = (ns) => ns / 1e6;

// Baseline ELU reading; each window's delta is computed against this one.
let lastElu = performance.eventLoopUtilization();

const timer = setInterval(() => {
  // Passing the previous reading returns only this window's busy/idle delta.
  const elu = performance.eventLoopUtilization(lastElu);
  lastElu = performance.eventLoopUtilization();

  const sample = {
    utilization: Number(elu.utilization.toFixed(3)), // 0..1, fraction of time busy
    p50Ms: toMs(lag.percentile(50)),
    p99Ms: toMs(lag.percentile(99)),
    maxMs: toMs(lag.max),
  };

  // Placeholder thresholds; tune them for your service.
  if (sample.utilization > 0.9 && sample.p50Ms > 50) {
    sample.hint = 'saturated: add capacity or reduce per-request work';
  } else if (sample.utilization < 0.5 && sample.maxMs > 200) {
    sample.hint = 'mostly idle but blocked by occasional sync work';
  }

  console.log(JSON.stringify(sample));

  // Start a fresh distribution for the next window, aligned with the ELU delta.
  lag.reset();
}, WINDOW_MS);

// Do not keep the process alive just for monitoring.
timer.unref();

Reads event loop utilization deltas and lag percentiles on the same timer, then resets the histogram so both signals describe the same window and can separate a saturated process from one blocked by occasional synchronous work.

When should you alert on event loop lag, and how do you set thresholds?

Alert on high-percentile lag, such as p99, and require it to stay elevated across several consecutive windows before paging. The other obvious signals fail in predictable ways.

The max is dominated by events that do not indicate a problem: garbage collection pauses, module loading and cache priming at startup, and JIT warm-up after a deploy. A max-based alert fires on every rollout and trains people to ignore it. The mean has the opposite flaw. A loop that is idle most of the time and blocked for 200 ms once per second still averages to a small number, so the mean hides exactly the tail that users experience.

Signal Noise Usefulness for paging
Max High: GC, startup, deploys Low; useful only when investigating
Mean Low Low; hides tail latency
Single-window p99 Medium: one bad window pages Moderate; good for dashboards
Sustained p99 (e.g. 5 of 5 windows) Low High; reflects persistent saturation or blocking

Derive the threshold from your latency SLO. Illustrative estimate, with assumed inputs: the p99 request latency budget is 300 ms, and a typical handler, including downstream I/O, takes 150 ms at p99. That leaves 150 ms of headroom. Reserve part of it for network and queueing variance, and set the lag allowance at about 75 ms. You would then page when p99 lag exceeds 75 ms for five consecutive one-minute windows.

Thresholds do not transfer between services. A batch worker can tolerate seconds of lag without anyone noticing, while the same value would break an interactive API. Set the threshold for each service from that service's own budget.

What should you do when an event loop lag alert fires?

Start by sorting the per-instance series by p99 and looking at the worst few, not the fleet average. Averaging hides a single stuck process behind dozens of healthy ones. If one or two instances are bad, suspect something local: a hot tenant, a pathological request, a noisy neighbor on the same node. If every instance rose together, look for a shared cause such as a deploy, a traffic shift, or a change in payload sizes.

Next, check container CPU throttling before you blame the code. When a container exhausts its CPU quota, the kernel pauses it until the next scheduling period. Timers fire late, and that delay shows up as lag even when nothing in JavaScript is blocking. If throttled periods climb in step with lag, fix the quota or the replica count first.

If throttling is flat, look for the usual culprits:

  • Large payloads. JSON.parse or JSON.stringify on large bodies.
  • Synchronous library calls. The *Sync variants in crypto and zlib.
  • Expensive computation. Regex patterns that backtrack catastrophically on certain inputs, and sorts over large arrays.
  • Blocking I/O. fs.*Sync calls left on a request path.
  • GC pressure. Heap growth that causes long collection pauses.

Confirm the cause with a CPU profile rather than guessing. Windowed lag metrics make this faster because they tell you which process and which time window to capture. You profile the instance that is lagging, during the minutes when it lags, instead of trying to reproduce the problem locally. Once the profile shows the blocking function, move that work to worker_threads or to a separate service.

How can event loop lag monitoring save engineering time?

Most of the time saved comes from shrinking the search space during latency investigations. Without lag metrics, a p99 latency regression in a Node service could be a slow database, a slow downstream API, CPU throttling, GC pressure, or a blocking code path, and engineers often check each one in turn. Windowed lag and utilization metrics cut that list down quickly:

  • Ruling out the downstream path. If request latency rose but lag stayed at baseline, the process was responsive and the time went to I/O. You go straight to dependency latency instead of profiling application code.
  • Separating saturation from blocking. High utilization with steadily elevated lag points to capacity. Low utilization with spiky p99 or max lag points to a specific synchronous code path. That decides whether the fix is a scaling change or a code change, and it avoids adding replicas that cannot help.
  • Pointing the profiler at the right target. Per-instance, per-thread series give you the process and the time window to capture, so you profile the problem in production conditions instead of spending hours failing to reproduce it locally.
  • Catching regressions at deploy time. Comparing lag windows before and after a rollout shows when a change introduced a new blocking call, while the diff is still small and the author still has context. That is cheaper than finding it weeks later during a traffic peak.
  • Reducing noisy pages. Alerting on sustained p99 rather than max or mean means fewer pages that resolve on their own, so on-call time goes to real problems.

The setup cost is a small, reusable module: the collector shown above can be shared across services, and only the thresholds need per-service tuning. The next section sketches an illustrative cost-versus-savings estimate using assumed numbers.

When is event loop lag the wrong signal, and what does it cost to adopt?

Lag tells you that the loop was blocked, not what blocked it. The histogram has no stack traces and no request IDs, so it cannot attribute a 300 ms stall to a JSON parse, a regex, or a synchronous crypto call. It points you at an instance and a time window, and a profiler has to do the rest.

Low lag does not mean the service is healthy. An I/O-bound service waiting on a slow database or downstream API spends that time parked in the event loop's poll phase, which is exactly what the loop is designed to do. The loop stays fast while users wait seconds. For that reason, lag belongs on the same dashboard as request latency, error rate, and per-dependency latency, never in their place.

Fidelity is also bounded by the sampling resolution. Stalls much shorter than the configured interval are blurred or missed, and many short blocks can look like a moderately elevated mean with no single obvious spike.

The adoption cost is small but not zero:

  • A few dozen lines of instrumentation.
  • One gauge set per process or worker thread, which multiplies metric cardinality across a fleet.
  • Per-service threshold tuning.

Illustrative estimate (assumed numbers, not a benchmark): time saved per year = incidents caught early × hours saved per incident. With 4 incidents and 3 hours each, that is 12 hours, against roughly 4 hours to instrument and tune one service.

The real risk is copying a threshold from a CPU-heavy service to a latency-sensitive one. That produces either constant noise or silence.

When to avoid it

Short-lived processes. Serverless handlers, CLI tools, and batch jobs that exit within seconds rarely accumulate enough samples for the high percentiles to mean anything. The final flush can also be lost when the process terminates. Warning sign: your p99 lag series is sparse, jumps between zero and one large value, or has gaps that line up with invocation boundaries. For these workloads, measure invocation duration directly.

Work that is mostly off the main thread. A histogram created on the main thread measures only that thread's loop. If CPU-heavy work runs in worker threads or child processes, the main loop can stay responsive while jobs wait in a worker queue. Warning sign: request latency climbs while main-thread lag stays flat. Instrument queue depth and wait time in the pool instead, or add a separate histogram inside each worker.

Idle or near-idle services. With almost no traffic, the lag percentiles mostly reflect garbage collection pauses and timer jitter, which no request experiences. Alerts on these services fire at night and resolve before anyone looks. Warning sign: lag alerts correlate with low request volume rather than high. Gate the alert on a minimum request rate, or don't page on lag for that service.

Sub-millisecond latency budgets. The default sampling resolution is coarse relative to these budgets. Making it finer adds timer overhead to the process you are trying to protect. If your budget is that tight, trace the hot path itself.

How OneEnv can help

Disclosure: OneEnv is the product behind this blog.

OneEnv (oneenv.io) is a workspace-based governance platform for the things services share — environment variables, database structure, API routes and validation rules. A change to a shared value is staged on a branch, reviewed once, and then every affected service explicitly approves or rejects it before it goes live, so you can see who a change touches before it ships instead of finding out in production.

Applied to node event loop lag monitoring, this is where it helps:

Saves time

  • Every service that inherits a shared value is listed in one place, so nobody searches repos and chats to find out who is affected.
  • One review per branch replaces coordinating each team separately; each service still keeps its own approve/reject.
  • Reviewers see the exact diff and the list of affected services up front, so approval is a decision rather than an investigation.

Saves cost

  • Fewer production incidents and rollbacks caused by a shared value, route or column changing under a consumer unannounced.
  • Less duplicated configuration to maintain: one shared definition inherited by many services.
  • Per-service approve/reject means a bad shared value can be refused where it would break something, before it is live.
  • OneEnv has a free plan (1 workspace, unlimited services and members, full governance), so trying it costs nothing.

These are qualitative benefits, not measured results — how much you save depends on how many services share the value.

Want to try it? Start at oneenv.io.