function

perf_hooks.monitorEventLoopDelay

options?: EventLoopMonitorOptions

This property is an extension by Node.js. It is not available in Web browsers.

Creates an IntervalHistogram object that samples and reports the event loop delay over time. The delays will be reported in nanoseconds.

Using a timer to detect approximate event loop delay works because the execution of timers is tied specifically to the lifecycle of the libuv event loop. That is, a delay in the loop will cause a delay in the execution of the timer, and those delays are specifically what this API is intended to detect.

import { monitorEventLoopDelay } from 'node:perf_hooks';
const h = monitorEventLoopDelay({ resolution: 20 });
h.enable();
// Do something.
h.disable();
console.log(h.min);
console.log(h.max);
console.log(h.mean);
console.log(h.stddev);
console.log(h.percentiles);
console.log(h.percentile(50));
console.log(h.percentile(99));

Referenced types

interface EventLoopMonitorOptions

  • resolution?: number

    The sampling rate in milliseconds. Must be greater than zero.

interface IntervalHistogram

  • readonly count: number

    The number of samples recorded by the histogram.

  • readonly countBigInt: bigint

    The number of samples recorded by the histogram. v17.4.0, v16.14.0

  • readonly exceeds: number

    The number of times the event loop delay exceeded the maximum 1 hour event loop delay threshold.

  • readonly exceedsBigInt: bigint

    The number of times the event loop delay exceeded the maximum 1 hour event loop delay threshold.

  • readonly max: number

    The maximum recorded event loop delay.

  • readonly maxBigInt: number

    The maximum recorded event loop delay. v17.4.0, v16.14.0

  • readonly mean: number

    The mean of the recorded event loop delays.

  • readonly min: number

    The minimum recorded event loop delay.

  • readonly minBigInt: bigint

    The minimum recorded event loop delay. v17.4.0, v16.14.0

  • readonly percentiles: Map<number, number>

    Returns a Map object detailing the accumulated percentile distribution.

  • readonly percentilesBigInt: Map<bigint, bigint>

    Returns a Map object detailing the accumulated percentile distribution.

  • readonly stddev: number

    The standard deviation of the recorded event loop delays.

  • Disables the update interval timer when the histogram is disposed.

    const { monitorEventLoopDelay } = require('node:perf_hooks');
{
  using hist = monitorEventLoopDelay({ resolution: 20 });
  hist.enable();
  // The histogram will be disabled when the block is exited.
}
  • disable(): boolean;

    Disables the update interval timer. Returns true if the timer was stopped, false if it was already stopped.

  • enable(): boolean;

    Enables the update interval timer. Returns true if the timer was started, false if it was already started.

  • percentile: number
    ): number;

    Returns the value at the given percentile.

    @param percentile

    A percentile value in the range (0, 100].

  • percentile: number
    ): bigint;

    Returns the value at the given percentile.

    @param percentile

    A percentile value in the range (0, 100].

  • reset(): void;

    Resets the collected histogram data.