Node.js v26.5.0 documentation

Performance measurement APIs#

This module provides an implementation of a subset of the W3C Web Performance APIs as well as additional APIs for Node.js-specific performance measurements.

• High Resolution Time
• Performance Timeline
• User Timing
• Resource Timing

import { performance, PerformanceObserver } from 'node:perf_hooks';

const obs = new PerformanceObserver((items) => {
  console.log(items.getEntries()[0].duration);
  performance.clearMarks();
});
obs.observe({ type: 'measure' });
performance.measure('Start to Now');

performance.mark('A');
doSomeLongRunningProcess(() => {
  performance.measure('A to Now', 'A');

  performance.mark('B');
  performance.measure('A to B', 'A', 'B');
});
const { PerformanceObserver, performance } = require('node:perf_hooks');

const obs = new PerformanceObserver((items) => {
  console.log(items.getEntries()[0].duration);
});
obs.observe({ type: 'measure' });
performance.measure('Start to Now');

performance.mark('A');
(async function doSomeLongRunningProcess() {
  await new Promise((r) => setTimeout(r, 5000));
  performance.measure('A to Now', 'A');

  performance.mark('B');
  performance.measure('A to B', 'A', 'B');
})();
javascriptcopy

perf_hooks.performance#

performance.clearMarks([name])#

This method must be called with the performance object as the receiver.

• name <string>

performance.clearMeasures([name])#

This method must be called with the performance object as the receiver.

• name <string>

performance.clearResourceTimings([name])#

This method must be called with the performance object as the receiver.

• name <string>

performance.eventLoopUtilization([utilization1[, utilization2]])#

Added perf_hooks.eventLoopUtilization alias.

• utilization1 <Object> The result of a previous call to eventLoopUtilization().
• utilization2 <Object> The result of a previous call to eventLoopUtilization() prior to utilization1.
• Returns: <Object>
  • idle <number>
  • active <number>
  • utilization <number>

This is an alias of perf_hooks.eventLoopUtilization().

performance.getEntries()#

This method must be called with the performance object as the receiver.

• Returns: <PerformanceEntry>[]

performance.getEntriesByName(name[, type])#

This method must be called with the performance object as the receiver.

• name <string>
• type <string>
• Returns: <PerformanceEntry>[]

performance.getEntriesByType(type)#

This method must be called with the performance object as the receiver.

• type <string>
• Returns: <PerformanceEntry>[]

performance.mark(name[, options])#

Updated to conform to the User Timing Level 3 specification.

• name <string>
• options <Object>
  • detail <any> Additional optional detail to include with the mark.
  • startTime <number> An optional timestamp to be used as the mark time. Default: performance.now().

Creates a new PerformanceMark entry in the Performance Timeline. A PerformanceMark is a subclass of PerformanceEntry whose performanceEntry.entryType is always 'mark', and whose performanceEntry.duration is always 0. Performance marks are used to mark specific significant moments in the Performance Timeline.

performance.markResourceTiming(timingInfo, requestedUrl, initiatorType, global, cacheMode, bodyInfo, responseStatus[, deliveryType])#

Added bodyInfo, responseStatus, and deliveryType arguments.

• timingInfo <Object> Fetch Timing Info
• requestedUrl <string> The resource url
• initiatorType <string> The initiator name, e.g: 'fetch'
• global <Object>
• cacheMode <string> The cache mode must be an empty string ('') or 'local'
• bodyInfo <Object> Fetch Response Body Info
• responseStatus <number> The response's status code
• deliveryType <string> The delivery type.  Default: ''.

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

Creates a new PerformanceResourceTiming entry in the Resource Timeline. A PerformanceResourceTiming is a subclass of PerformanceEntry whose performanceEntry.entryType is always 'resource'. Performance resources are used to mark moments in the Resource Timeline.

performance.measure(name[, startMarkOrOptions[, endMark]])#

Make startMark and endMark parameters optional.

• name <string>
• startMarkOrOptions <string> | <Object> Optional.
  • detail <any> Additional optional detail to include with the measure.
  • duration <number> Duration between start and end times.
  • end <number> | <string> Timestamp to be used as the end time, or a string identifying a previously recorded mark.
  • start <number> | <string> Timestamp to be used as the start time, or a string identifying a previously recorded mark.
• endMark <string> Optional. Must be omitted if startMarkOrOptions is an <Object>.

