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
Basic performance measurement works. Missing histogram creation and 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_info
function. It returns the current set of event loop metrics.It is recommended to use this property inside a function whose execution was scheduled using
setImmediate
to 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
asyncId
assigned 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
PerformanceObserver
instance from all notifications.Call all
destroy
hooks. 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 thedestroy
hooks will never be called.@returnsA reference to
asyncResource
.- options: { buffered: boolean; entryTypes: readonly EntryType[] } | { buffered: boolean; type: EntryType }): void;
Subscribes the
PerformanceObserver
instance to notifications of newPerformanceEntry
instances identified either byoptions.entryTypes
oroptions.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
triggerAsyncId
that is passed to theAsyncResource
constructor. - 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
PerformanceEntry
objects 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
PerformanceEntry
objects in chronological order with respect toperformanceEntry.startTime
whoseperformanceEntry.name
is equal toname
, and optionally, whoseperformanceEntry.entryType
is 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
PerformanceEntry
objects in chronological order with respect toperformanceEntry.startTime
whoseperformanceEntry.entryType
is 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
fetch
request. If the resource is not intercepted by a worker the property will always return 0. Returns a
object
that is the JSON representation of thePerformanceResourceTiming
object
Returns a
RecordableHistogram
.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));
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
Map
object detailing the accumulated percentile distribution. - readonly percentilesBigInt: Map<bigint, bigint>
Returns a
Map
object 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
Map
object detailing the accumulated percentile distribution. - readonly percentilesBigInt: Map<bigint, bigint>
Returns a
Map
object detailing the accumulated percentile distribution. Disables the update interval timer. Returns
true
if the timer was stopped,false
if it was already stopped.Enables the update interval timer. Returns
true
if the timer was started,false
if 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.entryType
is equal to 'gc', theperformance.flags
property contains additional information about garbage collection operation. See perf_hooks.constants for valid values. - readonly kind?: number
When
performanceEntry.entryType
is equal to 'gc', theperformance.kind
property 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
PerformanceNodeTiming
class that provides performance metrics for specific Node.js operational milestones. - readonly timeOrigin: number
The
timeOrigin
specifies the high resolution millisecond timestamp at which the currentnode
process began, measured in Unix time. - name?: string): void;
If
name
is not provided, removes allPerformanceMark
objects from the Performance Timeline. Ifname
is provided, removes only the named mark. - name?: string): void;
If
name
is not provided, removes allPerformanceMeasure
objects from the Performance Timeline. Ifname
is provided, removes only the named measure. - name?: string): void;
If
name
is not provided, removes allPerformanceResourceTiming
objects from the Resource Timeline. Ifname
is provided, removes only the named resource. Returns a list of
PerformanceEntry
objects 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
PerformanceEntry
objects in chronological order with respect toperformanceEntry.startTime
whoseperformanceEntry.name
is equal toname
, and optionally, whoseperformanceEntry.entryType
is equal totype
. Returns a list of
PerformanceEntry
objects in chronological order with respect toperformanceEntry.startTime
whoseperformanceEntry.entryType
is equal totype
.- mark(name: string,
Creates a new
PerformanceMark
entry in the Performance Timeline. APerformanceMark
is a subclass ofPerformanceEntry
whoseperformanceEntry.entryType
is always'mark'
, and whoseperformanceEntry.duration
is always0
. Performance marks are used to mark specific significant moments in the Performance Timeline.The created
PerformanceMark
entry 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
PerformanceResourceTiming
entry in the Resource Timeline. APerformanceResourceTiming
is a subclass ofPerformanceEntry
whoseperformanceEntry.entryType
is 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
node
process.- 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
PerformanceObserver
must 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.toJSON
in 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
Map
object detailing the accumulated percentile distribution. - readonly percentilesBigInt: Map<bigint, bigint>
Returns a
Map
object 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