d58ac1e8ba9f683033e248846b176529e6b544619293b12f4b04b99a15236f09ee1efb8e2016e262cb5ad69bf56a0e61e361a1ed6417a9497b86852aff9a5c 38 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970
  1. /**
  2. * This module provides an implementation of a subset of the W3C [Web Performance APIs](https://w3c.github.io/perf-timing-primer/) as well as additional APIs for
  3. * Node.js-specific performance measurements.
  4. *
  5. * Node.js supports the following [Web Performance APIs](https://w3c.github.io/perf-timing-primer/):
  6. *
  7. * * [High Resolution Time](https://www.w3.org/TR/hr-time-2)
  8. * * [Performance Timeline](https://w3c.github.io/performance-timeline/)
  9. * * [User Timing](https://www.w3.org/TR/user-timing/)
  10. * * [Resource Timing](https://www.w3.org/TR/resource-timing-2/)
  11. *
  12. * ```js
  13. * import { PerformanceObserver, performance } from 'node:perf_hooks';
  14. *
  15. * const obs = new PerformanceObserver((items) => {
  16. * console.log(items.getEntries()[0].duration);
  17. * performance.clearMarks();
  18. * });
  19. * obs.observe({ type: 'measure' });
  20. * performance.measure('Start to Now');
  21. *
  22. * performance.mark('A');
  23. * doSomeLongRunningProcess(() => {
  24. * performance.measure('A to Now', 'A');
  25. *
  26. * performance.mark('B');
  27. * performance.measure('A to B', 'A', 'B');
  28. * });
  29. * ```
  30. * @see [source](https://github.com/nodejs/node/blob/v22.x/lib/perf_hooks.js)
  31. */
  32. declare module "perf_hooks" {
  33. import { AsyncResource } from "node:async_hooks";
  34. type EntryType =
  35. | "dns" // Node.js only
  36. | "function" // Node.js only
  37. | "gc" // Node.js only
  38. | "http2" // Node.js only
  39. | "http" // Node.js only
  40. | "mark" // available on the Web
  41. | "measure" // available on the Web
  42. | "net" // Node.js only
  43. | "node" // Node.js only
  44. | "resource"; // available on the Web
  45. interface NodeGCPerformanceDetail {
  46. /**
  47. * When `performanceEntry.entryType` is equal to 'gc', the `performance.kind` property identifies
  48. * the type of garbage collection operation that occurred.
  49. * See perf_hooks.constants for valid values.
  50. */
  51. readonly kind?: number | undefined;
  52. /**
  53. * When `performanceEntry.entryType` is equal to 'gc', the `performance.flags`
  54. * property contains additional information about garbage collection operation.
  55. * See perf_hooks.constants for valid values.
  56. */
  57. readonly flags?: number | undefined;
  58. }
  59. /**
  60. * The constructor of this class is not exposed to users directly.
  61. * @since v8.5.0
  62. */
  63. class PerformanceEntry {
  64. protected constructor();
  65. /**
  66. * The total number of milliseconds elapsed for this entry. This value will not
  67. * be meaningful for all Performance Entry types.
  68. * @since v8.5.0
  69. */
  70. readonly duration: number;
  71. /**
  72. * The name of the performance entry.
  73. * @since v8.5.0
  74. */
  75. readonly name: string;
  76. /**
  77. * The high resolution millisecond timestamp marking the starting time of the
  78. * Performance Entry.
  79. * @since v8.5.0
  80. */
  81. readonly startTime: number;
  82. /**
  83. * The type of the performance entry. It may be one of:
  84. *
  85. * * `'node'` (Node.js only)
  86. * * `'mark'` (available on the Web)
  87. * * `'measure'` (available on the Web)
  88. * * `'gc'` (Node.js only)
  89. * * `'function'` (Node.js only)
  90. * * `'http2'` (Node.js only)
  91. * * `'http'` (Node.js only)
  92. * @since v8.5.0
  93. */
  94. readonly entryType: EntryType;
  95. /**
  96. * Additional detail specific to the `entryType`.
  97. * @since v16.0.0
  98. */
  99. readonly detail?: NodeGCPerformanceDetail | unknown | undefined; // TODO: Narrow this based on entry type.
  100. toJSON(): any;
  101. }
  102. /**
  103. * Exposes marks created via the `Performance.mark()` method.
  104. * @since v18.2.0, v16.17.0
  105. */
  106. class PerformanceMark extends PerformanceEntry {
  107. readonly duration: 0;
  108. readonly entryType: "mark";
  109. }
  110. /**
  111. * Exposes measures created via the `Performance.measure()` method.
  112. *
  113. * The constructor of this class is not exposed to users directly.
  114. * @since v18.2.0, v16.17.0
  115. */
  116. class PerformanceMeasure extends PerformanceEntry {
  117. readonly entryType: "measure";
  118. }
  119. interface UVMetrics {
  120. /**
  121. * Number of event loop iterations.
  122. */
  123. readonly loopCount: number;
  124. /**
  125. * Number of events that have been processed by the event handler.
  126. */
  127. readonly events: number;
  128. /**
  129. * Number of events that were waiting to be processed when the event provider was called.
  130. */
  131. readonly eventsWaiting: number;
  132. }
  133. /**
  134. * _This property is an extension by Node.js. It is not available in Web browsers._
  135. *
  136. * Provides timing details for Node.js itself. The constructor of this class
  137. * is not exposed to users.
  138. * @since v8.5.0
  139. */
  140. class PerformanceNodeTiming extends PerformanceEntry {
  141. readonly entryType: "node";
  142. /**
  143. * The high resolution millisecond timestamp at which the Node.js process
  144. * completed bootstrapping. If bootstrapping has not yet finished, the property
  145. * has the value of -1.
  146. * @since v8.5.0
  147. */
  148. readonly bootstrapComplete: number;
  149. /**
  150. * The high resolution millisecond timestamp at which the Node.js environment was
  151. * initialized.
  152. * @since v8.5.0
  153. */
  154. readonly environment: number;
  155. /**
  156. * The high resolution millisecond timestamp of the amount of time the event loop
  157. * has been idle within the event loop's event provider (e.g. `epoll_wait`). This
  158. * does not take CPU usage into consideration. If the event loop has not yet
  159. * started (e.g., in the first tick of the main script), the property has the
  160. * value of 0.
  161. * @since v14.10.0, v12.19.0
  162. */
  163. readonly idleTime: number;
  164. /**
  165. * The high resolution millisecond timestamp at which the Node.js event loop
  166. * exited. If the event loop has not yet exited, the property has the value of -1\.
  167. * It can only have a value of not -1 in a handler of the `'exit'` event.
  168. * @since v8.5.0
  169. */
  170. readonly loopExit: number;
  171. /**
  172. * The high resolution millisecond timestamp at which the Node.js event loop
  173. * started. If the event loop has not yet started (e.g., in the first tick of the
  174. * main script), the property has the value of -1.
  175. * @since v8.5.0
  176. */
  177. readonly loopStart: number;
  178. /**
  179. * The high resolution millisecond timestamp at which the Node.js process was initialized.
  180. * @since v8.5.0
  181. */
  182. readonly nodeStart: number;
  183. /**
  184. * This is a wrapper to the `uv_metrics_info` function.
  185. * It returns the current set of event loop metrics.
  186. *
  187. * It is recommended to use this property inside a function whose execution was
  188. * scheduled using `setImmediate` to avoid collecting metrics before finishing all
  189. * operations scheduled during the current loop iteration.
  190. * @since v22.8.0, v20.18.0
  191. */
  192. readonly uvMetricsInfo: UVMetrics;
  193. /**
  194. * The high resolution millisecond timestamp at which the V8 platform was
  195. * initialized.
  196. * @since v8.5.0
  197. */
  198. readonly v8Start: number;
  199. }
  200. interface EventLoopUtilization {
  201. idle: number;
  202. active: number;
  203. utilization: number;
  204. }
  205. /**
  206. * @param utilization1 The result of a previous call to `eventLoopUtilization()`.
  207. * @param utilization2 The result of a previous call to `eventLoopUtilization()` prior to `utilization1`.
  208. */
  209. type EventLoopUtilityFunction = (
  210. utilization1?: EventLoopUtilization,
  211. utilization2?: EventLoopUtilization,
  212. ) => EventLoopUtilization;
  213. interface MarkOptions {
  214. /**
  215. * Additional optional detail to include with the mark.
  216. */
  217. detail?: unknown | undefined;
  218. /**
  219. * An optional timestamp to be used as the mark time.
  220. * @default `performance.now()`
  221. */
  222. startTime?: number | undefined;
  223. }
  224. interface MeasureOptions {
  225. /**
  226. * Additional optional detail to include with the mark.
  227. */
  228. detail?: unknown | undefined;
  229. /**
  230. * Duration between start and end times.
  231. */
  232. duration?: number | undefined;
  233. /**
  234. * Timestamp to be used as the end time, or a string identifying a previously recorded mark.
  235. */
  236. end?: number | string | undefined;
  237. /**
  238. * Timestamp to be used as the start time, or a string identifying a previously recorded mark.
  239. */
  240. start?: number | string | undefined;
  241. }
  242. interface TimerifyOptions {
  243. /**
  244. * A histogram object created using `perf_hooks.createHistogram()` that will record runtime
  245. * durations in nanoseconds.
  246. */
  247. histogram?: RecordableHistogram | undefined;
  248. }
  249. interface Performance {
  250. /**
  251. * If `name` is not provided, removes all `PerformanceMark` objects from the Performance Timeline.
  252. * If `name` is provided, removes only the named mark.
  253. * @since v8.5.0
  254. */
  255. clearMarks(name?: string): void;
  256. /**
  257. * If `name` is not provided, removes all `PerformanceMeasure` objects from the Performance Timeline.
  258. * If `name` is provided, removes only the named measure.
  259. * @since v16.7.0
  260. */
  261. clearMeasures(name?: string): void;
  262. /**
  263. * If `name` is not provided, removes all `PerformanceResourceTiming` objects from the Resource Timeline.
  264. * If `name` is provided, removes only the named resource.
  265. * @since v18.2.0, v16.17.0
  266. */
  267. clearResourceTimings(name?: string): void;
  268. /**
  269. * eventLoopUtilization is similar to CPU utilization except that it is calculated using high precision wall-clock time.
  270. * It represents the percentage of time the event loop has spent outside the event loop's event provider (e.g. epoll_wait).
  271. * No other CPU idle time is taken into consideration.
  272. */
  273. eventLoopUtilization: EventLoopUtilityFunction;
  274. /**
  275. * Returns a list of `PerformanceEntry` objects in chronological order with respect to `performanceEntry.startTime`.
  276. * If you are only interested in performance entries of certain types or that have certain names, see
  277. * `performance.getEntriesByType()` and `performance.getEntriesByName()`.
  278. * @since v16.7.0
  279. */
  280. getEntries(): PerformanceEntry[];
  281. /**
  282. * Returns a list of `PerformanceEntry` objects in chronological order with respect to `performanceEntry.startTime`
  283. * whose `performanceEntry.name` is equal to `name`, and optionally, whose `performanceEntry.entryType` is equal to `type`.
  284. * @param name
  285. * @param type
  286. * @since v16.7.0
  287. */
  288. getEntriesByName(name: string, type?: EntryType): PerformanceEntry[];
  289. /**
  290. * Returns a list of `PerformanceEntry` objects in chronological order with respect to `performanceEntry.startTime`
  291. * whose `performanceEntry.entryType` is equal to `type`.
  292. * @param type
  293. * @since v16.7.0
  294. */
  295. getEntriesByType(type: EntryType): PerformanceEntry[];
  296. /**
  297. * Creates a new `PerformanceMark` entry in the Performance Timeline.
  298. * A `PerformanceMark` is a subclass of `PerformanceEntry` whose `performanceEntry.entryType` is always `'mark'`,
  299. * and whose `performanceEntry.duration` is always `0`.
  300. * Performance marks are used to mark specific significant moments in the Performance Timeline.
  301. *
  302. * The created `PerformanceMark` entry is put in the global Performance Timeline and can be queried with
  303. * `performance.getEntries`, `performance.getEntriesByName`, and `performance.getEntriesByType`. When the observation is
  304. * performed, the entries should be cleared from the global Performance Timeline manually with `performance.clearMarks`.
  305. * @param name
  306. */
  307. mark(name: string, options?: MarkOptions): PerformanceMark;
  308. /**
  309. * Creates a new `PerformanceResourceTiming` entry in the Resource Timeline.
  310. * A `PerformanceResourceTiming` is a subclass of `PerformanceEntry` whose `performanceEntry.entryType` is always `'resource'`.
  311. * Performance resources are used to mark moments in the Resource Timeline.
  312. * @param timingInfo [Fetch Timing Info](https://fetch.spec.whatwg.org/#fetch-timing-info)
  313. * @param requestedUrl The resource url
  314. * @param initiatorType The initiator name, e.g: 'fetch'
  315. * @param global
  316. * @param cacheMode The cache mode must be an empty string ('') or 'local'
  317. * @param bodyInfo [Fetch Response Body Info](https://fetch.spec.whatwg.org/#response-body-info)
  318. * @param responseStatus The response's status code
  319. * @param deliveryType The delivery type. Default: ''.
  320. * @since v18.2.0, v16.17.0
  321. */
  322. markResourceTiming(
  323. timingInfo: object,
  324. requestedUrl: string,
  325. initiatorType: string,
  326. global: object,
  327. cacheMode: "" | "local",
  328. bodyInfo: object,
  329. responseStatus: number,
  330. deliveryType?: string,
  331. ): PerformanceResourceTiming;
  332. /**
  333. * Creates a new PerformanceMeasure entry in the Performance Timeline.
  334. * A PerformanceMeasure is a subclass of PerformanceEntry whose performanceEntry.entryType is always 'measure',
  335. * and whose performanceEntry.duration measures the number of milliseconds elapsed since startMark and endMark.
  336. *
  337. * The startMark argument may identify any existing PerformanceMark in the the Performance Timeline, or may identify
  338. * any of the timestamp properties provided by the PerformanceNodeTiming class. If the named startMark does not exist,
  339. * then startMark is set to timeOrigin by default.
  340. *
  341. * The endMark argument must identify any existing PerformanceMark in the the Performance Timeline or any of the timestamp
  342. * properties provided by the PerformanceNodeTiming class. If the named endMark does not exist, an error will be thrown.
  343. * @param name
  344. * @param startMark
  345. * @param endMark
  346. * @return The PerformanceMeasure entry that was created
  347. */
  348. measure(name: string, startMark?: string, endMark?: string): PerformanceMeasure;
  349. measure(name: string, options: MeasureOptions): PerformanceMeasure;
  350. /**
  351. * _This property is an extension by Node.js. It is not available in Web browsers._
  352. *
  353. * An instance of the `PerformanceNodeTiming` class that provides performance metrics for specific Node.js operational milestones.
  354. * @since v8.5.0
  355. */
  356. readonly nodeTiming: PerformanceNodeTiming;
  357. /**
  358. * Returns the current high resolution millisecond timestamp, where 0 represents the start of the current `node` process.
  359. * @since v8.5.0
  360. */
  361. now(): number;
  362. /**
  363. * Sets the global performance resource timing buffer size to the specified number of "resource" type performance entry objects.
  364. *
  365. * By default the max buffer size is set to 250.
  366. * @since v18.8.0
  367. */
  368. setResourceTimingBufferSize(maxSize: number): void;
  369. /**
  370. * The [`timeOrigin`](https://w3c.github.io/hr-time/#dom-performance-timeorigin) specifies the high resolution millisecond timestamp
  371. * at which the current `node` process began, measured in Unix time.
  372. * @since v8.5.0
  373. */
  374. readonly timeOrigin: number;
  375. /**
  376. * _This property is an extension by Node.js. It is not available in Web browsers._
  377. *
  378. * Wraps a function within a new function that measures the running time of the wrapped function.
  379. * A `PerformanceObserver` must be subscribed to the `'function'` event type in order for the timing details to be accessed.
  380. *
  381. * ```js
  382. * import {
  383. * performance,
  384. * PerformanceObserver,
  385. * } from 'node:perf_hooks';
  386. *
  387. * function someFunction() {
  388. * console.log('hello world');
  389. * }
  390. *
  391. * const wrapped = performance.timerify(someFunction);
  392. *
  393. * const obs = new PerformanceObserver((list) => {
  394. * console.log(list.getEntries()[0].duration);
  395. *
  396. * performance.clearMarks();
  397. * performance.clearMeasures();
  398. * obs.disconnect();
  399. * });
  400. * obs.observe({ entryTypes: ['function'] });
  401. *
  402. * // A performance timeline entry will be created
  403. * wrapped();
  404. * ```
  405. *
  406. * If the wrapped function returns a promise, a finally handler will be attached to the promise and the duration will be reported
  407. * once the finally handler is invoked.
  408. * @param fn
  409. */
  410. timerify<T extends (...params: any[]) => any>(fn: T, options?: TimerifyOptions): T;
  411. /**
  412. * An object which is JSON representation of the performance object. It is similar to
  413. * [`window.performance.toJSON`](https://developer.mozilla.org/en-US/docs/Web/API/Performance/toJSON) in browsers.
  414. * @since v16.1.0
  415. */
  416. toJSON(): any;
  417. }
  418. class PerformanceObserverEntryList {
  419. /**
  420. * Returns a list of `PerformanceEntry` objects in chronological order
  421. * with respect to `performanceEntry.startTime`.
  422. *
  423. * ```js
  424. * import {
  425. * performance,
  426. * PerformanceObserver,
  427. * } from 'node:perf_hooks';
  428. *
  429. * const obs = new PerformanceObserver((perfObserverList, observer) => {
  430. * console.log(perfObserverList.getEntries());
  431. *
  432. * * [
  433. * * PerformanceEntry {
  434. * * name: 'test',
  435. * * entryType: 'mark',
  436. * * startTime: 81.465639,
  437. * * duration: 0,
  438. * * detail: null
  439. * * },
  440. * * PerformanceEntry {
  441. * * name: 'meow',
  442. * * entryType: 'mark',
  443. * * startTime: 81.860064,
  444. * * duration: 0,
  445. * * detail: null
  446. * * }
  447. * * ]
  448. *
  449. * performance.clearMarks();
  450. * performance.clearMeasures();
  451. * observer.disconnect();
  452. * });
  453. * obs.observe({ type: 'mark' });
  454. *
  455. * performance.mark('test');
  456. * performance.mark('meow');
  457. * ```
  458. * @since v8.5.0
  459. */
  460. getEntries(): PerformanceEntry[];
  461. /**
  462. * Returns a list of `PerformanceEntry` objects in chronological order
  463. * with respect to `performanceEntry.startTime` whose `performanceEntry.name` is
  464. * equal to `name`, and optionally, whose `performanceEntry.entryType` is equal to`type`.
  465. *
  466. * ```js
  467. * import {
  468. * performance,
  469. * PerformanceObserver,
  470. * } from 'node:perf_hooks';
  471. *
  472. * const obs = new PerformanceObserver((perfObserverList, observer) => {
  473. * console.log(perfObserverList.getEntriesByName('meow'));
  474. *
  475. * * [
  476. * * PerformanceEntry {
  477. * * name: 'meow',
  478. * * entryType: 'mark',
  479. * * startTime: 98.545991,
  480. * * duration: 0,
  481. * * detail: null
  482. * * }
  483. * * ]
  484. *
  485. * console.log(perfObserverList.getEntriesByName('nope')); // []
  486. *
  487. * console.log(perfObserverList.getEntriesByName('test', 'mark'));
  488. *
  489. * * [
  490. * * PerformanceEntry {
  491. * * name: 'test',
  492. * * entryType: 'mark',
  493. * * startTime: 63.518931,
  494. * * duration: 0,
  495. * * detail: null
  496. * * }
  497. * * ]
  498. *
  499. * console.log(perfObserverList.getEntriesByName('test', 'measure')); // []
  500. *
  501. * performance.clearMarks();
  502. * performance.clearMeasures();
  503. * observer.disconnect();
  504. * });
  505. * obs.observe({ entryTypes: ['mark', 'measure'] });
  506. *
  507. * performance.mark('test');
  508. * performance.mark('meow');
  509. * ```
  510. * @since v8.5.0
  511. */
  512. getEntriesByName(name: string, type?: EntryType): PerformanceEntry[];
  513. /**
  514. * Returns a list of `PerformanceEntry` objects in chronological order
  515. * with respect to `performanceEntry.startTime` whose `performanceEntry.entryType` is equal to `type`.
  516. *
  517. * ```js
  518. * import {
  519. * performance,
  520. * PerformanceObserver,
  521. * } from 'node:perf_hooks';
  522. *
  523. * const obs = new PerformanceObserver((perfObserverList, observer) => {
  524. * console.log(perfObserverList.getEntriesByType('mark'));
  525. *
  526. * * [
  527. * * PerformanceEntry {
  528. * * name: 'test',
  529. * * entryType: 'mark',
  530. * * startTime: 55.897834,
  531. * * duration: 0,
  532. * * detail: null
  533. * * },
  534. * * PerformanceEntry {
  535. * * name: 'meow',
  536. * * entryType: 'mark',
  537. * * startTime: 56.350146,
  538. * * duration: 0,
  539. * * detail: null
  540. * * }
  541. * * ]
  542. *
  543. * performance.clearMarks();
  544. * performance.clearMeasures();
  545. * observer.disconnect();
  546. * });
  547. * obs.observe({ type: 'mark' });
  548. *
  549. * performance.mark('test');
  550. * performance.mark('meow');
  551. * ```
  552. * @since v8.5.0
  553. */
  554. getEntriesByType(type: EntryType): PerformanceEntry[];
  555. }
  556. type PerformanceObserverCallback = (list: PerformanceObserverEntryList, observer: PerformanceObserver) => void;
  557. /**
  558. * @since v8.5.0
  559. */
  560. class PerformanceObserver extends AsyncResource {
  561. constructor(callback: PerformanceObserverCallback);
  562. /**
  563. * Disconnects the `PerformanceObserver` instance from all notifications.
  564. * @since v8.5.0
  565. */
  566. disconnect(): void;
  567. /**
  568. * Subscribes the `PerformanceObserver` instance to notifications of new `PerformanceEntry` instances identified either by `options.entryTypes` or `options.type`:
  569. *
  570. * ```js
  571. * import {
  572. * performance,
  573. * PerformanceObserver,
  574. * } from 'node:perf_hooks';
  575. *
  576. * const obs = new PerformanceObserver((list, observer) => {
  577. * // Called once asynchronously. `list` contains three items.
  578. * });
  579. * obs.observe({ type: 'mark' });
  580. *
  581. * for (let n = 0; n < 3; n++)
  582. * performance.mark(`test${n}`);
  583. * ```
  584. * @since v8.5.0
  585. */
  586. observe(
  587. options:
  588. | {
  589. entryTypes: readonly EntryType[];
  590. buffered?: boolean | undefined;
  591. }
  592. | {
  593. type: EntryType;
  594. buffered?: boolean | undefined;
  595. },
  596. ): void;
  597. /**
  598. * @since v16.0.0
  599. * @returns Current list of entries stored in the performance observer, emptying it out.
  600. */
  601. takeRecords(): PerformanceEntry[];
  602. }
  603. /**
  604. * Provides detailed network timing data regarding the loading of an application's resources.
  605. *
  606. * The constructor of this class is not exposed to users directly.
  607. * @since v18.2.0, v16.17.0
  608. */
  609. class PerformanceResourceTiming extends PerformanceEntry {
  610. readonly entryType: "resource";
  611. protected constructor();
  612. /**
  613. * The high resolution millisecond timestamp at immediately before dispatching the `fetch`
  614. * request. If the resource is not intercepted by a worker the property will always return 0.
  615. * @since v18.2.0, v16.17.0
  616. */
  617. readonly workerStart: number;
  618. /**
  619. * The high resolution millisecond timestamp that represents the start time of the fetch which
  620. * initiates the redirect.
  621. * @since v18.2.0, v16.17.0
  622. */
  623. readonly redirectStart: number;
  624. /**
  625. * The high resolution millisecond timestamp that will be created immediately after receiving
  626. * the last byte of the response of the last redirect.
  627. * @since v18.2.0, v16.17.0
  628. */
  629. readonly redirectEnd: number;
  630. /**
  631. * The high resolution millisecond timestamp immediately before the Node.js starts to fetch the resource.
  632. * @since v18.2.0, v16.17.0
  633. */
  634. readonly fetchStart: number;
  635. /**
  636. * The high resolution millisecond timestamp immediately before the Node.js starts the domain name lookup
  637. * for the resource.
  638. * @since v18.2.0, v16.17.0
  639. */
  640. readonly domainLookupStart: number;
  641. /**
  642. * The high resolution millisecond timestamp representing the time immediately after the Node.js finished
  643. * the domain name lookup for the resource.
  644. * @since v18.2.0, v16.17.0
  645. */
  646. readonly domainLookupEnd: number;
  647. /**
  648. * The high resolution millisecond timestamp representing the time immediately before Node.js starts to
  649. * establish the connection to the server to retrieve the resource.
  650. * @since v18.2.0, v16.17.0
  651. */
  652. readonly connectStart: number;
  653. /**
  654. * The high resolution millisecond timestamp representing the time immediately after Node.js finishes
  655. * establishing the connection to the server to retrieve the resource.
  656. * @since v18.2.0, v16.17.0
  657. */
  658. readonly connectEnd: number;
  659. /**
  660. * The high resolution millisecond timestamp representing the time immediately before Node.js starts the
  661. * handshake process to secure the current connection.
  662. * @since v18.2.0, v16.17.0
  663. */
  664. readonly secureConnectionStart: number;
  665. /**
  666. * The high resolution millisecond timestamp representing the time immediately before Node.js receives the
  667. * first byte of the response from the server.
  668. * @since v18.2.0, v16.17.0
  669. */
  670. readonly requestStart: number;
  671. /**
  672. * The high resolution millisecond timestamp representing the time immediately after Node.js receives the
  673. * last byte of the resource or immediately before the transport connection is closed, whichever comes first.
  674. * @since v18.2.0, v16.17.0
  675. */
  676. readonly responseEnd: number;
  677. /**
  678. * A number representing the size (in octets) of the fetched resource. The size includes the response header
  679. * fields plus the response payload body.
  680. * @since v18.2.0, v16.17.0
  681. */
  682. readonly transferSize: number;
  683. /**
  684. * A number representing the size (in octets) received from the fetch (HTTP or cache), of the payload body, before
  685. * removing any applied content-codings.
  686. * @since v18.2.0, v16.17.0
  687. */
  688. readonly encodedBodySize: number;
  689. /**
  690. * A number representing the size (in octets) received from the fetch (HTTP or cache), of the message body, after
  691. * removing any applied content-codings.
  692. * @since v18.2.0, v16.17.0
  693. */
  694. readonly decodedBodySize: number;
  695. /**
  696. * Returns a `object` that is the JSON representation of the `PerformanceResourceTiming` object
  697. * @since v18.2.0, v16.17.0
  698. */
  699. toJSON(): any;
  700. }
  701. namespace constants {
  702. const NODE_PERFORMANCE_GC_MAJOR: number;
  703. const NODE_PERFORMANCE_GC_MINOR: number;
  704. const NODE_PERFORMANCE_GC_INCREMENTAL: number;
  705. const NODE_PERFORMANCE_GC_WEAKCB: number;
  706. const NODE_PERFORMANCE_GC_FLAGS_NO: number;
  707. const NODE_PERFORMANCE_GC_FLAGS_CONSTRUCT_RETAINED: number;
  708. const NODE_PERFORMANCE_GC_FLAGS_FORCED: number;
  709. const NODE_PERFORMANCE_GC_FLAGS_SYNCHRONOUS_PHANTOM_PROCESSING: number;
  710. const NODE_PERFORMANCE_GC_FLAGS_ALL_AVAILABLE_GARBAGE: number;
  711. const NODE_PERFORMANCE_GC_FLAGS_ALL_EXTERNAL_MEMORY: number;
  712. const NODE_PERFORMANCE_GC_FLAGS_SCHEDULE_IDLE: number;
  713. }
  714. const performance: Performance;
  715. interface EventLoopMonitorOptions {
  716. /**
  717. * The sampling rate in milliseconds.
  718. * Must be greater than zero.
  719. * @default 10
  720. */
  721. resolution?: number | undefined;
  722. }
  723. interface Histogram {
  724. /**
  725. * The number of samples recorded by the histogram.
  726. * @since v17.4.0, v16.14.0
  727. */
  728. readonly count: number;
  729. /**
  730. * The number of samples recorded by the histogram.
  731. * v17.4.0, v16.14.0
  732. */
  733. readonly countBigInt: bigint;
  734. /**
  735. * The number of times the event loop delay exceeded the maximum 1 hour event
  736. * loop delay threshold.
  737. * @since v11.10.0
  738. */
  739. readonly exceeds: number;
  740. /**
  741. * The number of times the event loop delay exceeded the maximum 1 hour event loop delay threshold.
  742. * @since v17.4.0, v16.14.0
  743. */
  744. readonly exceedsBigInt: bigint;
  745. /**
  746. * The maximum recorded event loop delay.
  747. * @since v11.10.0
  748. */
  749. readonly max: number;
  750. /**
  751. * The maximum recorded event loop delay.
  752. * v17.4.0, v16.14.0
  753. */
  754. readonly maxBigInt: number;
  755. /**
  756. * The mean of the recorded event loop delays.
  757. * @since v11.10.0
  758. */
  759. readonly mean: number;
  760. /**
  761. * The minimum recorded event loop delay.
  762. * @since v11.10.0
  763. */
  764. readonly min: number;
  765. /**
  766. * The minimum recorded event loop delay.
  767. * v17.4.0, v16.14.0
  768. */
  769. readonly minBigInt: bigint;
  770. /**
  771. * Returns the value at the given percentile.
  772. * @since v11.10.0
  773. * @param percentile A percentile value in the range (0, 100].
  774. */
  775. percentile(percentile: number): number;
  776. /**
  777. * Returns the value at the given percentile.
  778. * @since v17.4.0, v16.14.0
  779. * @param percentile A percentile value in the range (0, 100].
  780. */
  781. percentileBigInt(percentile: number): bigint;
  782. /**
  783. * Returns a `Map` object detailing the accumulated percentile distribution.
  784. * @since v11.10.0
  785. */
  786. readonly percentiles: Map<number, number>;
  787. /**
  788. * Returns a `Map` object detailing the accumulated percentile distribution.
  789. * @since v17.4.0, v16.14.0
  790. */
  791. readonly percentilesBigInt: Map<bigint, bigint>;
  792. /**
  793. * Resets the collected histogram data.
  794. * @since v11.10.0
  795. */
  796. reset(): void;
  797. /**
  798. * The standard deviation of the recorded event loop delays.
  799. * @since v11.10.0
  800. */
  801. readonly stddev: number;
  802. }
  803. interface IntervalHistogram extends Histogram {
  804. /**
  805. * Enables the update interval timer. Returns `true` if the timer was
  806. * started, `false` if it was already started.
  807. * @since v11.10.0
  808. */
  809. enable(): boolean;
  810. /**
  811. * Disables the update interval timer. Returns `true` if the timer was
  812. * stopped, `false` if it was already stopped.
  813. * @since v11.10.0
  814. */
  815. disable(): boolean;
  816. }
  817. interface RecordableHistogram extends Histogram {
  818. /**
  819. * @since v15.9.0, v14.18.0
  820. * @param val The amount to record in the histogram.
  821. */
  822. record(val: number | bigint): void;
  823. /**
  824. * Calculates the amount of time (in nanoseconds) that has passed since the
  825. * previous call to `recordDelta()` and records that amount in the histogram.
  826. * @since v15.9.0, v14.18.0
  827. */
  828. recordDelta(): void;
  829. /**
  830. * Adds the values from `other` to this histogram.
  831. * @since v17.4.0, v16.14.0
  832. */
  833. add(other: RecordableHistogram): void;
  834. }
  835. /**
  836. * _This property is an extension by Node.js. It is not available in Web browsers._
  837. *
  838. * Creates an `IntervalHistogram` object that samples and reports the event loop
  839. * delay over time. The delays will be reported in nanoseconds.
  840. *
  841. * Using a timer to detect approximate event loop delay works because the
  842. * execution of timers is tied specifically to the lifecycle of the libuv
  843. * event loop. That is, a delay in the loop will cause a delay in the execution
  844. * of the timer, and those delays are specifically what this API is intended to
  845. * detect.
  846. *
  847. * ```js
  848. * import { monitorEventLoopDelay } from 'node:perf_hooks';
  849. * const h = monitorEventLoopDelay({ resolution: 20 });
  850. * h.enable();
  851. * // Do something.
  852. * h.disable();
  853. * console.log(h.min);
  854. * console.log(h.max);
  855. * console.log(h.mean);
  856. * console.log(h.stddev);
  857. * console.log(h.percentiles);
  858. * console.log(h.percentile(50));
  859. * console.log(h.percentile(99));
  860. * ```
  861. * @since v11.10.0
  862. */
  863. function monitorEventLoopDelay(options?: EventLoopMonitorOptions): IntervalHistogram;
  864. interface CreateHistogramOptions {
  865. /**
  866. * The minimum recordable value. Must be an integer value greater than 0.
  867. * @default 1
  868. */
  869. min?: number | bigint | undefined;
  870. /**
  871. * The maximum recordable value. Must be an integer value greater than min.
  872. * @default Number.MAX_SAFE_INTEGER
  873. */
  874. max?: number | bigint | undefined;
  875. /**
  876. * The number of accuracy digits. Must be a number between 1 and 5.
  877. * @default 3
  878. */
  879. figures?: number | undefined;
  880. }
  881. /**
  882. * Returns a `RecordableHistogram`.
  883. * @since v15.9.0, v14.18.0
  884. */
  885. function createHistogram(options?: CreateHistogramOptions): RecordableHistogram;
  886. import {
  887. performance as _performance,
  888. PerformanceEntry as _PerformanceEntry,
  889. PerformanceMark as _PerformanceMark,
  890. PerformanceMeasure as _PerformanceMeasure,
  891. PerformanceObserver as _PerformanceObserver,
  892. PerformanceObserverEntryList as _PerformanceObserverEntryList,
  893. PerformanceResourceTiming as _PerformanceResourceTiming,
  894. } from "perf_hooks";
  895. global {
  896. /**
  897. * `PerformanceEntry` is a global reference for `import { PerformanceEntry } from 'node:perf_hooks'`
  898. * @see https://nodejs.org/docs/latest-v22.x/api/globals.html#performanceentry
  899. * @since v19.0.0
  900. */
  901. var PerformanceEntry: typeof globalThis extends {
  902. onmessage: any;
  903. PerformanceEntry: infer T;
  904. } ? T
  905. : typeof _PerformanceEntry;
  906. /**
  907. * `PerformanceMark` is a global reference for `import { PerformanceMark } from 'node:perf_hooks'`
  908. * @see https://nodejs.org/docs/latest-v22.x/api/globals.html#performancemark
  909. * @since v19.0.0
  910. */
  911. var PerformanceMark: typeof globalThis extends {
  912. onmessage: any;
  913. PerformanceMark: infer T;
  914. } ? T
  915. : typeof _PerformanceMark;
  916. /**
  917. * `PerformanceMeasure` is a global reference for `import { PerformanceMeasure } from 'node:perf_hooks'`
  918. * @see https://nodejs.org/docs/latest-v22.x/api/globals.html#performancemeasure
  919. * @since v19.0.0
  920. */
  921. var PerformanceMeasure: typeof globalThis extends {
  922. onmessage: any;
  923. PerformanceMeasure: infer T;
  924. } ? T
  925. : typeof _PerformanceMeasure;
  926. /**
  927. * `PerformanceObserver` is a global reference for `import { PerformanceObserver } from 'node:perf_hooks'`
  928. * @see https://nodejs.org/docs/latest-v22.x/api/globals.html#performanceobserver
  929. * @since v19.0.0
  930. */
  931. var PerformanceObserver: typeof globalThis extends {
  932. onmessage: any;
  933. PerformanceObserver: infer T;
  934. } ? T
  935. : typeof _PerformanceObserver;
  936. /**
  937. * `PerformanceObserverEntryList` is a global reference for `import { PerformanceObserverEntryList } from 'node:perf_hooks'`
  938. * @see https://nodejs.org/docs/latest-v22.x/api/globals.html#performanceobserverentrylist
  939. * @since v19.0.0
  940. */
  941. var PerformanceObserverEntryList: typeof globalThis extends {
  942. onmessage: any;
  943. PerformanceObserverEntryList: infer T;
  944. } ? T
  945. : typeof _PerformanceObserverEntryList;
  946. /**
  947. * `PerformanceResourceTiming` is a global reference for `import { PerformanceResourceTiming } from 'node:perf_hooks'`
  948. * @see https://nodejs.org/docs/latest-v22.x/api/globals.html#performanceresourcetiming
  949. * @since v19.0.0
  950. */
  951. var PerformanceResourceTiming: typeof globalThis extends {
  952. onmessage: any;
  953. PerformanceResourceTiming: infer T;
  954. } ? T
  955. : typeof _PerformanceResourceTiming;
  956. /**
  957. * `performance` is a global reference for `import { performance } from 'node:perf_hooks'`
  958. * @see https://nodejs.org/docs/latest-v22.x/api/globals.html#performance
  959. * @since v16.0.0
  960. */
  961. var performance: typeof globalThis extends {
  962. onmessage: any;
  963. performance: infer T;
  964. } ? T
  965. : typeof _performance;
  966. }
  967. }
  968. declare module "node:perf_hooks" {
  969. export * from "perf_hooks";
  970. }