Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท node:sqlite and Runtime Services

Node.js monitorEventLoopDelay() function

Reference for perf_hooks.monitorEventLoopDelay(): sample event loop delay into a histogram, read percentiles in nanoseconds and spot blocked loops.

monitorEventLoopDelay() creates a histogram that samples how late the event loop is. Internally a timer is scheduled at a fixed resolution; each time it fires, the difference between the expected and the actual time is recorded. A healthy server shows tiny delays. When some code blocks the loop with heavy synchronous work, the delay grows and shows up in the high percentiles.

The histogram is idle until you call enable(). Values are in nanoseconds. It is the most direct way to see whether your process is struggling to keep up with callbacks.

NODE
import { monitorEventLoopDelay } from 'node:perf_hooks';

const h = monitorEventLoopDelay({ resolution: 10 });
h.enable();
// ... later ...
h.disable();

Try it

Node.js Detecting a blocked event loop

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Node.js Enable, disable and reset

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Syntax

NODE
monitorEventLoopDelay(options?: { resolution?: number }): IntervalHistogram
Name Description
options.resolution Sampling interval in milliseconds, a positive integer. Default 10.

Returns: an IntervalHistogram, which has the usual histogram members (count, min, max, mean, stddev, percentile(p), percentiles, exceeds, reset()) plus:

Method Description
enable() Starts sampling. Returns true if it started, false if it was already running.
disable() Stops sampling. Returns true if it stopped, false if it was not running.

Errors: a RangeError or TypeError (ERR_OUT_OF_RANGE, ERR_INVALID_ARG_TYPE) if resolution is not a positive integer.

Usage notes

  • Values are in nanoseconds. Divide by 1e6 for milliseconds. The recorded delay includes the timer's own interval, so a tiny process may report values near the resolution.
  • Look at percentiles, not just the mean. A few long stalls hide in the mean but stand out at p99 and max.
  • The timer is unref'd: an enabled histogram does not keep the process alive.
  • Reset periodically. Call reset() after you report, so each report covers only a recent window.
  • It measures lag of the loop, not CPU use. For the share of time the loop is busy, use performance.eventLoopUtilization().
  • Sample cost is small, but a very low resolution such as 1 ms adds timer wake-ups; the default is a good start.
  • Per-thread. A worker has its own event loop and needs its own monitor.
  • Added in Node.js 11.10.0.