Creates a new PerformanceMeasure entry in the Performance Timeline. A PerformanceMeasure is a subclass of PerformanceEntry whose performanceEntry.entryType is always 'measure', and whose performanceEntry.duration measures the number of milliseconds elapsed since startMark and endMark.

The startMark argument may identify any existing PerformanceMark in the Performance Timeline, or may identify any of the timestamp properties provided by the PerformanceNodeTiming class. If the named startMark does not exist, an error is thrown.

The optional endMark argument must identify any existing PerformanceMark in the Performance Timeline or any of the timestamp properties provided by the PerformanceNodeTiming class. endMark will be performance.now() if no parameter is passed, otherwise if the named endMark does not exist, an error will be thrown.

performance.nodeTiming#

• Type: <PerformanceNodeTiming>

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

performance.now()#

This method must be called with the performance object as the receiver.

• Returns: <number>

performance.setResourceTimingBufferSize(maxSize)#

This method must be called with the performance object as the receiver.

Sets the global performance resource timing buffer size to the specified number of "resource" type performance entry objects.

performance.timeOrigin#

• Type: <number>

performance.timerify(fn[, options])#

Re-implemented to use pure-JavaScript and the ability to time async functions.

• fn <Function>
• options <Object>
  • histogram <RecordableHistogram> A histogram object created using perf_hooks.createHistogram() that will record runtime durations in nanoseconds.

This is an alias of perf_hooks.timerify().

performance.toJSON()#

This method must be called with the performance object as the receiver.

Event: 'resourcetimingbufferfull'#

Class: PerformanceEntry#

performanceEntry.duration#

This property getter must be called with the PerformanceEntry object as the receiver.

• Type: <number>

performanceEntry.entryType#

This property getter must be called with the PerformanceEntry object as the receiver.

• Type: <string>

• 'dns' (Node.js only)
• 'function' (Node.js only)
• 'gc' (Node.js only)
• 'http2' (Node.js only)
• 'http' (Node.js only)
• 'mark' (available on the Web)
• 'measure' (available on the Web)
• 'net' (Node.js only)
• 'node' (Node.js only)
• 'resource' (available on the Web)

performanceEntry.name#

This property getter must be called with the PerformanceEntry object as the receiver.

• Type: <string>

performanceEntry.startTime#

This property getter must be called with the PerformanceEntry object as the receiver.

• Type: <number>

Class: PerformanceMark#

• Extends: <PerformanceEntry>

performanceMark.detail#

This property getter must be called with the PerformanceMark object as the receiver.

• Type: <any>

Class: PerformanceMeasure#

• Extends: <PerformanceEntry>

Exposes measures created via the Performance.measure() method.

performanceMeasure.detail#

This property getter must be called with the PerformanceMeasure object as the receiver.

• Type: <any>

Class: PerformanceNodeEntry#

• Extends: <PerformanceEntry>

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

Provides detailed Node.js timing data.

performanceNodeEntry.detail#

This property getter must be called with the PerformanceNodeEntry object as the receiver.

• Type: <any>

performanceNodeEntry.flags#

Runtime deprecated. Now moved to the detail property when entryType is 'gc'.

• Type: <number>

• perf_hooks.constants.NODE_PERFORMANCE_GC_FLAGS_NO
• perf_hooks.constants.NODE_PERFORMANCE_GC_FLAGS_CONSTRUCT_RETAINED
• perf_hooks.constants.NODE_PERFORMANCE_GC_FLAGS_FORCED
• perf_hooks.constants.NODE_PERFORMANCE_GC_FLAGS_SYNCHRONOUS_PHANTOM_PROCESSING
• perf_hooks.constants.NODE_PERFORMANCE_GC_FLAGS_ALL_AVAILABLE_GARBAGE
• perf_hooks.constants.NODE_PERFORMANCE_GC_FLAGS_ALL_EXTERNAL_MEMORY
• perf_hooks.constants.NODE_PERFORMANCE_GC_FLAGS_SCHEDULE_IDLE

performanceNodeEntry.kind#

Runtime deprecated. Now moved to the detail property when entryType is 'gc'.

• Type: <number>

• perf_hooks.constants.NODE_PERFORMANCE_GC_MAJOR
• perf_hooks.constants.NODE_PERFORMANCE_GC_MINOR
• perf_hooks.constants.NODE_PERFORMANCE_GC_MINOR_MARK_SWEEP
• perf_hooks.constants.NODE_PERFORMANCE_GC_INCREMENTAL
• perf_hooks.constants.NODE_PERFORMANCE_GC_WEAKCB

Garbage Collection ('gc') Details#

