Node.js v18.18.0 文档

perf_hooks.performance#

可用于从当前 Node.js 实例收集性能指标的对象。 类似于浏览器中的 window.performance。

英An object that can be used to collect performance metrics from the current Node.js instance. It is similar to window.performance in browsers.

performance.clearMarks([name])#

• name <string>

如果未提供 name，则从性能时间轴中删除所有 PerformanceMark 对象。 如果提供了 name，则仅删除命名标记。

英If name is not provided, removes all PerformanceMark objects from the Performance Timeline. If name is provided, removes only the named mark.

performance.clearMeasures([name])#

• name <string>

如果未提供 name，则从性能时间轴中删除所有 PerformanceMeasure 对象。 如果提供了 name，则只删除指定的测量。

英If name is not provided, removes all PerformanceMeasure objects from the Performance Timeline. If name is provided, removes only the named measure.

performance.clearResourceTimings([name])#

• name <string>

如果未提供 name，则从资源时间线中删除所有 PerformanceResourceTiming 对象。 如果提供了 name，则只删除指定的资源。

英If name is not provided, removes all PerformanceResourceTiming objects from the Resource Timeline. If name is provided, removes only the named resource.

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

• utilization1 <Object> 上一次调用 eventLoopUtilization() 的结果。
• utilization2 <Object> 在 utilization1 之前调用 eventLoopUtilization() 的结果。
• 返回 <Object>
  • idle <number>
  • active <number>
  • utilization <number>

eventLoopUtilization() 方法返回包含事件循环作为高解析度毫秒计时器的既空闲又活动的累积持续时间的对象。 utilization 值是计算的事件循环利用率 (ELU)。

英The eventLoopUtilization() method 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).

如果主线程上的引导尚未完成，则属性的值为 0。 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.

utilization1 和 utilization2 都是可选参数。

英Both utilization1 and utilization2 are optional parameters.

如果传入了 utilization1，则计算当前调用的 active 和 idle 之间的差值，以及对应的 utilization 值(类似于 process.hrtime())。

英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()).

如果传入了 utilization1 和 utilization2，则计算两个参数之间的增量。 这是便捷的选项，因为与 process.hrtime() 不同，计算 ELU 比单个减法更复杂。

英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 类似于 CPU 使用率，不同之处在于它只测量事件循环统计信息而不是 CPU 使用率。 它表示事件循环在事件循环的事件提供者（例如 epoll_wait）之外花费的时间百分比。 不考虑其他 CPU 空闲时间。 以下是主要空闲进程如何具有高 ELU 的示例。

英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.

'use strict';
const { eventLoopUtilization } = require('node:perf_hooks').performance;
const { spawnSync } = require('node:child_process');

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

虽然运行这个脚本时 CPU 大部分是空闲的，但 utilization 的值为 1。 这是因为对 child_process.spawnSync() 的调用阻止了事件循环的进行。

英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.

传入用户定义的对象而不是先前调用 eventLoopUtilization() 的结果将导致未定义的行为。 不保证返回值反映事件循环的任何正确状态。

英Passing in a user-defined object instead of the result of a previous call to eventLoopUtilization() will lead to undefined behavior. The return values are not guaranteed to reflect any correct state of the event loop.

performance.getEntries()#

• 返回： <PerformanceEntry[]>

返回 PerformanceEntry 对象的列表，按照相对于 performanceEntry.startTime 的时间顺序排列。 如果你只对某些类型或具有某些名称的性能条目感兴趣，则参阅 performance.getEntriesByType() 和 performance.getEntriesByName()。

英Returns a list of PerformanceEntry objects in chronological order with respect to performanceEntry.startTime. If you are only interested in performance entries of certain types or that have certain names, see performance.getEntriesByType() and performance.getEntriesByName().

performance.getEntriesByName(name[, type])#

• name <string>
• type <string>
• 返回： <PerformanceEntry[]>

返回按时间顺序的 PerformanceEntry 对象列表，其中 performanceEntry.startTime 的 performanceEntry.name 等于 name，并且可选地，其 performanceEntry.entryType 等于 type。

英Returns a list of PerformanceEntry objects in chronological order with respect to performanceEntry.startTime whose performanceEntry.name is equal to name, and optionally, whose performanceEntry.entryType is equal to type.

