性能测量 API

稳定性：2 - 稳定

此模块提供了 W3C Web Performance APIs 子集的实现，以及用于 Node.js 特定性能测量的其他 API。

Node.js 支持以下 Web Performance APIs：

• [高精度时间][]
• [性能时间线][]
• [用户计时][]
• [资源计时][]

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('从开始到现在');

performance.mark('A');
doSomeLongRunningProcess(() => {
  performance.measure('A 到现在', 'A');

  performance.mark('B');
  performance.measure('A 到 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('从开始到现在');

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

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

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

performance.clearMarks(name?): void

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

performance.clearMeasures(name?): void

如果未提供 name，则从性能时间线中移除所有 PerformanceMeasure 对象。如果提供了 name，则仅移除命名的测量。

performance.clearResourceTimings(name?): void

如果未提供 name，则从资源时间线中移除所有 PerformanceResourceTiming 对象。如果提供了 name，则仅移除命名的资源。

performance.eventLoopUtilization(utilization1?, utilization2?): void

这是 perf_hooks.eventLoopUtilization() 的别名。

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

performance.getEntries(): void

• 返回：PerformanceEntry[]

返回按 performanceEntry.startTime 时间顺序排列的 PerformanceEntry 对象列表。如果你只关心特定类型或具有特定名称的性能条目，请参阅 performance.getEntriesByType() 和 performance.getEntriesByName()。

performance.getEntriesByName(name, type?): void

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

performance.getEntriesByType(type): void

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

performance.mark(name, options?): void

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

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

performance.markResourceTiming(timingInfo, requestedUrl, initiatorType, global, cacheMode, bodyInfo, responseStatus, deliveryType?): void

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

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

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

performance.measure(name, startMarkOrOptions?, endMark?): void

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

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

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

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

• 类型：PerformanceNodeTiming

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

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

performance.now(): void

• 返回：number

返回当前高分辨率毫秒时间戳，其中 0 代表当前 node 进程的开始。

performance.setResourceTimingBufferSize(maxSize): void

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

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

• 类型：number

timeOrigin 指定当前 node 进程开始的高分辨率毫秒时间戳，以 Unix 时间测量。

performance.timerify(fn, options?): void

这是 perf_hooks.timerify() 的别名。

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

performance.toJSON(): void

一个对象，是 performance 对象的 JSON 表示。它类似于浏览器中的 window.performance.toJSON。

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

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

• 类型：number

该条目经过的总毫秒数。此值并不适用于所有性能条目类型。

• 类型：string

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

• 'dns'（仅 Node.js）
• 'function'（仅 Node.js）
• 'gc'（仅 Node.js）
• 'http2'（仅 Node.js）
• 'http'（仅 Node.js）
• 'mark'（Web 上可用）
• 'measure'（Web 上可用）
• 'net'（仅 Node.js）
• 'node'（仅 Node.js）
• 'resource'（Web 上可用）

• 类型：string

性能条目的名称。

• 类型：number

标记性能条目开始时间的高分辨率毫秒时间戳。

• 继承：PerformanceEntry

暴露通过 Performance.mark() 方法创建的标记。

• 类型：any

使用 Performance.mark() 方法创建时指定的附加详情。

• 继承：PerformanceEntry

暴露通过 Performance.measure() 方法创建的测量。

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

• 类型：any

使用 Performance.measure() 方法创建时指定的附加详情。

• 继承：PerformanceEntry

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

提供详细的 Node.js 计时数据。

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

• 类型：any

特定于 entryType 的附加详情。

稳定性：0 - 已弃用：请改用 performanceNodeEntry.detail。

• 类型：number

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

• 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

稳定性：0 - 已弃用：请改用 performanceNodeEntry.detail。

• 类型：number

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

• 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

当 performanceEntry.type 等于 'gc' 时，performanceNodeEntry.detail 属性将是一个包含两个属性的 Object：

当 performanceEntry.type 等于 'http' 时，performanceNodeEntry.detail 属性将是一个包含附加信息的 Object。

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

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

这可能会增加额外的内存开销，应仅用于诊断目的，默认情况下不应在生产环境中保持开启。

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

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

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

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

当 performanceEntry.type 等于 'net' 时，performanceNodeEntry.detail 属性将是一个包含附加信息的 Object。

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

当 performanceEntry.type 等于 'dns' 时，performanceNodeEntry.detail 属性将是一个包含附加信息的 Object。

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

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

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

• 继承：PerformanceEntry

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

提供 Node.js 本身的计时详情。此类的构造函数不向用户暴露。

• 类型：number

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

• 类型：number

Node.js 环境初始化的高分辨率毫秒时间戳。

• 类型：number

事件循环在其事件提供者（例如 epoll_wait）内处于空闲状态的时间量的高分辨率毫秒时间戳。这不考虑 CPU 使用情况。如果事件循环尚未启动（例如，在主脚本的第一个刻度中），则该属性的值为 0。

• 类型：number

Node.js 事件循环退出时的高分辨率毫秒时间戳。如果事件循环尚未退出，则该属性的值为 -1。它只能在 'exit' 事件的处理程序中具有非 -1 的值。

• 类型：number

Node.js 事件循环启动时的高分辨率毫秒时间戳。如果事件循环尚未启动（例如，在主脚本的第一个刻度中），则该属性的值为 -1。

• 类型：number

Node.js 进程初始化时的高分辨率毫秒时间戳。

• 类型：Object
  Attributes

  loopCount:number

  事件循环迭代次数。

  events:number

  事件处理程序已处理的事件数。

  eventsWaiting:number

  调用事件提供者时等待处理的事件数。

这是 uv_metrics_info 函数的包装器。 它返回当前的一组事件循环指标。

这些值在 Number.MAX_SAFE_INTEGER 范围内是精确的。使用 performanceNodeTiming.uvMetricsInfoBigInt 可获取 libuv 报告的完整 64 位 值。

建议在使用 setImmediate 调度执行的函数中使用此属性，以避免在完成当前循环迭代中调度的所有操作之前收集指标。

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

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

import { performance } from 'node:perf_hooks';

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

• 类型：Object
  Attributes

  loopCount:bigint

  事件循环迭代次数。

  events:bigint

  事件处理程序已处理的事件数。

  eventsWaiting:bigint

  调用事件提供者时等待处理的事件数。

与 performanceNodeTiming.uvMetricsInfo 相同，但这些值为 bigint，可携带 libuv 报告的完整 64 位范围。

由于 JSON.stringify() 无法序列化 bigint 值，此属性不可枚举，也不会包含在 performanceNodeTiming.toJSON() 的输出中。通过展开其可枚举属性创建的 performance.nodeTiming 副本，例如，仍可序列化。

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

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

import { performance } from 'node:perf_hooks';

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

• 类型：number

V8 平台初始化时的高分辨率毫秒时间戳。

• 继承：PerformanceEntry

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

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

• 类型：number

调度 fetch 请求之前立即的高分辨率毫秒时间戳。如果资源未被工作器拦截，则该属性将始终返回 0。

• 类型：number

表示发起重定向的 fetch 开始时间的高分辨率毫秒时间戳。

• 类型：number

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

• 类型：number

Node.js 开始获取资源之前立即的高分辨率毫秒时间戳。

• 类型：number

Node.js 开始资源的域名查找之前立即的高分辨率毫秒时间戳。

• 类型：number

表示 Node.js 完成资源的域名查找之后立即的时间的高分辨率毫秒时间戳。

• 类型：number

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

• 类型：number

表示 Node.js 完成建立与服务器的连接以检索资源之后立即的时间的高分辨率毫秒时间戳。

• 类型：number

表示 Node.js 开始握手过程以保护当前连接之前立即的时间的高分辨率毫秒时间戳。

• 类型：number

表示 Node.js 接收到来自服务器的响应的第一个字节之前立即的时间的高分辨率毫秒时间戳。

• 类型：number

表示 Node.js 接收到最终响应的第一个字节之后立即时间的高分辨率毫秒时间戳， 而非临时响应。

• 类型：number

表示 Node.js 接收到第一个临时响应（例如 103 Early Hints 响应）的第一个字节之后立即时间的高分辨率毫秒时间戳。

• 类型：number

表示 Node.js 接收到来自服务器的响应的第一个字节之后立即时间的高分辨率毫秒时间戳。当 firstInterimResponseStart 不为零时，该值为 firstInterimResponseStart；否则为 finalResponseHeadersStart。

• 类型：number

表示 Node.js 接收到资源的最后一个字节之后立即或传输连接关闭之前立即的时间的高分辨率毫秒时间戳，以先发生者为准。

• 类型：number

一个数字，表示获取的资源的大小（以八位字节为单位）。大小包括响应头字段加上响应负载主体。

• 类型：number

一个数字，表示从 fetch（HTTP 或缓存）接收的负载主体的大小（以八位字节为单位），在移除任何应用的内容编码之前。

• 类型：number

一个数字，表示从 fetch（HTTP 或缓存）接收的消息主体的大小（以八位字节为单位），在移除任何应用的内容编码之后。

• 类型：string

资源的渲染阻塞状态。可以是 'blocking' 或 'non-blocking'。

• 类型：string

获取的资源内容的最简化 MIME 类型；如果无法确定，则为空字符串。

• 类型：string

获取的资源的内容编码，例如 'gzip' 或 'br'。

performanceResourceTiming.toJSON(): void

返回一个 object，它是 PerformanceResourceTiming 对象的 JSON 表示。

• 类型：string[]

获取支持的类型。

new PerformanceObserver(callback): void

PerformanceObserver 对象在新的 PerformanceEntry 实例被添加到性能时间轴时提供通知。

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

因为 PerformanceObserver 实例会引入额外的性能开销，因此不应无限期地订阅通知。用户应在不再需要观察者时尽快断开连接。

当 PerformanceObserver 收到新的 PerformanceEntry 实例通知时，会调用 callback。回调接收一个 PerformanceObserverEntryList 实例和对 PerformanceObserver 的引用。

performanceObserver.disconnect(): void

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

performanceObserver.observe(options): void

订阅 PerformanceObserver 实例，以接收由 options.entryTypes 或 options.type 标识的新 PerformanceEntry 实例的通知：

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

const obs = new PerformanceObserver((list, observer) => {
  // 异步调用一次。`list` 包含三个项。
});
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) => {
  // 异步调用一次。`list` 包含三个项。
});
obs.observe({ type: 'mark' });

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

performanceObserver.takeRecords(): void

• 返回：PerformanceEntry[] 当前存储在性能观察者中的条目列表，并将其清空。

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

performanceObserverEntryList.getEntries(): void

• 返回：PerformanceEntry[]

返回一个 PerformanceEntry 对象列表，按照 performanceEntry.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');

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

performanceObserverEntryList.getEntriesByName(name, type?): void

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

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

performanceObserverEntryList.getEntriesByType(type): void

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

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

perf_hooks.createHistogram(options?): void

返回一个 RecordableHistogram。

perf_hooks.createSlidingWindowHistogram(options): void

创建一个 SlidingWindowHistogram，用于保留最新的 chunks 个直方图块。轮换采用惰性方式，不会创建计时器。基于时间的轮换会在调用 record() 或 snapshot() 时进行评估。基于计数的轮换会在调用 record() 时进行评估。

构造时会分配一个直方图块。其他块会按需分配。窗口使用的最大原生内存量取决于 chunks 以及直方图选项 lowest、highest 和 figures。

窗口边界的精度以块为单位。对于持续时间为 D 的 N 个块，记录的值会保留 (N - 1) * D 到 N * D 毫秒。基于计数的窗口填满后，会保留 (N - 1) * C + 1 到 N * C 次记录尝试，其中 C 为 recordsPerChunk。超出 highest 的记录尝试也会计入基于计数的轮换。

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

const window = createSlidingWindowHistogram({
  chunks: 6,
  chunkDuration: 10_000,
});

window.record(20_000_000);

// 将当前窗口物化为一个独立的 Histogram。
const snapshot = window.snapshot();
console.log(snapshot.percentile(99));

perf_hooks.importHistogram(data): void

从 CBOR 编码的 Uint8Array 重建直方图。返回的直方图是一个完整的 RecordableHistogram，已恢复所有桶数据、配置和 EWMA 状态。可以向其中记录新值。

可以导入由 histogram.export() 生成的任意格式版本的数据。详情请参阅[直方图导出格式兼容性][]。

const { createHistogram, importHistogram } = require('node:perf_hooks');

const h = createHistogram();
for (let i = 1; i <= 1000; i++) h.record(i);

// 序列化并重建
const data = h.export();
const h2 = importHistogram(data);

console.log(h2.count);          // 1000
console.log(h2.percentile(99)); // 与 h.percentile(99) 相同

perf_hooks.eventLoopUtilization(utilization1?, utilization2?): void

eventLoopUtilization() 函数返回一个对象，该对象包含事件循环处于空闲和活动状态的累计持续时间，作为高分辨率毫秒计时器。utilization 值是计算出的事件循环利用率（ELU）。

如果主线程上的引导尚未完成，则属性的值为 0。由于引导发生在事件循环内，因此 ELU 在[工作线程][]上立即可用。

utilization1 和 utilization2 都是可选参数。

如果传入了 utilization1，则会计算并返回当前调用的 active 和 idle 时间之间的差值，以及相应的 utilization 值（类似于 process.hrtime()）。

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

ELU 类似于 CPU 利用率，但它仅测量事件循环统计信息，而不是 CPU 使用情况。它表示事件循环花在事件循环的事件提供者（例如 epoll_wait）之外的时间百分比。不考虑其他 CPU 空闲时间。以下是一个大部分空闲的进程如何具有高 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);
});

