diff options
Diffstat (limited to 'doc/api/perf_hooks.md')
| -rw-r--r-- | doc/api/perf_hooks.md | 71 |
1 files changed, 71 insertions, 0 deletions
diff --git a/doc/api/perf_hooks.md b/doc/api/perf_hooks.md index 392dc2a5245..c8770c25605 100644 --- a/doc/api/perf_hooks.md +++ b/doc/api/perf_hooks.md @@ -165,6 +165,62 @@ obs.observe({ entryTypes: ['function'] }); wrapped(); ``` +### `performance.eventLoopUtilization([util1][,util2])` +<!-- YAML +added: REPLACEME +--> + +* `util1` {Object} The result of a previous call to `eventLoopUtilization()` +* `util2` {Object} The result of a previous call to `eventLoopUtilization()` + prior to `util1` +* Returns {Object} + * `idle` {number} + * `active` {number} + * `utilization` {number} + +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). If bootstrapping has not yet finished, the +properties have the value of 0. + +`util1` and `util2` are optional parameters. + +If `util1` is passed then the delta between the current call's `active` and +`idle` times are calculated and returned (similar to [`process.hrtime()`][]). +Likewise the adjusted `utilization` value is calculated. + +If `util1` and `util2` are both passed then the calculation adjustments are +done between the two arguments. This is a convenience option because unlike +[`process.hrtime()`][] additional work is done to calculate the ELU. + +ELU is similar to CPU utilization except that it is calculated using high +precision wall-clock time. It represents the percentage of time the event loop +has spent outside the event loop's event provider (e.g. `epoll_wait`). No other +CPU idle time is taken into consideration. The following is an example of how +a mostly idle process will have a high ELU. + +<!-- eslint-skip --> +```js +'use strict'; +const { eventLoopUtilization } = require('perf_hooks').performance; +const { spawnSync } = require('child_process'); + +setImmediate(() => { + const elu = eventLoopUtilization(); + spawnSync('sleep', ['5']); + console.log(eventLoopUtilization(elu).utilization); +}); +``` + +While 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. + +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. + ## Class: `PerformanceEntry` <!-- YAML added: v8.5.0 @@ -332,6 +388,19 @@ added: v8.5.0 The high resolution millisecond timestamp at which the V8 platform was initialized. +### `performanceNodeTiming.idleTime` +<!-- YAML +added: REPLACEME +--> + +* {number} + +The high resolution millisecond timestamp of the amount of time the event loop +has been idle within the event loop's event provider (e.g. `epoll_wait`). This +does not take CPU usage into consideration. If the event loop has not yet +started (e.g., in the first tick of the main script), the property has the +value of 0. + ## Class: `perf_hooks.PerformanceObserver` ### `new PerformanceObserver(callback)` @@ -688,6 +757,8 @@ require('some-module'); ``` [`'exit'`]: process.html#process_event_exit +[`process.hrtime()`]: process.html#process_process_hrtime_time +[`child_process.spawnSync()`]: #child_process_child_process_spawnsync_command_args_options [`timeOrigin`]: https://w3c.github.io/hr-time/#dom-performance-timeorigin [`window.performance`]: https://developer.mozilla.org/en-US/docs/Web/API/Window/performance [Async Hooks]: async_hooks.html |