performance.getEntriesByType(type)#

• type <string>
• 返回： <PerformanceEntry[]>

返回按时间顺序排列的 PerformanceEntry 对象列表，其中 performanceEntry.startTime 的 performanceEntry.entryType 等于 type。

英Returns a list of PerformanceEntry objects in chronological order with respect to performanceEntry.startTime whose performanceEntry.entryType is equal to type.

performance.mark([name[, options]])#

• name <string>
• options <Object>
  • detail <any> 包含在标记中的附加可选细节。
  • startTime <number> 用作标记时间的可选时间戳。 默认: performance.now()。

在性能时间轴中创建新的 PerformanceMark 条目。 PerformanceMark 是 PerformanceEntry 的子类，其 performanceEntry.entryType 始终为 'mark'，而其 performanceEntry.duration 始终为 0。 性能标记用于标记性能时间轴中的特定重要时刻。

英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.

创建的 PerformanceMark 条目放入全局的性能时间轴，可以用 performance.getEntries、performance.getEntriesByName、performance.getEntriesByType 查询。 当执行观察时，应使用 performance.clearMarks 手动从全局的性能时间轴中清除条目。

英The created PerformanceMark entry is put in the global Performance Timeline and can be queried with performance.getEntries, performance.getEntriesByName, and performance.getEntriesByType. When the observation is performed, the entries should be cleared from the global Performance Timeline manually with performance.clearMarks.

performance.markResourceTiming(timingInfo, requestedUrl, initiatorType, global, cacheMode)#

• timingInfo <Object> 获取时间信息
• requestedUrl <string> 资源网址
• initiatorType <string> 启动器名称，例如： 'fetch'
• global <Object>
• cacheMode <string> 缓存模式必须为空字符串（''）或 'local'

此属性是 Node.js 的扩展。 它在 Web 浏览器中不可用。

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

在资源时间线中创建新的 PerformanceResourceTiming 条目。 PerformanceResourceTiming 是 PerformanceEntry 的子类，其 performanceEntry.entryType 始终是 'resource'。 性能资源用于在资源时间线中标记时刻。

英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.

创建的 PerformanceMark 条目放入全局资源时间线，可以使用 performance.getEntries、performance.getEntriesByName、performance.getEntriesByType 查询。 当执行观察时，应使用 performance.clearResourceTimings 手动从全局的性能时间轴中清除条目。

英The created PerformanceMark entry is put in the global Resource Timeline and can be queried with performance.getEntries, performance.getEntriesByName, and performance.getEntriesByType. When the observation is performed, the entries should be cleared from the global Performance Timeline manually with performance.clearResourceTimings.

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

• name <string>
• startMarkOrOptions <string> | <Object> 可选的。
  • detail <any> 要包含在度量中的其他可选细节。
  • duration <number> 开始和结束时间之间的持续时间。
  • end <number> | <string> 用作结束时间的时间戳，或标识先前记录标记的字符串。
  • start <number> | <string> 用作开始时间的时间戳，或标识先前记录标记的字符串。
• endMark <string> 可选的。 如果 startMarkOrOptions 是 <Object>，则必须省略。

在性能时间轴中创建新的 PerformanceMeasure 条目。 PerformanceMeasure 是 PerformanceEntry 的子类，其 performanceEntry.entryType 始终为 'measure'，其 performanceEntry.duration 测量自 startMark 和 endMark 以来经过的毫秒数。

英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.

startMark 参数可以标识性能时间线中任何现有的 PerformanceMark，或者可以标识 PerformanceNodeTiming 类提供的任何时间戳属性。 如果指定的 startMark 不存在，则抛出错误。

英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.

可选的 endMark 参数必须标识性能时间线中的任何现有 PerformanceMark 或 PerformanceNodeTiming 类提供的任何时间戳属性。 不传入参数则 endMark 为 performance.now()，否则如果命名的 endMark 不存在，则抛出错误。

英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.

创建的 PerformanceMeasure 条目放入全局的性能时间轴，可以用 performance.getEntries、performance.getEntriesByName、performance.getEntriesByType 查询。 当执行观察时，应使用 performance.clearMeasures 手动从全局的性能时间轴中清除条目。