• kind <number> One of:
  • perf_hooks.constants.NODE_PERFORMANCE_GC_MAJOR
  • perf_hooks.constants.NODE_PERFORMANCE_GC_MINOR
  • perf_hooks.constants.NODE_PERFORMANCE_GC_MINOR_MARK_SWEEP
  • perf_hooks.constants.NODE_PERFORMANCE_GC_INCREMENTAL
  • perf_hooks.constants.NODE_PERFORMANCE_GC_WEAKCB
• flags <number> One of:
  • perf_hooks.constants.NODE_PERFORMANCE_GC_FLAGS_NO
  • perf_hooks.constants.NODE_PERFORMANCE_GC_FLAGS_CONSTRUCT_RETAINED
  • perf_hooks.constants.NODE_PERFORMANCE_GC_FLAGS_FORCED
  • perf_hooks.constants.NODE_PERFORMANCE_GC_FLAGS_SYNCHRONOUS_PHANTOM_PROCESSING
  • perf_hooks.constants.NODE_PERFORMANCE_GC_FLAGS_ALL_AVAILABLE_GARBAGE
  • perf_hooks.constants.NODE_PERFORMANCE_GC_FLAGS_ALL_EXTERNAL_MEMORY
  • perf_hooks.constants.NODE_PERFORMANCE_GC_FLAGS_SCHEDULE_IDLE

HTTP ('http') Details#

When performanceEntry.type is equal to 'http', the performanceNodeEntry.detail property will be an <Object> containing additional information.

If performanceEntry.name is equal to HttpClient, the detail will contain the following properties: req, res. And the req property will be an <Object> containing method, url, headers, the res property will be an <Object> containing statusCode, statusMessage, headers.

If performanceEntry.name is equal to HttpRequest, the detail will contain the following properties: req, res. And the req property will be an <Object> containing method, url, headers, the res property will be an <Object> containing statusCode, statusMessage, headers.

HTTP/2 ('http2') Details#

When performanceEntry.type is equal to 'http2', the performanceNodeEntry.detail property will be an <Object> containing additional performance information.

If performanceEntry.name is equal to Http2Stream, the detail will contain the following properties:

• bytesRead <number> The number of DATA frame bytes received for this Http2Stream.
• bytesWritten <number> The number of DATA frame bytes sent for this Http2Stream.
• id <number> The identifier of the associated Http2Stream
• timeToFirstByte <number> The number of milliseconds elapsed between the PerformanceEntry startTime and the reception of the first DATA frame.
• timeToFirstByteSent <number> The number of milliseconds elapsed between the PerformanceEntry startTime and sending of the first DATA frame.
• timeToFirstHeader <number> The number of milliseconds elapsed between the PerformanceEntry startTime and the reception of the first header.

• bytesRead <number> The number of bytes received for this Http2Session.
• bytesWritten <number> The number of bytes sent for this Http2Session.
• framesReceived <number> The number of HTTP/2 frames received by the Http2Session.
• framesSent <number> The number of HTTP/2 frames sent by the Http2Session.
• maxConcurrentStreams <number> The maximum number of streams concurrently open during the lifetime of the Http2Session.
• pingRTT <number> The number of milliseconds elapsed since the transmission of a PING frame and the reception of its acknowledgment. Only present if a PING frame has been sent on the Http2Session.
• streamAverageDuration <number> The average duration (in milliseconds) for all Http2Stream instances.
• streamCount <number> The number of Http2Stream instances processed by the Http2Session.
• type <string> Either 'server' or 'client' to identify the type of Http2Session.

Timerify ('function') Details#

Net ('net') Details#

When performanceEntry.type is equal to 'net', the performanceNodeEntry.detail property will be an <Object> containing additional information.

DNS ('dns') Details#

When performanceEntry.type is equal to 'dns', the performanceNodeEntry.detail property will be an <Object> containing additional information.

If performanceEntry.name is equal to lookup, the detail will contain the following properties: hostname, family, hints, verbatim, addresses.

If performanceEntry.name is equal to lookupService, the detail will contain the following properties: host, port, hostname, service.

Class: PerformanceNodeTiming#

• Extends: <PerformanceEntry>

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

performanceNodeTiming.bootstrapComplete#

• Type: <number>

performanceNodeTiming.environment#

• Type: <number>

performanceNodeTiming.idleTime#

• Type: <number>

performanceNodeTiming.loopExit#

• Type: <number>

performanceNodeTiming.loopStart#

• Type: <number>

performanceNodeTiming.nodeStart#

