The constructor of this class is not exposed to users directly.
Node.js module
perf_hooks
The 'node:perf_hooks' module provides performance measurement APIs based on the User Timing specification. It includes performance.now(), performance.mark, performance.measure, and PerformanceObserver.
Use it to benchmark code execution, measure memory usage, and observe performance entries for timely optimization.
Works in Bun
Missing event loop delay monitoring. It's recommended to use the `performance` global instead of `perf_hooks.performance`.
namespace constants
class PerformanceEntry
class PerformanceMark
Exposes marks created via the
Performance.mark()method.- readonly duration: 0
The total number of milliseconds elapsed for this entry. This value will not be meaningful for all Performance Entry types.
- readonly entryType: 'mark'
The type of the performance entry. It may be one of:
'node'(Node.js only)'mark'(available on the Web)'measure'(available on the Web)'gc'(Node.js only)'function'(Node.js only)'http2'(Node.js only)'http'(Node.js only)
- readonly startTime: number
The high resolution millisecond timestamp marking the starting time of the Performance Entry.
class PerformanceMeasure
Exposes measures created via the
Performance.measure()method.The constructor of this class is not exposed to users directly.
- readonly duration: number
The total number of milliseconds elapsed for this entry. This value will not be meaningful for all Performance Entry types.
- readonly entryType: 'measure'
The type of the performance entry. It may be one of:
'node'(Node.js only)'mark'(available on the Web)'measure'(available on the Web)'gc'(Node.js only)'function'(Node.js only)'http2'(Node.js only)'http'(Node.js only)
- readonly startTime: number
The high resolution millisecond timestamp marking the starting time of the Performance Entry.
class PerformanceNodeTiming
This property is an extension by Node.js. It is not available in Web browsers.
Provides timing details for Node.js itself. The constructor of this class is not exposed to users.
- readonly bootstrapComplete: number
The high resolution millisecond timestamp at which the Node.js process completed bootstrapping. If bootstrapping has not yet finished, the property has the value of -1.
- readonly duration: number
The total number of milliseconds elapsed for this entry. This value will not be meaningful for all Performance Entry types.
- readonly entryType: 'node'
The type of the performance entry. It may be one of:
'node'(Node.js only)'mark'(available on the Web)'measure'(available on the Web)'gc'(Node.js only)'function'(Node.js only)'http2'(Node.js only)'http'(Node.js only)
- readonly environment: number
The high resolution millisecond timestamp at which the Node.js environment was initialized.
- readonly idleTime: number
The high resolution millisecond timestamp of the amount of time the event loop has been idle within the event loop's event provider (e.g.
epoll_wait). This does not take CPU usage into consideration. If the event loop has not yet started (e.g., in the first tick of the main script), the property has the value of 0. - readonly loopExit: number
The high resolution millisecond timestamp at which the Node.js event loop exited. If the event loop has not yet exited, the property has the value of -1. It can only have a value of not -1 in a handler of the
'exit'event. - readonly loopStart: number
The high resolution millisecond timestamp at which the Node.js event loop started. If the event loop has not yet started (e.g., in the first tick of the main script), the property has the value of -1.
- readonly nodeStart: number
The high resolution millisecond timestamp at which the Node.js process was initialized.
- readonly startTime: number
The high resolution millisecond timestamp marking the starting time of the Performance Entry.
- readonly uvMetricsInfo: UVMetrics
This is a wrapper to the
uv_metrics_infofunction. It returns the current set of event loop metrics.It is recommended to use this property inside a function whose execution was scheduled using
setImmediateto avoid collecting metrics before finishing all operations scheduled during the current loop iteration. - readonly v8Start: number
The high resolution millisecond timestamp at which the V8 platform was initialized.
class PerformanceObserver
- @returns
The unique
asyncIdassigned to the resource. - fn: Func): Func;
Binds the given function to execute to this
AsyncResource's scope.@param fnThe function to bind to the current
AsyncResource. Disconnects the
PerformanceObserverinstance from all notifications.Call all
destroyhooks. This should only ever be called once. An error will be thrown if it is called more than once. This must be manually called. If the resource is left to be collected by the GC then thedestroyhooks will never be called.@returnsA reference to
asyncResource.- options: { buffered: boolean; entryTypes: readonly EntryType[] } | { buffered: boolean; type: EntryType }): void;
Subscribes the
PerformanceObserverinstance to notifications of newPerformanceEntryinstances identified either byoptions.entryTypesoroptions.type: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}`); - fn: (this: This, ...args: any[]) => Result,thisArg?: This,...args: any[]): Result;
Call the provided function with the provided arguments in the execution context of the async resource. This will establish the context, trigger the AsyncHooks before callbacks, call the function, trigger the AsyncHooks after callbacks, and then restore the original execution context.
@param fnThe function to call in the execution context of this async resource.
@param thisArgThe receiver to be used for the function call.
@param argsOptional arguments to pass to the function.
- @returns
Current list of entries stored in the performance observer, emptying it out.
- @returns
The same
triggerAsyncIdthat is passed to theAsyncResourceconstructor. - fn: Func,type?: string,thisArg?: ThisArg): Func;
Binds the given function to the current execution context.
@param fnThe function to bind to the current execution context.
@param typeAn optional name to associate with the underlying
AsyncResource.
Returns a list of
PerformanceEntryobjects in chronological order with respect toperformanceEntry.startTime.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');- name: string,
Returns a list of
PerformanceEntryobjects in chronological order with respect toperformanceEntry.startTimewhoseperformanceEntry.nameis equal toname, and optionally, whoseperformanceEntry.entryTypeis equal totype.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'); Returns a list of
PerformanceEntryobjects in chronological order with respect toperformanceEntry.startTimewhoseperformanceEntry.entryTypeis equal totype.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');
class PerformanceResourceTiming
Provides detailed network timing data regarding the loading of an application's resources.
The constructor of this class is not exposed to users directly.
- readonly connectEnd: number
The high resolution millisecond timestamp representing the time immediately after Node.js finishes establishing the connection to the server to retrieve the resource.
- readonly connectStart: number
The high resolution millisecond timestamp representing the time immediately before Node.js starts to establish the connection to the server to retrieve the resource.
- readonly decodedBodySize: number
A number representing the size (in octets) received from the fetch (HTTP or cache), of the message body, after removing any applied content-codings.
- readonly domainLookupEnd: number
The high resolution millisecond timestamp representing the time immediately after the Node.js finished the domain name lookup for the resource.
- readonly domainLookupStart: number
The high resolution millisecond timestamp immediately before the Node.js starts the domain name lookup for the resource.
- readonly duration: number
The total number of milliseconds elapsed for this entry. This value will not be meaningful for all Performance Entry types.
- readonly encodedBodySize: number
A number representing the size (in octets) received from the fetch (HTTP or cache), of the payload body, before removing any applied content-codings.
- readonly entryType: 'resource'
The type of the performance entry. It may be one of:
'node'(Node.js only)'mark'(available on the Web)'measure'(available on the Web)'gc'(Node.js only)'function'(Node.js only)'http2'(Node.js only)'http'(Node.js only)
- readonly fetchStart: number
The high resolution millisecond timestamp immediately before the Node.js starts to fetch the resource.
- readonly redirectEnd: number
The high resolution millisecond timestamp that will be created immediately after receiving the last byte of the response of the last redirect.
- readonly redirectStart: number
The high resolution millisecond timestamp that represents the start time of the fetch which initiates the redirect.
- readonly requestStart: number
The high resolution millisecond timestamp representing the time immediately before Node.js receives the first byte of the response from the server.
- readonly responseEnd: number
The high resolution millisecond timestamp representing the time immediately after Node.js receives the last byte of the resource or immediately before the transport connection is closed, whichever comes first.
- readonly secureConnectionStart: number
The high resolution millisecond timestamp representing the time immediately before Node.js starts the handshake process to secure the current connection.
- readonly startTime: number
The high resolution millisecond timestamp marking the starting time of the Performance Entry.
- readonly transferSize: number
A number representing the size (in octets) of the fetched resource. The size includes the response header fields plus the response payload body.
- readonly workerStart: number
The high resolution millisecond timestamp at immediately before dispatching the
fetchrequest. If the resource is not intercepted by a worker the property will always return 0. Returns a
objectthat is the JSON representation of thePerformanceResourceTimingobject
Returns a
RecordableHistogram.This property is an extension by Node.js. It is not available in Web browsers.
Creates an
IntervalHistogramobject 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));
Type definitions
interface CreateHistogramOptions
interface EventLoopMonitorOptions
interface EventLoopUtilization
interface Histogram
- 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 percentiles: Map<number, number>
Returns a
Mapobject detailing the accumulated percentile distribution. - readonly percentilesBigInt: Map<bigint, bigint>
Returns a
Mapobject detailing the accumulated percentile distribution. - @param percentile
A percentile value in the range (0, 100].
- @param percentile
A percentile value in the range (0, 100].
Resets the collected histogram data.
interface IntervalHistogram
- 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 percentiles: Map<number, number>
Returns a
Mapobject detailing the accumulated percentile distribution. - readonly percentilesBigInt: Map<bigint, bigint>
Returns a
Mapobject detailing the accumulated percentile distribution. 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. }Disables the update interval timer. Returns
trueif the timer was stopped,falseif it was already stopped.Enables the update interval timer. Returns
trueif the timer was started,falseif it was already started.- @param percentile
A percentile value in the range (0, 100].
- @param percentile
A percentile value in the range (0, 100].
Resets the collected histogram data.
interface MarkOptions
interface MeasureOptions
interface NodeGCPerformanceDetail
- readonly flags: number
When
performanceEntry.entryTypeis equal to 'gc', theperformance.flagsproperty contains additional information about garbage collection operation. See perf_hooks.constants for valid values. - readonly kind: number
When
performanceEntry.entryTypeis equal to 'gc', theperformance.kindproperty identifies the type of garbage collection operation that occurred. See perf_hooks.constants for valid values.
interface Performance
- eventLoopUtilization: EventLoopUtilityFunction
eventLoopUtilization is similar to CPU utilization except that it is calculated using high precision wall-clock time. 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.
- readonly nodeTiming: PerformanceNodeTiming
This property is an extension by Node.js. It is not available in Web browsers.
An instance of the
PerformanceNodeTimingclass that provides performance metrics for specific Node.js operational milestones. - readonly timeOrigin: number
The
timeOriginspecifies the high resolution millisecond timestamp at which the currentnodeprocess began, measured in Unix time. - name?: string): void;
If
nameis not provided, removes allPerformanceMarkobjects from the Performance Timeline. Ifnameis provided, removes only the named mark. - name?: string): void;
If
nameis not provided, removes allPerformanceMeasureobjects from the Performance Timeline. Ifnameis provided, removes only the named measure. - name?: string): void;
If
nameis not provided, removes allPerformanceResourceTimingobjects from the Resource Timeline. Ifnameis provided, removes only the named resource. Returns a list of
PerformanceEntryobjects in chronological order with respect toperformanceEntry.startTime. If you are only interested in performance entries of certain types or that have certain names, seeperformance.getEntriesByType()andperformance.getEntriesByName().- name: string,
Returns a list of
PerformanceEntryobjects in chronological order with respect toperformanceEntry.startTimewhoseperformanceEntry.nameis equal toname, and optionally, whoseperformanceEntry.entryTypeis equal totype. Returns a list of
PerformanceEntryobjects in chronological order with respect toperformanceEntry.startTimewhoseperformanceEntry.entryTypeis equal totype.- mark(name: string,
Creates a new
PerformanceMarkentry in the Performance Timeline. APerformanceMarkis a subclass ofPerformanceEntrywhoseperformanceEntry.entryTypeis always'mark', and whoseperformanceEntry.durationis always0. Performance marks are used to mark specific significant moments in the Performance Timeline.The created
PerformanceMarkentry is put in the global Performance Timeline and can be queried withperformance.getEntries,performance.getEntriesByName, andperformance.getEntriesByType. When the observation is performed, the entries should be cleared from the global Performance Timeline manually withperformance.clearMarks. - timingInfo: object,requestedUrl: string,initiatorType: string,global: object,cacheMode: '' | 'local',bodyInfo: object,responseStatus: number,deliveryType?: string
Creates a new
PerformanceResourceTimingentry in the Resource Timeline. APerformanceResourceTimingis a subclass ofPerformanceEntrywhoseperformanceEntry.entryTypeis always'resource'. Performance resources are used to mark moments in the Resource Timeline.@param timingInfo@param requestedUrlThe resource url
@param initiatorTypeThe initiator name, e.g: 'fetch'
@param cacheModeThe cache mode must be an empty string ('') or 'local'
@param bodyInfo@param responseStatusThe response's status code
@param deliveryTypeThe delivery type. Default: ''.
- name: string,startMark?: string,endMark?: string
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 the Performance Timeline, or may identify any of the timestamp properties provided by the PerformanceNodeTiming class. If the named startMark does not exist, then startMark is set to timeOrigin by default.
The endMark argument must identify any existing PerformanceMark in the the Performance Timeline or any of the timestamp properties provided by the PerformanceNodeTiming class. If the named endMark does not exist, an error will be thrown.
@returnsThe PerformanceMeasure entry that was created
Returns the current high resolution millisecond timestamp, where 0 represents the start of the current
nodeprocess.- maxSize: number): void;
Sets the global performance resource timing buffer size to the specified number of "resource" type performance entry objects.
By default the max buffer size is set to 250.
- fn: T,): T;
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
PerformanceObservermust be subscribed to the'function'event type in order for the timing details to be accessed.import { performance, PerformanceObserver, } from 'node:perf_hooks'; function someFunction() { console.log('hello world'); } const wrapped = performance.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();If the wrapped function returns a promise, a finally handler will be attached to the promise and the duration will be reported once the finally handler is invoked.
An object which is JSON representation of the performance object. It is similar to
window.performance.toJSONin browsers.
interface RecordableHistogram
- 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 percentiles: Map<number, number>
Returns a
Mapobject detailing the accumulated percentile distribution. - readonly percentilesBigInt: Map<bigint, bigint>
Returns a
Mapobject detailing the accumulated percentile distribution. - @param percentile
A percentile value in the range (0, 100].
- @param percentile
A percentile value in the range (0, 100].
- @param val
The amount to record in the histogram.
Calculates the amount of time (in nanoseconds) that has passed since the previous call to
recordDelta()and records that amount in the histogram.Resets the collected histogram data.
interface TimerifyOptions
- histogram?: RecordableHistogram
A histogram object created using
perf_hooks.createHistogram()that will record runtime durations in nanoseconds.
interface UVMetrics
- readonly eventsWaiting: number
Number of events that were waiting to be processed when the event provider was called.
- type EntryType = 'dns' | 'function' | 'gc' | 'http2' | 'http' | 'mark' | 'measure' | 'net' | 'node' | 'resource'
- type EventLoopUtilityFunction = (utilization1?: EventLoopUtilization, utilization2?: EventLoopUtilization) => EventLoopUtilization
- type PerformanceObserverCallback = (list: PerformanceObserverEntryList, observer: PerformanceObserver) => void