虽然运行此脚本时 CPU 大部分处于空闲状态，但 utilization 的值为 1。这是因为对 child_process.spawnSync() 的调用阻止了事件循环继续执行。

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

perf_hooks.monitorEventLoopDelay(options?): void

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

创建一个直方图对象，用于随时间采样并报告事件循环延迟。 延迟将以纳秒为单位报告。

默认情况下，直方图会通过使用已配置的 resolution 的计时器进行更新。 当 samplePerIteration 为 true 时，样本会使用 uv_prepare_t 和 uv_check_t 钩子在每次事件循环迭代时采集一次。 在该模式下，直方图不会保持事件循环存活，也不会在应用空闲时强制额外迭代。 这两种采样模式产生的结果差异很大，不应直接比较。

lowest、highest 和 figures 选项对直方图的配置方式与 perf_hooks.createHistogram() 相同。lowest 必须大于 0，因为事件循环延迟不可能为零：事件循环存在最小开销，并且测量本身也依赖事件循环运行。大于 highest 的延迟不会被记录，而是由 histogram.exceeds 计数。对于基于间隔的采样，每个样本都包含 resolution，因此 highest 应远大于 resolution * 1e6。直方图的内存使用量取决于这些选项，而非样本数。

import { monitorEventLoopDelay } from 'node:perf_hooks';