• Type: <number>

performanceNodeTiming.uvMetricsInfo#

• Returns: <Object>
  • loopCount <number> Number of event loop iterations.
  • events <number> Number of events that have been processed by the event handler.
  • eventsWaiting <number> Number of events that were waiting to be processed when the event provider was called.

This is a wrapper to the uv_metrics_info function. It returns the current set of event loop metrics.

const { performance } = require('node:perf_hooks');

setImmediate(() => {
  console.log(performance.nodeTiming.uvMetricsInfo);
});
import { performance } from 'node:perf_hooks';

setImmediate(() => {
  console.log(performance.nodeTiming.uvMetricsInfo);
});
javascriptcopy

performanceNodeTiming.v8Start#

• Type: <number>

Class: PerformanceResourceTiming#

• Extends: <PerformanceEntry>

Provides detailed network timing data regarding the loading of an application's resources.

performanceResourceTiming.workerStart#

This property getter must be called with the PerformanceResourceTiming object as the receiver.

• Type: <number>

performanceResourceTiming.redirectStart#

This property getter must be called with the PerformanceResourceTiming object as the receiver.

• Type: <number>

performanceResourceTiming.redirectEnd#

This property getter must be called with the PerformanceResourceTiming object as the receiver.

• Type: <number>

performanceResourceTiming.fetchStart#

This property getter must be called with the PerformanceResourceTiming object as the receiver.

• Type: <number>

performanceResourceTiming.domainLookupStart#

This property getter must be called with the PerformanceResourceTiming object as the receiver.

• Type: <number>

performanceResourceTiming.domainLookupEnd#

This property getter must be called with the PerformanceResourceTiming object as the receiver.

• Type: <number>

performanceResourceTiming.connectStart#

This property getter must be called with the PerformanceResourceTiming object as the receiver.

• Type: <number>

performanceResourceTiming.connectEnd#

This property getter must be called with the PerformanceResourceTiming object as the receiver.

• Type: <number>

performanceResourceTiming.secureConnectionStart#

This property getter must be called with the PerformanceResourceTiming object as the receiver.

• Type: <number>

performanceResourceTiming.requestStart#

This property getter must be called with the PerformanceResourceTiming object as the receiver.

• Type: <number>

performanceResourceTiming.responseEnd#

This property getter must be called with the PerformanceResourceTiming object as the receiver.

• Type: <number>

performanceResourceTiming.transferSize#

This property getter must be called with the PerformanceResourceTiming object as the receiver.

• Type: <number>

performanceResourceTiming.encodedBodySize#

This property getter must be called with the PerformanceResourceTiming object as the receiver.

• Type: <number>

performanceResourceTiming.decodedBodySize#

This property getter must be called with the PerformanceResourceTiming object as the receiver.

• Type: <number>

performanceResourceTiming.toJSON()#

This method must be called with the PerformanceResourceTiming object as the receiver.

PerformanceObserver.supportedEntryTypes#

• Type: <string>[]

new PerformanceObserver(callback)#

Passing an invalid callback to the callback argument now throws ERR_INVALID_ARG_TYPE instead of ERR_INVALID_CALLBACK.

• callback <Function>
  • list <PerformanceObserverEntryList>
  • observer <PerformanceObserver>

PerformanceObserver objects provide notifications when new PerformanceEntry instances have been added to the Performance Timeline.

import { performance, PerformanceObserver } from 'node:perf_hooks';

const obs = new PerformanceObserver((list, observer) => {
  console.log(list.getEntries());

  performance.clearMarks();
  performance.clearMeasures();
  observer.disconnect();
});
obs.observe({ entryTypes: ['mark'], buffered: true });

performance.mark('test');
const {
  performance,
  PerformanceObserver,
} = require('node:perf_hooks');

const obs = new PerformanceObserver((list, observer) => {
  console.log(list.getEntries());

  performance.clearMarks();
  performance.clearMeasures();
  observer.disconnect();
});
obs.observe({ entryTypes: ['mark'], buffered: true });

performance.mark('test');
javascriptcopy

Because PerformanceObserver instances introduce their own additional performance overhead, instances should not be left subscribed to notifications indefinitely. Users should disconnect observers as soon as they are no longer needed.

performanceObserver.disconnect()#

performanceObserver.observe(options)#

Updated to conform to User Timing Level 3. The buffered option has been removed.