英The created PerformanceMeasure entry is put in the global Performance Timeline and can be queried with performance.getEntries, performance.getEntriesByName, and performance.getEntriesByType. When the observation is performed, the entries should be cleared from the global Performance Timeline manually with performance.clearMeasures.

performance.nodeTiming#

• <PerformanceNodeTiming>

此属性是 Node.js 的扩展。 它在 Web 浏览器中不可用。

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

PerformanceNodeTiming 类的实例，为特定的 Node.js 操作里程碑提供性能指标。

英An instance of the PerformanceNodeTiming class that provides performance metrics for specific Node.js operational milestones.

performance.now()#

• 返回： <number>

返回当前的高解析度毫秒时间戳，其中 0 表示当前的 node 进程的开始。

英Returns the current high resolution millisecond timestamp, where 0 represents the start of the current node process.

performance.setResourceTimingBufferSize(maxSize)#

将全局性能资源定时缓冲区大小设置为指定数量的 "resource" 类型性能条目对象。

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

默认情况下，最大缓冲区大小设置为 250。

英By default the max buffer size is set to 250.

performance.timeOrigin#

• <number>

timeOrigin 指定了当前的 node 进程开始的高解析度毫秒时间戳，以 Unix 时间度量。

英The timeOrigin specifies the high resolution millisecond timestamp at which the current node process began, measured in Unix time.

performance.timerify(fn[, options])#

• fn <Function>
• options <Object>
  • histogram <RecordableHistogram> 使用 perf_hooks.createHistogram() 创建的直方图对象，以纳秒为单位记录运行时间。

此属性是 Node.js 的扩展。 它在 Web 浏览器中不可用。

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

将函数封装在测量被封装函数运行时间的新函数中。 PerformanceObserver 必须订阅 'function' 事件类型才能访问时间细节。

英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.