const h = monitorEventLoopDelay({ resolution: 20 });
h.enable();
// 做一些事情。
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();
// 做一些事情。
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));

perf_hooks.timerify(fn, options?): void

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

将函数包装在一个新函数中，以测量被包装函数的运行时长。必须订阅 'function' 条目类型的 PerformanceObserver 才能访问计时详情。

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'] });

// 将创建一个性能时间线条目
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'] });

// 将创建一个性能时间线条目
wrapped();

如果被包装的函数返回一个 promise，则会向该 promise 附加一个 finally 处理程序，并在调用 finally 处理程序后报告时长。

histogram.burnRate(sloTarget): void

返回 SLO 消耗速率：ewmaErrorRate / (1 - sloTarget)。消耗速率为 1 表示错误预算将在 SLO 时间窗口内恰好耗尽。消耗速率大于 1 表示错误预算的消耗速度超出允许范围。要求创建直方图时同时指定 halfLife 和 threshold 选项。

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

// 使用 200ms 的 SLO 阈值和 100 个样本的半衰期跟踪延迟
const h = createHistogram({ halfLife: 100, threshold: 200_000_000 });

// ... 记录延迟值 ...

// 检查相对于 99.9% SLO 的消耗速率
const rate = h.burnRate(0.999);
if (rate > 1) {
  console.log(`SLO burn rate: ${rate.toFixed(2)}x — error budget depleting`);
}