• options <Object>
  • type <string> A single <PerformanceEntry> type. Must not be given if entryTypes is already specified.
  • entryTypes <string>[] An array of strings identifying the types of <PerformanceEntry> instances the observer is interested in. If not provided an error will be thrown.
  • buffered <boolean> If true, the observer callback is called with a list global PerformanceEntry buffered entries. If false, only PerformanceEntrys created after the time point are sent to the observer callback. Default: false.

import { performance, PerformanceObserver } from 'node:perf_hooks';

const obs = new PerformanceObserver((list, observer) => {
  // Called once asynchronously. `list` contains three items.
});
obs.observe({ type: 'mark' });

for (let n = 0; n < 3; n++)
  performance.mark(`test${n}`);
const {
  performance,
  PerformanceObserver,
} = require('node:perf_hooks');

const obs = new PerformanceObserver((list, observer) => {
  // Called once asynchronously. `list` contains three items.
});
obs.observe({ type: 'mark' });

for (let n = 0; n < 3; n++)
  performance.mark(`test${n}`);
javascriptcopy

Class: PerformanceObserverEntryList#

performanceObserverEntryList.getEntries()#

• Returns: <PerformanceEntry>[]

import { performance, PerformanceObserver } from 'node:perf_hooks';

const obs = new PerformanceObserver((perfObserverList, observer) => {
  console.log(perfObserverList.getEntries());
  /**
   * [
   *   PerformanceEntry {
   *     name: 'test',
   *     entryType: 'mark',
   *     startTime: 81.465639,
   *     duration: 0,
   *     detail: null
   *   },
   *   PerformanceEntry {
   *     name: 'meow',
   *     entryType: 'mark',
   *     startTime: 81.860064,
   *     duration: 0,
   *     detail: null
   *   }
   * ]
   */

  performance.clearMarks();
  performance.clearMeasures();
  observer.disconnect();
});
obs.observe({ type: 'mark' });

performance.mark('test');
performance.mark('meow');
const {
  performance,
  PerformanceObserver,
} = require('node:perf_hooks');

const obs = new PerformanceObserver((perfObserverList, observer) => {
  console.log(perfObserverList.getEntries());
  /**
   * [
   *   PerformanceEntry {
   *     name: 'test',
   *     entryType: 'mark',
   *     startTime: 81.465639,
   *     duration: 0,
   *     detail: null
   *   },
   *   PerformanceEntry {
   *     name: 'meow',
   *     entryType: 'mark',
   *     startTime: 81.860064,
   *     duration: 0,
   *     detail: null
   *   }
   * ]
   */

  performance.clearMarks();
  performance.clearMeasures();
  observer.disconnect();
});
obs.observe({ type: 'mark' });

performance.mark('test');
performance.mark('meow');
javascriptcopy

performanceObserverEntryList.getEntriesByName(name[, type])#

• name <string>
• type <string>
• Returns: <PerformanceEntry>[]

import { performance, PerformanceObserver } from 'node:perf_hooks';

const obs = new PerformanceObserver((perfObserverList, observer) => {
  console.log(perfObserverList.getEntriesByName('meow'));
  /**
   * [
   *   PerformanceEntry {
   *     name: 'meow',
   *     entryType: 'mark',
   *     startTime: 98.545991,
   *     duration: 0,
   *     detail: null
   *   }
   * ]
   */
  console.log(perfObserverList.getEntriesByName('nope')); // []

  console.log(perfObserverList.getEntriesByName('test', 'mark'));
  /**
   * [
   *   PerformanceEntry {
   *     name: 'test',
   *     entryType: 'mark',
   *     startTime: 63.518931,
   *     duration: 0,
   *     detail: null
   *   }
   * ]
   */
  console.log(perfObserverList.getEntriesByName('test', 'measure')); // []

  performance.clearMarks();
  performance.clearMeasures();
  observer.disconnect();
});
obs.observe({ entryTypes: ['mark', 'measure'] });

performance.mark('test');
performance.mark('meow');
const {
  performance,
  PerformanceObserver,
} = require('node:perf_hooks');

const obs = new PerformanceObserver((perfObserverList, observer) => {
  console.log(perfObserverList.getEntriesByName('meow'));
  /**
   * [
   *   PerformanceEntry {
   *     name: 'meow',
   *     entryType: 'mark',
   *     startTime: 98.545991,
   *     duration: 0,
   *     detail: null
   *   }
   * ]
   */
  console.log(perfObserverList.getEntriesByName('nope')); // []

  console.log(perfObserverList.getEntriesByName('test', 'mark'));
  /**
   * [
   *   PerformanceEntry {
   *     name: 'test',
   *     entryType: 'mark',
   *     startTime: 63.518931,
   *     duration: 0,
   *     detail: null
   *   }
   * ]
   */
  console.log(perfObserverList.getEntriesByName('test', 'measure')); // []

  performance.clearMarks();
  performance.clearMeasures();
  observer.disconnect();
});
obs.observe({ entryTypes: ['mark', 'measure'] });