const {
  performance,
  PerformanceObserver,
} = require('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(); 拷贝

如果封装的函数返回 promise，则 finally 句柄将绑定到该 promise 上，并且一旦调用 finally 句柄就会报告持续时间。

英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.

performance.toJSON()#

performance 对象的 JSON 表示的对象。 类似于浏览器中的 window.performance.toJSON。

英An object which is JSON representation of the performance object. It is similar to window.performance.toJSON in browsers.

事件：'resourcetimingbufferfull'#

当全局性能资源计时缓冲区已满时会触发 'resourcetimingbufferfull' 事件。 使用 performance.setResourceTimingBufferSize() 调整资源计时缓冲区大小或在事件监听器中使用 performance.clearResourceTimings() 清除缓冲区，以允许将更多条目添加到性能时间线缓冲区。

英The 'resourcetimingbufferfull' event is fired when the global performance resource timing buffer is full. Adjust resource timing buffer size with performance.setResourceTimingBufferSize() or clear the buffer with performance.clearResourceTimings() in the event listener to allow more entries to be added to the performance timeline buffer.

类：PerformanceEntry#

performanceEntry.detail#

• <any>

entryType 特有的附加细节。

英Additional detail specific to the entryType.

performanceEntry.duration#

• <number>

此条目经过的总毫秒数。 此值对所有性能条目类型都没有意义。

英The total number of milliseconds elapsed for this entry. This value will not be meaningful for all Performance Entry types.

performanceEntry.entryType#

• <string>

性能条目的类型。 它可能是以下之一：

英The type of the performance entry. It may be one of:

• 'node' （仅限 Node.js）
• 'mark' （在网络上可用）
• 'measure' （在网络上可用）
• 'gc' （仅限 Node.js）
• 'function' （仅限 Node.js）
• 'http2' （仅限 Node.js）
• 'http' （仅限 Node.js）

performanceEntry.flags#

• <number>

此属性是 Node.js 的扩展。 它在 Web 浏览器中不可用。

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

当 performanceEntry.entryType 等于 'gc' 时，则 performance.flags 属性包含有关垃圾收集操作的附加信息。 该值可能是以下之一：

英When performanceEntry.entryType is equal to 'gc', the performance.flags property contains additional information about garbage collection operation. The value may be 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

performanceEntry.name#

• <string>

性能条目的名称。

英The name of the performance entry.

performanceEntry.kind#

• <number>

此属性是 Node.js 的扩展。 它在 Web 浏览器中不可用。

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

当 performanceEntry.entryType 等于 'gc' 时，则 performance.kind 属性标识发生的垃圾收集操作的类型。 该值可能是以下之一：

英When performanceEntry.entryType is equal to 'gc', the performance.kind property identifies the type of garbage collection operation that occurred. The value may be one of:

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

performanceEntry.startTime#

• <number>

标记性能条目开始时间的高解析度毫秒时间戳。

英The high resolution millisecond timestamp marking the starting time of the Performance Entry.

垃圾收集 ('gc') 详细信息#

当 performanceEntry.type 等于 'gc' 时，则 performanceEntry.detail 属性将是具有两个属性的 <Object>：

英When performanceEntry.type is equal to 'gc', the performanceEntry.detail property will be an <Object> with two properties:

• kind <number> 其中之一：
  • perf_hooks.constants.NODE_PERFORMANCE_GC_MAJOR
  • perf_hooks.constants.NODE_PERFORMANCE_GC_MINOR
  • perf_hooks.constants.NODE_PERFORMANCE_GC_INCREMENTAL
  • perf_hooks.constants.NODE_PERFORMANCE_GC_WEAKCB
• flags <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

HTTP ('http') 详细信息#

当 performanceEntry.type 等于 'http' 时，则 performanceEntry.detail 属性将是一个包含额外信息的 <Object>。

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

如果 performanceEntry.name 等于 HttpClient，则 detail 将包含以下属性： req，res。 而 req 属性将是包含 method、url、headers 的 <Object>，res 属性将是包含 statusCode、statusMessage、headers 的 <Object>。

英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.

如果 performanceEntry.name 等于 HttpRequest，则 detail 将包含以下属性： req，res。 而 req 属性将是包含 method、url、headers 的 <Object>，res 属性将是包含 statusCode、statusMessage、headers 的 <Object>。

英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.

这可能会增加额外的内存开销，并且只能用于诊断目的，而不是默认情况下在生产中打开。

英This could add additional memory overhead and should only be used for diagnostic purposes, not left turned on in production by default.

HTTP/2 ('http2') 详细信息#

当 performanceEntry.type 等于 'http2' 时，则 performanceEntry.detail 属性将是包含附加性能信息的 <Object>。

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

如果 performanceEntry.name 等于 Http2Stream，则 detail 将包含以下属性：

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

• bytesRead <number> 为此 Http2Stream 接收的 DATA 帧字节数。
• bytesWritten <number> 为此 Http2Stream 发送的 DATA 帧字节数。
• id <number> 关联 Http2Stream 的标识符
• timeToFirstByte <number> 从 PerformanceEntry startTime 到接收到第一个 DATA 帧之间经过的毫秒数。
• timeToFirstByteSent <number> 从 PerformanceEntry startTime 到发送的第一个 DATA 帧之间经过的毫秒数。
• timeToFirstHeader <number> 从 PerformanceEntry startTime 到接收到第一个标头之间经过的毫秒数。

如果 performanceEntry.name 等于 Http2Session，则 detail 将包含以下属性：

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

• bytesRead <number> 为此 Http2Session 接收的字节数。
• bytesWritten <number> 为此 Http2Session 发送的字节数。
• framesReceived <number> Http2Session 接收到的 HTTP/2 帧数。
• framesSent <number> Http2Session 发送的 HTTP/2 帧数。
• maxConcurrentStreams <number> Http2Session 生命周期内同时打开的最大流数。
• pingRTT <number> 从发送 PING 帧到接收到它的确认所经过的毫秒数。 只有在 Http2Session 上发送了 PING 帧时才会出现。
• streamAverageDuration <number> 所有 Http2Stream 实例的平均持续时间（以毫秒为单位）
• streamCount <number> Http2Session 处理的 Http2Stream 实例的数量。
• type <string> 'server' 或 'client' 来标识 Http2Session 的类型。

Timerify ('function') 详细信息#

当 performanceEntry.type 等于 'function' 时，则 performanceEntry.detail 属性将是列出计时函数的输入参数的 <Array>。

英When performanceEntry.type is equal to 'function', the performanceEntry.detail property will be an <Array> listing the input arguments to the timed function.

网络（'net'）详细信息#

当 performanceEntry.type 等于 'net' 时，则 performanceEntry.detail 属性将是一个包含额外信息的 <Object>。

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

如果 performanceEntry.name 等于 connect，则 detail 将包含以下属性： host，port。

英If performanceEntry.name is equal to connect, the detail will contain the following properties: host, port.

DNS ('dns') 详细信息#

当 performanceEntry.type 等于 'dns' 时，则 performanceEntry.detail 属性将是一个包含额外信息的 <Object>。

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

如果 performanceEntry.name 等于 lookup，则 detail 将包含以下属性： hostname、family、hints、verbatim、addresses。

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

如果 performanceEntry.name 等于 lookupService，则 detail 将包含以下属性： host、port、hostname、service。

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

如果 performanceEntry.name 等于 queryxxx 或 getHostByAddr，则 detail 将包含以下属性： host、ttl、result。 result 的值与 queryxxx 或 getHostByAddr 的结果相同。

英If performanceEntry.name is equal to queryxxx or getHostByAddr, the detail will contain the following properties: host, ttl, result. The value of result is same as the result of queryxxx or getHostByAddr.

类：PerformanceNodeTiming#

• 继承： <PerformanceEntry>

此属性是 Node.js 的扩展。 它在 Web 浏览器中不可用。

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

为 Node.js 本身提供计时细节。 此类的构造函数不会暴露给用户。

英Provides timing details for Node.js itself. The constructor of this class is not exposed to users.

performanceNodeTiming.bootstrapComplete#

• <number>

Node.js 进程完成引导的高解析度毫秒时间戳。 如果引导尚未完成，则该属性的值为 -1。

英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.

performanceNodeTiming.environment#

• <number>

Node.js 环境初始化的高解析度毫秒时间戳。

英The high resolution millisecond timestamp at which the Node.js environment was initialized.

performanceNodeTiming.idleTime#

• <number>

事件循环在事件循环的事件提供者（例如 epoll_wait）中空闲的时间量的高解析度毫秒时间戳。 这不考虑 CPU 使用率。 如果事件循环尚未开始（例如，在主脚本的第一个滴答中），则该属性的值为 0。

英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.

performanceNodeTiming.loopExit#

• <number>

Node.js 事件循环退出时的高解析度毫秒时间戳。 如果事件循环尚未退出，则该属性的值为 -1。 它只能在 'exit' 事件的句柄中具有非 -1 的值。

英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.

performanceNodeTiming.loopStart#

• <number>

Node.js 事件循环开始的高解析度毫秒时间戳。 如果事件循环尚未开始（例如，在主脚本的第一个滴答中），则该属性的值为 -1。

英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.

performanceNodeTiming.nodeStart#

• <number>

Node.js 进程初始化的高解析度毫秒时间戳。

英The high resolution millisecond timestamp at which the Node.js process was initialized.

performanceNodeTiming.v8Start#

• <number>

V8 平台初始化的高解析度毫秒时间戳。

英The high resolution millisecond timestamp at which the V8 platform was initialized.

类：PerformanceResourceTiming#

• 继承： <PerformanceEntry>

提供有关应用资源加载的详细网络计时数据。

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

此类的构造函数不直接暴露给用户。

英The constructor of this class is not exposed to users directly.

performanceResourceTiming.workerStart#

• <number>

即将发送 fetch 请求之前的高解析度毫秒时间戳。 如果资源没有被工作进程截获，该属性将始终返回 0。

英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.

performanceResourceTiming.redirectStart#

• <number>

表示启动重定向的获取的开始时间的高解析度毫秒时间戳。

英The high resolution millisecond timestamp that represents the start time of the fetch which initiates the redirect.

performanceResourceTiming.redirectEnd#

• <number>

接收到最后一个重定向响应的最后一个字节后立即创建的高解析度毫秒时间戳。

英The high resolution millisecond timestamp that will be created immediately after receiving the last byte of the response of the last redirect.

performanceResourceTiming.fetchStart#

• <number>

Node.js 开始获取资源之前的高解析度毫秒时间戳。

英The high resolution millisecond timestamp immediately before the Node.js starts to fetch the resource.

performanceResourceTiming.domainLookupStart#

• <number>

Node.js 开始查找资源之前的高解析度毫秒时间戳。

英The high resolution millisecond timestamp immediately before the Node.js starts the domain name lookup for the resource.

performanceResourceTiming.domainLookupEnd#

• <number>

表示 Node.js 完成对资源的域名查找之后的时间高解析度毫秒时间戳。

英The high resolution millisecond timestamp representing the time immediately after the Node.js finished the domain name lookup for the resource.

performanceResourceTiming.connectStart#

• <number>

表示 Node.js 开始与服务器建立连接以检索资源之前的时间的高解析度毫秒时间戳。

英The high resolution millisecond timestamp representing the time immediately before Node.js starts to establish the connection to the server to retrieve the resource.

performanceResourceTiming.connectEnd#

• <number>

表示 Node.js 完成与服务器建立连接以检索资源后的时间的高解析度毫秒时间戳。

英The high resolution millisecond timestamp representing the time immediately after Node.js finishes establishing the connection to the server to retrieve the resource.

performanceResourceTiming.secureConnectionStart#

• <number>

表示 Node.js 开始握手过程以保护当前连接之前的时间的高解析度毫秒时间戳。

英The high resolution millisecond timestamp representing the time immediately before Node.js starts the handshake process to secure the current connection.

performanceResourceTiming.requestStart#

• <number>

表示 Node.js 从服务器接收到响应的第一个字节之前的时间的高解析度毫秒时间戳。

英The high resolution millisecond timestamp representing the time immediately before Node.js receives the first byte of the response from the server.

performanceResourceTiming.responseEnd#

• <number>

表示 Node.js 接收到资源的最后一个字节之后或传输连接关闭之前的时间（以先到者为准）的高解析度毫秒时间戳。

英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.

performanceResourceTiming.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.

performanceResourceTiming.encodedBodySize#

• <number>

表示在删除任何应用的内容编码之前从有效负载主体的提取（HTTP 或缓存）接收到的大小（以八位字节为单位）的数值。

英A number representing the size (in octets) received from the fetch (HTTP or cache), of the payload body, before removing any applied content-codings.

performanceResourceTiming.decodedBodySize#

• <number>

表示在删除任何应用的内容编码后，从消息主体的提取（HTTP 或缓存）接收到的大小（以八位字节为单位）的数值。

英A number representing the size (in octets) received from the fetch (HTTP or cache), of the message body, after removing any applied content-codings.

performanceResourceTiming.toJSON()#

返回 object，其是 PerformanceResourceTiming 对象的 JSON 表示形式

英Returns a object that is the JSON representation of the PerformanceResourceTiming object

类：perf_hooks.PerformanceObserver#

PerformanceObserver.supportedEntryTypes#

• <string[]>

获取支持的类型。

英Get supported types.

new PerformanceObserver(callback)#

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

当新的 PerformanceEntry 实例被添加到性能时间线时，则 PerformanceObserver 对象会提供通知。

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

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'); 拷贝

因为 PerformanceObserver 实例引入了它们自己的额外性能开销，实例不应无限期地订阅通知。 一旦不再需要观察者，则用户应立即断开观察者的连接。

英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 接收到有关新的 PerformanceEntry 实例的通知时，则会调用 callback。 回调接收到 PerformanceObserverEntryList 实例和对 PerformanceObserver 的引用。

英The callback is invoked when a PerformanceObserver is notified about new PerformanceEntry instances. The callback receives a PerformanceObserverEntryList instance and a reference to the PerformanceObserver.

performanceObserver.disconnect()#

断开 PerformanceObserver 实例与所有通知的连接。

英Disconnects the PerformanceObserver instance from all notifications.

performanceObserver.observe(options)#

• options <Object>
  • type <string> 单个 <PerformanceEntry> 类型。 如果已经指定了 entryTypes，则不能给出。
  • entryTypes <string[]> 标识观察者感兴趣的 <PerformanceEntry> 实例类型的字符串数组。 如果未提供，将抛出错误。
  • buffered <boolean> 如果为 true，则使用列表全局 PerformanceEntry 缓冲条目调用观察者回调。 如果为 false，则只有在该时间点之后创建的 PerformanceEntry 被发送到观察者回调。 默认值： false。

为 <PerformanceObserver> 实例订阅由 options.entryTypes 或 options.type 标识的新 <PerformanceEntry> 实例的通知：

英Subscribes the <PerformanceObserver> instance to notifications of new <PerformanceEntry> instances identified either by options.entryTypes or options.type:

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}`); 拷贝

类：PerformanceObserverEntryList#

PerformanceObserverEntryList 类用于提供对传给 PerformanceObserver 的 PerformanceEntry 实例的访问。 此类的构造函数不会暴露给用户。

英The PerformanceObserverEntryList class is used to provide access to the PerformanceEntry instances passed to a PerformanceObserver. The constructor of this class is not exposed to users.

performanceObserverEntryList.getEntries()#

• 返回： <PerformanceEntry[]>

返回 PerformanceEntry 对象的列表，按照相对于 performanceEntry.startTime 的时间顺序排列。

英Returns a list of PerformanceEntry objects in chronological order with respect to performanceEntry.startTime.

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
   *   },
   *   PerformanceEntry {
   *     name: 'meow',
   *     entryType: 'mark',
   *     startTime: 81.860064,
   *     duration: 0
   *   }
   * ]
   */

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

performance.mark('test');
performance.mark('meow'); 拷贝

performanceObserverEntryList.getEntriesByName(name[, type])#

• name <string>
• type <string>
• 返回： <PerformanceEntry[]>

返回按时间顺序的 PerformanceEntry 对象列表，其中 performanceEntry.startTime 的 performanceEntry.name 等于 name，并且可选地，其 performanceEntry.entryType 等于 type。

英Returns a list of PerformanceEntry objects in chronological order with respect to performanceEntry.startTime whose performanceEntry.name is equal to name, and optionally, whose performanceEntry.entryType is equal to type.

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
   *   }
   * ]
   */
  console.log(perfObserverList.getEntriesByName('nope')); // []

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

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

performance.mark('test');
performance.mark('meow'); 拷贝

performanceObserverEntryList.getEntriesByType(type)#

• type <string>
• 返回： <PerformanceEntry[]>

返回按时间顺序排列的 PerformanceEntry 对象列表，其中 performanceEntry.startTime 的 performanceEntry.entryType 等于 type。

英Returns a list of PerformanceEntry objects in chronological order with respect to performanceEntry.startTime whose performanceEntry.entryType is equal to type.

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
   *   },
   *   PerformanceEntry {
   *     name: 'meow',
   *     entryType: 'mark',
   *     startTime: 56.350146,
   *     duration: 0
   *   }
   * ]
   */
  performance.clearMarks();
  performance.clearMeasures();
  observer.disconnect();
});
obs.observe({ type: 'mark' });

performance.mark('test');
performance.mark('meow'); 拷贝

perf_hooks.createHistogram([options])#

• options <Object>
  • lowest <number> | <bigint> 最低可识别值。 必须是大于 0 的整数值。 默认值： 1。
  • highest <number> | <bigint> 最高可记录值。 必须是等于或大于 lowest 两倍的整数值。 默认值： Number.MAX_SAFE_INTEGER。
  • figures <number> 精度位数。 必须是 1 和 5 之间的数字。 默认值： 3。
• 返回 <RecordableHistogram>

返回 <RecordableHistogram>。

英Returns a <RecordableHistogram>.

perf_hooks.monitorEventLoopDelay([options])#

• options <Object>
  • resolution <number> 以毫秒为单位的采样率。 必须大于零。 默认值： 10。
• 返回： <IntervalHistogram>

此属性是 Node.js 的扩展。 它在 Web 浏览器中不可用。

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

创建可随时间采样并报告事件循环延迟的 IntervalHistogram 对象。 延迟将以纳秒为单位报告。

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

使用计时器来检测近似的事件循环延迟是有效的，因为计时器的执行与 libuv 事件循环的生命周期特别相关。 也就是说，循环中的延迟会导致计时器执行的延迟，而这些延迟正是此 API 旨在检测的。

英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.

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)); 拷贝

类：Histogram#

histogram.count#

• <number>

直方图记录的样本数。

英The number of samples recorded by the histogram.

histogram.countBigInt#

• <bigint>

直方图记录的样本数。

英The number of samples recorded by the histogram.

histogram.exceeds#

• <number>

事件循环延迟超过最大 1 小时事件循环延迟阈值的次数。

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

histogram.exceedsBigInt#

• <bigint>

事件循环延迟超过最大 1 小时事件循环延迟阈值的次数。

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

histogram.max#

• <number>

记录的事件循环延迟的最大值。

英The maximum recorded event loop delay.

histogram.maxBigInt#

• <bigint>

记录的事件循环延迟的最大值。

英The maximum recorded event loop delay.

histogram.mean#

• <number>

记录的事件循环延迟的平均值。

英The mean of the recorded event loop delays.

histogram.min#

• <number>

记录的事件循环延迟的最小值。

英The minimum recorded event loop delay.

histogram.minBigInt#

• <bigint>

记录的事件循环延迟的最小值。

英The minimum recorded event loop delay.

histogram.percentile(percentile)#

• percentile <number> 百分位值的范围是 (0, 100]。
• 返回：<number>

返回给定的百分位数的值。

英Returns the value at the given percentile.

histogram.percentileBigInt(percentile)#

• percentile <number> 百分位值的范围是 (0, 100]。
• 返回：<bigint>

返回给定的百分位数的值。

英Returns the value at the given percentile.

histogram.percentiles#

• <Map>

返回详细说明累积的百分位分布的 Map 对象。

英Returns a Map object detailing the accumulated percentile distribution.

histogram.percentilesBigInt#

• <Map>

返回详细说明累积的百分位分布的 Map 对象。

英Returns a Map object detailing the accumulated percentile distribution.

histogram.reset()#

重置收集的直方图数据。

英Resets the collected histogram data.

histogram.stddev#

• <number>

记录的事件循环延迟的标准偏差。

英The standard deviation of the recorded event loop delays.

类：IntervalHistogram extends Histogram#

在给定的时间间隔内定期更新的 Histogram。

英A Histogram that is periodically updated on a given interval.

histogram.disable()#

• 返回：<boolean>

禁用更新间隔计时器。 如果计时器已停止，则返回 true，如果已停止，则返回 false。

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

histogram.enable()#

• 返回：<boolean>

启用更新间隔计时器。 如果计时器已启动，则返回 true，如果已经启动，则返回 false。

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

克隆 IntervalHistogram#

<IntervalHistogram> 可以通过 <MessagePort> 克隆实例。 在接收端，直方图被克隆为一个没有实现 enable() 和 disable() 方法的普通 <Histogram> 对象。

英<IntervalHistogram> instances can be cloned via <MessagePort>. On the receiving end, the histogram is cloned as a plain <Histogram> object that does not implement the enable() and disable() methods.

类：RecordableHistogram extends Histogram#

histogram.add(other)#

• other <RecordableHistogram>

将 other 中的值添加到此直方图中。

英Adds the values from other to this histogram.

histogram.record(val)#

• val <number> | <bigint> 在直方图中记录的数量。

histogram.recordDelta()#

计算自上次调用 recordDelta() 以来经过的时间量（以纳秒为单位），并在直方图中记录该量。

英Calculates the amount of time (in nanoseconds) that has passed since the previous call to recordDelta() and records that amount in the histogram.

示例#

测量异步操作的持续时间#

以下示例使用 异步钩子 和性能 API 来测量超时操作的实际持续时间（包括执行回调所花费的时间量）。

英The following example uses the Async Hooks and Performance APIs to measure the actual duration of a Timeout operation (including the amount of time it took to execute the callback).

'use strict';
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'], buffered: true });

setTimeout(() => {}, 1000); 拷贝

测量加载依赖需要多长时间#

以下示例测量加载依赖的 require() 操作的持续时间：

英The following example measures the duration of require() operations to load dependencies:

'use strict';
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'], buffered: true });

require('some-module'); 拷贝

测量一次 HTTP 往返需要多长时间#

以下示例用于跟踪 HTTP 客户端 (OutgoingMessage) 和 HTTP 请求 (IncomingMessage) 花费的时间。 对于 HTTP 客户端，是指发起请求到收到响应的时间间隔，对于 HTTP 请求，是指从接收请求到发送响应的时间间隔：

英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:

'use strict';
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}`);
}); 拷贝

测量连接成功时 net.connect（只针对 TCP）需要多长时间#

'use strict';
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);
}); 拷贝

测量请求成功时 DNS 花费的时间#

'use strict';
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'); 拷贝