• 类型：number

直方图记录的样本数。

• 类型：bigint

直方图记录的样本数。

histogram.ccdf(value): void

返回给定值的互补累积分布函数（CCDF）值，表示记录值超过 value 的概率。等价于 1 - histogram.cdf(value)。

histogram.cdf(value): void

返回给定值的累积分布函数（CDF）值，表示记录值小于或等于 value 的概率。这是 histogram.percentile() 的逆操作。

histogram.cliffsD(other): void

计算 Cliff's delta，这是一种非参数效应量度量。返回此直方图中的随机值超过 other 中随机值的概率，减去反向概率。值为 1 表示此直方图中的每个值都大于 other 中的每个值；-1 表示相反；0 表示两个方向都没有倾向性。

histogram.cohensD(other): void

计算 Cohen's d 效应量，即此直方图与 other 的均值之差的标准化结果，使用合并标准差计算。正值表示此直方图的均值较高。按照惯例，|d| < 0.2 表示效应较小，0.5 表示中等，0.8 或更高表示效应较大。两个直方图都必须至少记录 2 个值；否则返回 0。

histogram.countAt(value): void

返回落在给定值对应值范围内的记录值数量。

histogram.diff(other): void

返回一个新的 Histogram，其中包含在获取 other 之后记录到此直方图中的值。两个直方图都不会被修改。若要在不调用 reset() 的情况下获取每个时间间隔内记录的值，可从快照计算每次差值，并将该快照保留为下一个时间间隔的基线：

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