performance.mark('test');
performance.mark('meow');
javascriptcopy

performanceObserverEntryList.getEntriesByType(type)#

• type <string>
• Returns: <PerformanceEntry>[]

import { performance, PerformanceObserver } from 'node:perf_hooks';

const obs = new PerformanceObserver((perfObserverList, observer) => {
  console.log(perfObserverList.getEntriesByType('mark'));
  /**
   * [
   *   PerformanceEntry {
   *     name: 'test',
   *     entryType: 'mark',
   *     startTime: 55.897834,
   *     duration: 0,
   *     detail: null
   *   },
   *   PerformanceEntry {
   *     name: 'meow',
   *     entryType: 'mark',
   *     startTime: 56.350146,
   *     duration: 0,
   *     detail: null
   *   }
   * ]
   */
  performance.clearMarks();
  performance.clearMeasures();
  observer.disconnect();
});
obs.observe({ type: 'mark' });

performance.mark('test');
performance.mark('meow');
const {
  performance,
  PerformanceObserver,
} = require('node:perf_hooks');

const obs = new PerformanceObserver((perfObserverList, observer) => {
  console.log(perfObserverList.getEntriesByType('mark'));
  /**
   * [
   *   PerformanceEntry {
   *     name: 'test',
   *     entryType: 'mark',
   *     startTime: 55.897834,
   *     duration: 0,
   *     detail: null
   *   },
   *   PerformanceEntry {
   *     name: 'meow',
   *     entryType: 'mark',
   *     startTime: 56.350146,
   *     duration: 0,
   *     detail: null
   *   }
   * ]
   */
  performance.clearMarks();
  performance.clearMeasures();
  observer.disconnect();
});
obs.observe({ type: 'mark' });

performance.mark('test');
performance.mark('meow');
javascriptcopy

perf_hooks.createHistogram([options])#

• options <Object>
  • lowest <number> | <bigint> The lowest discernible value. Must be an integer value greater than 0. Default: 1.
  • highest <number> | <bigint> The highest recordable value. Must be an integer value that is equal to or greater than two times lowest. Default: Number.MAX_SAFE_INTEGER.
  • figures <number> The number of accuracy digits. Must be a number between 1 and 5. Default: 3.
• Returns: <RecordableHistogram>

perf_hooks.eventLoopUtilization([utilization1[, utilization2]])#

• utilization1 <Object> The result of a previous call to eventLoopUtilization().
• utilization2 <Object> The result of a previous call to eventLoopUtilization() prior to utilization1.
• Returns: <Object>
  • idle <number>
  • active <number>
  • utilization <number>

The eventLoopUtilization() function returns an object that contains the cumulative duration of time the event loop has been both idle and active as a high resolution milliseconds timer. The utilization value is the calculated Event Loop Utilization (ELU).

If bootstrapping has not yet finished on the main thread the properties have the value of 0. The ELU is immediately available on Worker threads since bootstrap happens within the event loop.

Both utilization1 and utilization2 are optional parameters.

If utilization1 is passed, then the delta between the current call's active and idle times, as well as the corresponding utilization value are calculated and returned (similar to process.hrtime()).

If utilization1 and utilization2 are both passed, then the delta is calculated between the two arguments. This is a convenience option because, unlike process.hrtime(), calculating the ELU is more complex than a single subtraction.

ELU is similar to CPU utilization, except that it only measures event loop statistics and not CPU usage. It represents the percentage of time the event loop has spent outside the event loop's event provider (e.g. epoll_wait). No other CPU idle time is taken into consideration. The following is an example of how a mostly idle process will have a high ELU.

import { eventLoopUtilization } from 'node:perf_hooks';
import { spawnSync } from 'node:child_process';

setImmediate(() => {
  const elu = eventLoopUtilization();
  spawnSync('sleep', ['5']);
  console.log(eventLoopUtilization(elu).utilization);
});
const { eventLoopUtilization } = require('node:perf_hooks');
const { spawnSync } = require('node:child_process');

setImmediate(() => {
  const elu = eventLoopUtilization();
  spawnSync('sleep', ['5']);
  console.log(eventLoopUtilization(elu).utilization);
});
javascriptcopy

