Skip to content

Commit 8b0bdc9

Browse files
joyeecheungjoyeecheung
committed
doc: clarify about the Node.js-only extensions in perf_hooks
- Add clarifications for Node.js-only extensions - Explain the Web Performance APIs implemented in Node.js and clarify that perf_hooks also include other non-Web APIs. - Prefix exposed interfaces with `perf_hooks.` to distinguish them from internal classes. PR-URL: #33199 Refs: #28635 Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Chengzhong Wu <legendecas@gmail.com> Reviewed-By: Rich Trott <rtrott@gmail.com> Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>
1 parent fe1b9e0 commit 8b0bdc9

2 files changed

Lines changed: 49 additions & 13 deletions

File tree

‎doc/api/perf_hooks.md‎

Lines changed: 48 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,18 @@
1-
# Performance Timing API
1+
# Performance Measurement APIs
22

33
<!--introduced_in=v8.5.0-->
44

55
> Stability: 2 - Stable
66
7-
The Performance Timing API provides an implementation of the
8-
[W3C Performance Timeline][] specification. The purpose of the API
9-
is to support collection of high resolution performance metrics.
10-
This is the same Performance API as implemented in modern Web browsers.
7+
This module provides an implementation of a subset of the W3C
8+
[Web Performance APIs][] as well as additional APIs for
9+
Node.js-specific performance measurements.
10+
11+
Node.js supports the following [Web Performance APIs][]:
12+
13+
* [High Resolution Time][]
14+
* [Performance Timeline][]
15+
* [User Timing][]
1116

1217
```js
1318
const { PerformanceObserver, performance } = require('perf_hooks');
@@ -28,11 +33,14 @@ doSomeLongRunningProcess(() => {
2833
});
2934
```
3035

31-
## Class: `Performance`
36+
## `perf_hooks.performance`
3237
<!-- YAML
3338
added: v8.5.0
3439
-->
3540

41+
An object that can be used to collect performance metrics from the current
42+
Node.js instance. It is similar to [`window.performance`][] in browsers.
43+
3644
### `performance.clearMarks([name])`
3745
<!-- YAML
3846
added: v8.5.0
@@ -95,6 +103,8 @@ added: v8.5.0
95103

96104
* {PerformanceNodeTiming}
97105

106+
_This property is an extension by Node.js. It is not available in Web browsers._
107+
98108
An instance of the `PerformanceNodeTiming` class that provides performance
99109
metrics for specific Node.js operational milestones.
100110

@@ -125,6 +135,8 @@ added: v8.5.0
125135

126136
* `fn` {Function}
127137

138+
_This property is an extension by Node.js. It is not available in Web browsers._
139+
128140
Wraps a function within a new function that measures the running time of the
129141
wrapped function. A `PerformanceObserver` must be subscribed to the `'function'`
130142
event type in order for the timing details to be accessed.
@@ -192,8 +204,15 @@ added: v8.5.0
192204

193205
* {string}
194206

195-
The type of the performance entry. Currently it may be one of: `'node'`,
196-
`'mark'`, `'measure'`, `'gc'`, `'function'`, `'http2'` or `'http'`.
207+
The type of the performance entry. It may be one of:
208+
209+
* `'node'` (Node.js only)
210+
* `'mark'` (available on the Web)
211+
* `'measure'` (available on the Web)
212+
* `'gc'` (Node.js only)
213+
* `'function'` (Node.js only)
214+
* `'http2'` (Node.js only)
215+
* `'http'` (Node.js only)
197216

198217
### `performanceEntry.kind`
199218
<!-- YAML
@@ -202,6 +221,8 @@ added: v8.5.0
202221

203222
* {number}
204223

224+
_This property is an extension by Node.js. It is not available in Web browsers._
225+
205226
When `performanceEntry.entryType` is equal to `'gc'`, the `performance.kind`
206227
property identifies the type of garbage collection operation that occurred.
207228
The value may be one of:
@@ -218,6 +239,8 @@ added: v13.9.0
218239

219240
* {number}
220241

242+
_This property is an extension by Node.js. It is not available in Web browsers._
243+
221244
When `performanceEntry.entryType` is equal to `'gc'`, the `performance.flags`
222245
property contains additional information about garbage collection operation.
223246
The value may be one of:
@@ -235,7 +258,10 @@ The value may be one of:
235258
added: v8.5.0
236259
-->
237260

238-
Provides timing details for Node.js itself.
261+
_This property is an extension by Node.js. It is not available in Web browsers._
262+
263+
Provides timing details for Node.js itself. The constructor of this class
264+
is not exposed to users.
239265

240266
### `performanceNodeTiming.bootstrapComplete`
241267
<!-- YAML
@@ -300,7 +326,7 @@ added: v8.5.0
300326
The high resolution millisecond timestamp at which the V8 platform was
301327
initialized.
302328

303-
## Class: `PerformanceObserver`
329+
## Class: `perf_hooks.PerformanceObserver`
304330

305331
### `new PerformanceObserver(callback)`
306332
<!-- YAML
@@ -402,6 +428,7 @@ added: v8.5.0
402428

403429
The `PerformanceObserverEntryList` class is used to provide access to the
404430
`PerformanceEntry` instances passed to a `PerformanceObserver`.
431+
The constructor of this class is not exposed to users.
405432

406433
### `performanceObserverEntryList.getEntries()`
407434
<!-- YAML
@@ -449,6 +476,8 @@ added: v11.10.0
449476
than zero. **Default:** `10`.
450477
* Returns: {Histogram}
451478

479+
_This property is an extension by Node.js. It is not available in Web browsers._
480+
452481
Creates a `Histogram` object that samples and reports the event loop delay
453482
over time. The delays will be reported in nanoseconds.
454483

@@ -477,7 +506,10 @@ console.log(h.percentile(99));
477506
<!-- YAML
478507
added: v11.10.0
479508
-->
480-
Tracks the event loop delay at a given sampling rate.
509+
Tracks the event loop delay at a given sampling rate. The constructor of
510+
this class not exposed to users.
511+
512+
_This property is an extension by Node.js. It is not available in Web browsers._
481513

482514
#### `histogram.disable()`
483515
<!-- YAML
@@ -651,5 +683,9 @@ require('some-module');
651683

652684
[`'exit'`]: process.html#process_event_exit
653685
[`timeOrigin`]: https://w3c.github.io/hr-time/#dom-performance-timeorigin
686+
[`window.performance`]: https://developer.mozilla.org/en-US/docs/Web/API/Window/performance
654687
[Async Hooks]: async_hooks.html
655-
[W3C Performance Timeline]: https://w3c.github.io/performance-timeline/
688+
[High Resolution Time]: https://www.w3.org/TR/hr-time-2
689+
[Performance Timeline]: https://w3c.github.io/performance-timeline/
690+
[Web Performance APIs]: https://w3c.github.io/perf-timing-primer/
691+
[User Timing]: https://www.w3.org/TR/user-timing/

‎tools/doc/type-parser.js‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -126,7 +126,7 @@ const customTypesMap = {
126126
'PerformanceNodeTiming':
127127
'perf_hooks.html#perf_hooks_class_performancenodetiming_extends_performanceentry', // eslint-disable-line max-len
128128
'PerformanceObserver':
129-
'perf_hooks.html#perf_hooks_class_performanceobserver',
129+
'perf_hooks.html#perf_hooks_class_perf_hooks_performanceobserver',
130130
'PerformanceObserverEntryList':
131131
'perf_hooks.html#perf_hooks_class_performanceobserverentrylist',
132132

0 commit comments

Comments
 (0)