const histogram = monitorEventLoopDelay();
histogram.enable();
let previous = histogram.snapshot();

setInterval(() => {
  const current = histogram.snapshot();
  // 重置后，使用重置以来记录的所有数据。
  const delta = current.resetCount === previous.resetCount ?
    current.diff(previous) : current;
  console.log(delta.percentile(99));
  previous = current;
}, 10_000);

返回的直方图中的 count、exceeds 和桶计数是两个直方图之间的差值。其 min 和 max 根据差值对应的桶计算得出，不包含 EWMA 状态，且其 resetCount 为 0。

此方法会抛出：

• 如果 other 的 lowest、highest 或 figures 配置不同，则抛出 ERR_INVALID_ARG_VALUE。
• 如果自获取 other 后，此直方图中的值已被移除，则抛出 ERR_INVALID_STATE；当两个直方图的 resetCount 不同时就会出现这种情况。
• 如果 other 包含此直方图中不存在的值，则抛出 ERR_INVALID_ARG_VALUE，例如两个直方图的传入顺序错误时。

• 类型：number

因超过直方图可记录的最大值而未被记录的值的数量。

• 类型：bigint

因超过直方图可记录的最大值而未被记录的值的数量。

histogram.export(): void

• 返回：Uint8Array

将直方图序列化为适合传输或持久化存储的 CBOR 编码（RFC 8949）Uint8Array。该编码使用增量编码的稀疏桶计数表示，因此输出大小随不同记录值的数量变化，而非随桶总数变化。

输出包含所有直方图配置、桶数据和 EWMA 状态（启用时）。可使用 perf_hooks.importHistogram() 将其重建为新的直方图。

CBOR 负载是一个使用整数键的映射：

任何标准 CBOR 解码器都可以解析输出。

perf_hooks.importHistogram() 接受 histogram.export() 生成的所有格式版本：

• Node.js v26.9.0 生成了版本 1。对于带有版本 1 键或不带版本键的数据，将按照原始语义导入：不接受上面未列出的键。
• 版本 2 的布局与版本 1 相同。未识别的键会被忽略，因此之后的 Node.js 版本可以向版本 2 数据添加字段而不更改版本，并且数据仍可导入。

任何其他版本的数据都会被拒绝。

如果缺少总计数、最小值或最大值，则会根据桶计数推导得出。若存在总计数，则必须与桶计数相符。

• 类型：number

记录值的指数加权移动平均值。仅当创建直方图时指定的 halfLife 选项大于 0 时才有效。禁用 EWMA 或尚未记录任何值时返回 0。

• 类型：number

指数加权移动标准差。仅当创建直方图时指定的 halfLife 选项大于 0 时才有效。禁用 EWMA 或尚未记录任何值时返回 0。

• 类型：number

记录值超过配置的 threshold 的概率的 EWMA 平滑值。仅当创建直方图时同时指定 halfLife 和 threshold 选项才有效。未启用该功能或尚未记录任何值时返回 0。

histogram.ksTest(other): void

计算此直方图的分布与 other 的比较结果的 Kolmogorov-Smirnov 检验统计量。值为 0 表示分布完全相同；接近 1 的值表示分布完全不相交。 通过比较变更前后的直方图，可用于检测性能回归。