Although the CPU is mostly idle while running this script, the value of utilization is 1. This is because the call to child_process.spawnSync() blocks the event loop from proceeding.

perf_hooks.monitorEventLoopDelay([options])#

Added the samplePerIteration option.

• options <Object>
  • samplePerIteration <boolean> When true, samples are taken once per event loop iteration. Default: false.
  • resolution <number> The sampling rate in milliseconds for interval-based sampling. Must be greater than zero. This option is ignored when samplePerIteration is true. Default: 10.
• Returns: {ELDHistogram}

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

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

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));
const { monitorEventLoopDelay } = require('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));
javascriptcopy

perf_hooks.timerify(fn[, options])#

• fn <Function>
• options <Object>
  • histogram <RecordableHistogram> A histogram object created using perf_hooks.createHistogram() that will record runtime durations in nanoseconds.

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

Wraps a function within a new function that measures the running time of the wrapped function. A PerformanceObserver must be subscribed to the 'function' event type in order for the timing details to be accessed.

import { timerify, performance, PerformanceObserver } from 'node:perf_hooks';

function someFunction() {
  console.log('hello world');
}

const wrapped = timerify(someFunction);

const obs = new PerformanceObserver((list) => {
  console.log(list.getEntries()[0].duration);

  performance.clearMarks();
  performance.clearMeasures();
  obs.disconnect();
});
obs.observe({ entryTypes: ['function'] });

// A performance timeline entry will be created
wrapped();
const {
  timerify,
  performance,
  PerformanceObserver,
} = require('node:perf_hooks');

function someFunction() {
  console.log('hello world');
}

const wrapped = timerify(someFunction);

const obs = new PerformanceObserver((list) => {
  console.log(list.getEntries()[0].duration);

  performance.clearMarks();
  performance.clearMeasures();
  obs.disconnect();
});
obs.observe({ entryTypes: ['function'] });

// A performance timeline entry will be created
wrapped();
javascriptcopy

histogram.count#

• Type: <number>

histogram.countBigInt#

• Type: <bigint>

histogram.exceeds#

• Type: <number>

histogram.exceedsBigInt#

• Type: <bigint>

histogram.max#

• Type: <number>

histogram.maxBigInt#

• Type: <bigint>

histogram.mean#

• Type: <number>

histogram.min#

• Type: <number>

histogram.minBigInt#

• Type: <bigint>

histogram.percentile(percentile)#

• percentile <number> A percentile value in the range (0, 100].
• Returns: <number>

histogram.percentileBigInt(percentile)#

• percentile <number> A percentile value in the range (0, 100].
• Returns: <bigint>

histogram.percentiles#

• Type: <Map>

histogram.percentilesBigInt#

• Type: <Map>

histogram.reset()#

histogram.stddev#

• Type: <number>

Class: ELDHistogram extends Histogram#

histogram.disable()#

• Returns: <boolean>

histogram.enable()#

• Returns: <boolean>

histogram[Symbol.dispose]()#

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

Cloning an ELDHistogram#

histogram.add(other)#

• other <RecordableHistogram>

histogram.recordDelta()#

Measuring the duration of async operations#

import { createHook } from 'node:async_hooks';
import { performance, PerformanceObserver } from 'node:perf_hooks';

const set = new Set();
const hook = createHook({
  init(id, type) {
    if (type === 'Timeout') {
      performance.mark(`Timeout-${id}-Init`);
      set.add(id);
    }
  },
  destroy(id) {
    if (set.has(id)) {
      set.delete(id);
      performance.mark(`Timeout-${id}-Destroy`);
      performance.measure(`Timeout-${id}`,
                          `Timeout-${id}-Init`,
                          `Timeout-${id}-Destroy`);
    }
  },
});
hook.enable();

const obs = new PerformanceObserver((list, observer) => {
  console.log(list.getEntries()[0]);
  performance.clearMarks();
  performance.clearMeasures();
  observer.disconnect();
});
obs.observe({ entryTypes: ['measure'], buffered: true });

setTimeout(() => {}, 1000);
const async_hooks = require('node:async_hooks');
const {
  performance,
  PerformanceObserver,
} = require('node:perf_hooks');

const set = new Set();
const hook = async_hooks.createHook({
  init(id, type) {
    if (type === 'Timeout') {
      performance.mark(`Timeout-${id}-Init`);
      set.add(id);
    }
  },
  destroy(id) {
    if (set.has(id)) {
      set.delete(id);
      performance.mark(`Timeout-${id}-Destroy`);
      performance.measure(`Timeout-${id}`,
                          `Timeout-${id}-Init`,
                          `Timeout-${id}-Destroy`);
    }
  },
});
hook.enable();

const obs = new PerformanceObserver((list, observer) => {
  console.log(list.getEntries()[0]);
  performance.clearMarks();
  performance.clearMeasures();
  observer.disconnect();
});
obs.observe({ entryTypes: ['measure'] });

setTimeout(() => {}, 1000);
javascriptcopy

Measuring how long it takes to load dependencies#

import { performance, PerformanceObserver } from 'node:perf_hooks';

// Activate the observer
const obs = new PerformanceObserver((list) => {
  const entries = list.getEntries();
  entries.forEach((entry) => {
    console.log(`import('${entry[0]}')`, entry.duration);
  });
  performance.clearMarks();
  performance.clearMeasures();
  obs.disconnect();
});
obs.observe({ entryTypes: ['function'], buffered: true });

const timedImport = performance.timerify(async (module) => {
  return await import(module);
});

await timedImport('some-module');
const {
  performance,
  PerformanceObserver,
} = require('node:perf_hooks');
const mod = require('node:module');

// Monkey patch the require function
mod.Module.prototype.require =
  performance.timerify(mod.Module.prototype.require);
require = performance.timerify(require);

// Activate the observer
const obs = new PerformanceObserver((list) => {
  const entries = list.getEntries();
  entries.forEach((entry) => {
    console.log(`require('${entry[0]}')`, entry.duration);
  });
  performance.clearMarks();
  performance.clearMeasures();
  obs.disconnect();
});
obs.observe({ entryTypes: ['function'] });

require('some-module');
javascriptcopy

Measuring how long one HTTP round-trip takes#

The following example is used to trace the time spent by HTTP client (OutgoingMessage) and HTTP request (IncomingMessage). For HTTP client, it means the time interval between starting the request and receiving the response, and for HTTP request, it means the time interval between receiving the request and sending the response:

import { PerformanceObserver } from 'node:perf_hooks';
import { createServer, get } from 'node:http';

const obs = new PerformanceObserver((items) => {
  items.getEntries().forEach((item) => {
    console.log(item);
  });
});

obs.observe({ entryTypes: ['http'] });

const PORT = 8080;

createServer((req, res) => {
  res.end('ok');
}).listen(PORT, () => {
  get(`http://127.0.0.1:${PORT}`);
});
const { PerformanceObserver } = require('node:perf_hooks');
const http = require('node:http');

const obs = new PerformanceObserver((items) => {
  items.getEntries().forEach((item) => {
    console.log(item);
  });
});

obs.observe({ entryTypes: ['http'] });

const PORT = 8080;

http.createServer((req, res) => {
  res.end('ok');
}).listen(PORT, () => {
  http.get(`http://127.0.0.1:${PORT}`);
});
javascriptcopy

import { PerformanceObserver } from 'node:perf_hooks';
import { connect, createServer } from 'node:net';

const obs = new PerformanceObserver((items) => {
  items.getEntries().forEach((item) => {
    console.log(item);
  });
});
obs.observe({ entryTypes: ['net'] });
const PORT = 8080;
createServer((socket) => {
  socket.destroy();
}).listen(PORT, () => {
  connect(PORT);
});
const { PerformanceObserver } = require('node:perf_hooks');
const net = require('node:net');
const obs = new PerformanceObserver((items) => {
  items.getEntries().forEach((item) => {
    console.log(item);
  });
});
obs.observe({ entryTypes: ['net'] });
const PORT = 8080;
net.createServer((socket) => {
  socket.destroy();
}).listen(PORT, () => {
  net.connect(PORT);
});
javascriptcopy

import { PerformanceObserver } from 'node:perf_hooks';
import { lookup, promises } from 'node:dns';

const obs = new PerformanceObserver((items) => {
  items.getEntries().forEach((item) => {
    console.log(item);
  });
});
obs.observe({ entryTypes: ['dns'] });
lookup('localhost', () => {});
promises.resolve('localhost');
const { PerformanceObserver } = require('node:perf_hooks');
const dns = require('node:dns');
const obs = new PerformanceObserver((items) => {
  items.getEntries().forEach((item) => {
    console.log(item);
  });
});
obs.observe({ entryTypes: ['dns'] });
dns.lookup('localhost', () => {});
dns.promises.resolve('localhost');
javascriptcopy