930 lines
60 KiB
HTML
930 lines
60 KiB
HTML
<!doctype html>
|
|
<html lang="en">
|
|
<head>
|
|
<meta charset="utf-8">
|
|
<meta name="viewport" content="width=device-width">
|
|
<meta name="nodejs.org:node-version" content="v12.22.12">
|
|
<title>Performance measurement APIs | Node.js v12.22.12 Documentation</title>
|
|
<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Lato:400,700,400italic&display=fallback">
|
|
<link rel="stylesheet" href="assets/style.css">
|
|
<link rel="stylesheet" href="assets/hljs.css">
|
|
<link rel="canonical" href="https://nodejs.org/api/perf_hooks.html">
|
|
</head>
|
|
<body class="alt apidoc" id="api-section-perf_hooks">
|
|
<div id="content" class="clearfix">
|
|
<div id="column2" class="interior">
|
|
<div id="intro" class="interior">
|
|
<a href="/" title="Go back to the home page">
|
|
Node.js
|
|
</a>
|
|
</div>
|
|
<ul>
|
|
<li><a href="documentation.html" class="nav-documentation">About this documentation</a></li>
|
|
<li><a href="synopsis.html" class="nav-synopsis">Usage and example</a></li>
|
|
</ul>
|
|
<hr class="line">
|
|
<ul>
|
|
<li><a href="assert.html" class="nav-assert">Assertion testing</a></li>
|
|
<li><a href="async_hooks.html" class="nav-async_hooks">Async hooks</a></li>
|
|
<li><a href="buffer.html" class="nav-buffer">Buffer</a></li>
|
|
<li><a href="addons.html" class="nav-addons">C++ Addons</a></li>
|
|
<li><a href="n-api.html" class="nav-n-api">C/C++ Addons with N-API</a></li>
|
|
<li><a href="embedding.html" class="nav-embedding">C++ Embedder API</a></li>
|
|
<li><a href="child_process.html" class="nav-child_process">Child Processes</a></li>
|
|
<li><a href="cluster.html" class="nav-cluster">Cluster</a></li>
|
|
<li><a href="cli.html" class="nav-cli">Command line options</a></li>
|
|
<li><a href="console.html" class="nav-console">Console</a></li>
|
|
<li><a href="crypto.html" class="nav-crypto">Crypto</a></li>
|
|
<li><a href="debugger.html" class="nav-debugger">Debugger</a></li>
|
|
<li><a href="deprecations.html" class="nav-deprecations">Deprecated APIs</a></li>
|
|
<li><a href="dns.html" class="nav-dns">DNS</a></li>
|
|
<li><a href="domain.html" class="nav-domain">Domain</a></li>
|
|
<li><a href="errors.html" class="nav-errors">Errors</a></li>
|
|
<li><a href="events.html" class="nav-events">Events</a></li>
|
|
<li><a href="fs.html" class="nav-fs">File system</a></li>
|
|
<li><a href="globals.html" class="nav-globals">Globals</a></li>
|
|
<li><a href="http.html" class="nav-http">HTTP</a></li>
|
|
<li><a href="http2.html" class="nav-http2">HTTP/2</a></li>
|
|
<li><a href="https.html" class="nav-https">HTTPS</a></li>
|
|
<li><a href="inspector.html" class="nav-inspector">Inspector</a></li>
|
|
<li><a href="intl.html" class="nav-intl">Internationalization</a></li>
|
|
<li><a href="modules.html" class="nav-modules">Modules: CommonJS modules</a></li>
|
|
<li><a href="esm.html" class="nav-esm">Modules: ECMAScript modules</a></li>
|
|
<li><a href="module.html" class="nav-module">Modules: <code>module</code> API</a></li>
|
|
<li><a href="packages.html" class="nav-packages">Modules: Packages</a></li>
|
|
<li><a href="net.html" class="nav-net">Net</a></li>
|
|
<li><a href="os.html" class="nav-os">OS</a></li>
|
|
<li><a href="path.html" class="nav-path">Path</a></li>
|
|
<li><a href="perf_hooks.html" class="nav-perf_hooks active">Performance hooks</a></li>
|
|
<li><a href="policy.html" class="nav-policy">Policies</a></li>
|
|
<li><a href="process.html" class="nav-process">Process</a></li>
|
|
<li><a href="punycode.html" class="nav-punycode">Punycode</a></li>
|
|
<li><a href="querystring.html" class="nav-querystring">Query strings</a></li>
|
|
<li><a href="readline.html" class="nav-readline">Readline</a></li>
|
|
<li><a href="repl.html" class="nav-repl">REPL</a></li>
|
|
<li><a href="report.html" class="nav-report">Report</a></li>
|
|
<li><a href="stream.html" class="nav-stream">Stream</a></li>
|
|
<li><a href="string_decoder.html" class="nav-string_decoder">String decoder</a></li>
|
|
<li><a href="timers.html" class="nav-timers">Timers</a></li>
|
|
<li><a href="tls.html" class="nav-tls">TLS/SSL</a></li>
|
|
<li><a href="tracing.html" class="nav-tracing">Trace events</a></li>
|
|
<li><a href="tty.html" class="nav-tty">TTY</a></li>
|
|
<li><a href="dgram.html" class="nav-dgram">UDP/datagram</a></li>
|
|
<li><a href="url.html" class="nav-url">URL</a></li>
|
|
<li><a href="util.html" class="nav-util">Utilities</a></li>
|
|
<li><a href="v8.html" class="nav-v8">V8</a></li>
|
|
<li><a href="vm.html" class="nav-vm">VM</a></li>
|
|
<li><a href="wasi.html" class="nav-wasi">WASI</a></li>
|
|
<li><a href="worker_threads.html" class="nav-worker_threads">Worker threads</a></li>
|
|
<li><a href="zlib.html" class="nav-zlib">Zlib</a></li>
|
|
</ul>
|
|
<hr class="line">
|
|
<ul>
|
|
<li><a href="https://github.com/nodejs/node" class="nav-https-github-com-nodejs-node">Code repository and issue tracker</a></li>
|
|
</ul>
|
|
</div>
|
|
|
|
<div id="column1" data-id="perf_hooks" class="interior">
|
|
<header>
|
|
<h1>Node.js v12.22.12 Documentation</h1>
|
|
<div id="gtoc">
|
|
<ul>
|
|
<li>
|
|
<a href="index.html">Index</a>
|
|
</li>
|
|
<li>
|
|
<a href="all.html">View on single page</a>
|
|
</li>
|
|
<li>
|
|
<a href="perf_hooks.json">View as JSON</a>
|
|
</li>
|
|
|
|
<li class="version-picker">
|
|
<a href="#">View another version <span>▼</span></a>
|
|
<ol class="version-picker"><li><a href="https://nodejs.org/docs/latest-v17.x/api/perf_hooks.html">17.x</a></li>
|
|
<li><a href="https://nodejs.org/docs/latest-v16.x/api/perf_hooks.html">16.x <b>LTS</b></a></li>
|
|
<li><a href="https://nodejs.org/docs/latest-v15.x/api/perf_hooks.html">15.x</a></li>
|
|
<li><a href="https://nodejs.org/docs/latest-v14.x/api/perf_hooks.html">14.x <b>LTS</b></a></li>
|
|
<li><a href="https://nodejs.org/docs/latest-v13.x/api/perf_hooks.html">13.x</a></li>
|
|
<li><a href="https://nodejs.org/docs/latest-v12.x/api/perf_hooks.html">12.x <b>LTS</b></a></li>
|
|
<li><a href="https://nodejs.org/docs/latest-v11.x/api/perf_hooks.html">11.x</a></li>
|
|
<li><a href="https://nodejs.org/docs/latest-v10.x/api/perf_hooks.html">10.x</a></li>
|
|
<li><a href="https://nodejs.org/docs/latest-v9.x/api/perf_hooks.html">9.x</a></li>
|
|
<li><a href="https://nodejs.org/docs/latest-v8.x/api/perf_hooks.html">8.x</a></li></ol>
|
|
</li>
|
|
|
|
<li class="edit_on_github"><a href="https://github.com/nodejs/node/edit/master/doc/api/perf_hooks.md"><span class="github_icon"><svg height="16" width="16" viewBox="0 0 16.1 16.1" fill="currentColor"><path d="M8 0a8 8 0 0 0-2.5 15.6c.4 0 .5-.2.5-.4v-1.5c-2 .4-2.5-.5-2.7-1 0-.1-.5-.9-.8-1-.3-.2-.7-.6 0-.6.6 0 1 .6 1.2.8.7 1.2 1.9 1 2.4.7 0-.5.2-.9.5-1-1.8-.3-3.7-1-3.7-4 0-.9.3-1.6.8-2.2 0-.2-.3-1 .1-2 0 0 .7-.3 2.2.7a7.4 7.4 0 0 1 4 0c1.5-1 2.2-.8 2.2-.8.5 1.1.2 2 .1 2.1.5.6.8 1.3.8 2.2 0 3-1.9 3.7-3.6 4 .3.2.5.7.5 1.4v2.2c0 .2.1.5.5.4A8 8 0 0 0 16 8a8 8 0 0 0-8-8z"/></svg></span>Edit on GitHub</a></li>
|
|
</ul>
|
|
</div>
|
|
<hr>
|
|
</header>
|
|
|
|
<div id="toc">
|
|
<h2>Table of Contents</h2>
|
|
<ul>
|
|
<li><span class="stability_2"><a href="#perf_hooks_performance_measurement_apis">Performance measurement APIs</a></span>
|
|
<ul>
|
|
<li><a href="#perf_hooks_perf_hooks_performance"><code>perf_hooks.performance</code></a>
|
|
<ul>
|
|
<li><a href="#perf_hooks_performance_clearmarks_name"><code>performance.clearMarks([name])</code></a></li>
|
|
<li><a href="#perf_hooks_performance_eventlooputilization_utilization1_utilization2"><code>performance.eventLoopUtilization([utilization1[, utilization2]])</code></a></li>
|
|
<li><a href="#perf_hooks_performance_mark_name"><code>performance.mark([name])</code></a></li>
|
|
<li><a href="#perf_hooks_performance_measure_name_startmark_endmark"><code>performance.measure(name[, startMark[, endMark]])</code></a></li>
|
|
<li><a href="#perf_hooks_performance_nodetiming"><code>performance.nodeTiming</code></a></li>
|
|
<li><a href="#perf_hooks_performance_now"><code>performance.now()</code></a></li>
|
|
<li><a href="#perf_hooks_performance_timeorigin"><code>performance.timeOrigin</code></a></li>
|
|
<li><a href="#perf_hooks_performance_timerify_fn"><code>performance.timerify(fn)</code></a></li>
|
|
<li><a href="#perf_hooks_performance_eventlooputilization_util1_util2"><code>performance.eventLoopUtilization([util1][,util2])</code></a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#perf_hooks_class_performanceentry">Class: <code>PerformanceEntry</code></a>
|
|
<ul>
|
|
<li><a href="#perf_hooks_performanceentry_duration"><code>performanceEntry.duration</code></a></li>
|
|
<li><a href="#perf_hooks_performanceentry_name"><code>performanceEntry.name</code></a></li>
|
|
<li><a href="#perf_hooks_performanceentry_starttime"><code>performanceEntry.startTime</code></a></li>
|
|
<li><a href="#perf_hooks_performanceentry_entrytype"><code>performanceEntry.entryType</code></a></li>
|
|
<li><a href="#perf_hooks_performanceentry_kind"><code>performanceEntry.kind</code></a></li>
|
|
<li><a href="#perf_hooks_performanceentry_flags">performanceEntry.flags</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#perf_hooks_class_performancenodetiming_extends_performanceentry">Class: <code>PerformanceNodeTiming extends PerformanceEntry</code></a>
|
|
<ul>
|
|
<li><a href="#perf_hooks_performancenodetiming_bootstrapcomplete"><code>performanceNodeTiming.bootstrapComplete</code></a></li>
|
|
<li><a href="#perf_hooks_performancenodetiming_environment"><code>performanceNodeTiming.environment</code></a></li>
|
|
<li><a href="#perf_hooks_performancenodetiming_loopexit"><code>performanceNodeTiming.loopExit</code></a></li>
|
|
<li><a href="#perf_hooks_performancenodetiming_loopstart"><code>performanceNodeTiming.loopStart</code></a></li>
|
|
<li><a href="#perf_hooks_performancenodetiming_nodestart"><code>performanceNodeTiming.nodeStart</code></a></li>
|
|
<li><a href="#perf_hooks_performancenodetiming_v8start"><code>performanceNodeTiming.v8Start</code></a></li>
|
|
<li><a href="#perf_hooks_performancenodetiming_idletime"><code>performanceNodeTiming.idleTime</code></a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#perf_hooks_class_perf_hooks_performanceobserver">Class: <code>perf_hooks.PerformanceObserver</code></a>
|
|
<ul>
|
|
<li><a href="#perf_hooks_new_performanceobserver_callback"><code>new PerformanceObserver(callback)</code></a></li>
|
|
<li><a href="#perf_hooks_performanceobserver_disconnect"><code>performanceObserver.disconnect()</code></a></li>
|
|
<li><a href="#perf_hooks_performanceobserver_observe_options"><code>performanceObserver.observe(options)</code></a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#perf_hooks_class_performanceobserverentrylist">Class: <code>PerformanceObserverEntryList</code></a>
|
|
<ul>
|
|
<li><a href="#perf_hooks_performanceobserverentrylist_getentries"><code>performanceObserverEntryList.getEntries()</code></a></li>
|
|
<li><a href="#perf_hooks_performanceobserverentrylist_getentriesbyname_name_type"><code>performanceObserverEntryList.getEntriesByName(name[, type])</code></a></li>
|
|
<li><a href="#perf_hooks_performanceobserverentrylist_getentriesbytype_type"><code>performanceObserverEntryList.getEntriesByType(type)</code></a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#perf_hooks_perf_hooks_monitoreventloopdelay_options"><code>perf_hooks.monitorEventLoopDelay([options])</code></a>
|
|
<ul>
|
|
<li><a href="#perf_hooks_class_histogram">Class: <code>Histogram</code></a>
|
|
<ul>
|
|
<li><a href="#perf_hooks_histogram_disable"><code>histogram.disable()</code></a></li>
|
|
<li><a href="#perf_hooks_histogram_enable"><code>histogram.enable()</code></a></li>
|
|
<li><a href="#perf_hooks_histogram_exceeds"><code>histogram.exceeds</code></a></li>
|
|
<li><a href="#perf_hooks_histogram_max"><code>histogram.max</code></a></li>
|
|
<li><a href="#perf_hooks_histogram_mean"><code>histogram.mean</code></a></li>
|
|
<li><a href="#perf_hooks_histogram_min"><code>histogram.min</code></a></li>
|
|
<li><a href="#perf_hooks_histogram_percentile_percentile"><code>histogram.percentile(percentile)</code></a></li>
|
|
<li><a href="#perf_hooks_histogram_percentiles"><code>histogram.percentiles</code></a></li>
|
|
<li><a href="#perf_hooks_histogram_reset"><code>histogram.reset()</code></a></li>
|
|
<li><a href="#perf_hooks_histogram_stddev"><code>histogram.stddev</code></a></li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#perf_hooks_examples">Examples</a>
|
|
<ul>
|
|
<li><a href="#perf_hooks_measuring_the_duration_of_async_operations">Measuring the duration of async operations</a></li>
|
|
<li><a href="#perf_hooks_measuring_how_long_it_takes_to_load_dependencies">Measuring how long it takes to load dependencies</a></li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
</div>
|
|
|
|
<div id="apicontent">
|
|
<h1>Performance measurement APIs<span><a class="mark" href="#perf_hooks_performance_measurement_apis" id="perf_hooks_performance_measurement_apis">#</a></span></h1>
|
|
|
|
<p></p><div class="api_stability api_stability_2"><a href="documentation.html#documentation_stability_index">Stability: 2</a> - Stable</div><p></p>
|
|
<p><strong>Source Code:</strong> <a href="https://github.com/nodejs/node/blob/v12.22.12/lib/perf_hooks.js">lib/perf_hooks.js</a></p>
|
|
<p>This module provides an implementation of a subset of the W3C
|
|
<a href="https://w3c.github.io/perf-timing-primer/">Web Performance APIs</a> as well as additional APIs for
|
|
Node.js-specific performance measurements.</p>
|
|
<p>Node.js supports the following <a href="https://w3c.github.io/perf-timing-primer/">Web Performance APIs</a>:</p>
|
|
<ul>
|
|
<li><a href="https://www.w3.org/TR/hr-time-2">High Resolution Time</a></li>
|
|
<li><a href="https://w3c.github.io/performance-timeline/">Performance Timeline</a></li>
|
|
<li><a href="https://www.w3.org/TR/user-timing/">User Timing</a></li>
|
|
</ul>
|
|
<pre><code class="language-js"><span class="hljs-keyword">const</span> { PerformanceObserver, performance } = <span class="hljs-built_in">require</span>(<span class="hljs-string">'perf_hooks'</span>);
|
|
|
|
<span class="hljs-keyword">const</span> obs = <span class="hljs-keyword">new</span> PerformanceObserver(<span class="hljs-function">(<span class="hljs-params">items</span>) =></span> {
|
|
<span class="hljs-built_in">console</span>.log(items.getEntries()[<span class="hljs-number">0</span>].duration);
|
|
performance.clearMarks();
|
|
});
|
|
obs.observe({ <span class="hljs-attr">entryTypes</span>: [<span class="hljs-string">'measure'</span>] });
|
|
performance.measure(<span class="hljs-string">'Start to Now'</span>);
|
|
|
|
performance.mark(<span class="hljs-string">'A'</span>);
|
|
doSomeLongRunningProcess(<span class="hljs-function">() =></span> {
|
|
performance.measure(<span class="hljs-string">'A to Now'</span>, <span class="hljs-string">'A'</span>);
|
|
|
|
performance.mark(<span class="hljs-string">'B'</span>);
|
|
performance.measure(<span class="hljs-string">'A to B'</span>, <span class="hljs-string">'A'</span>, <span class="hljs-string">'B'</span>);
|
|
});</code></pre>
|
|
<h2><code>perf_hooks.performance</code><span><a class="mark" href="#perf_hooks_perf_hooks_performance" id="perf_hooks_perf_hooks_performance">#</a></span></h2>
|
|
<div class="api_metadata">
|
|
<span>Added in: v8.5.0</span>
|
|
</div>
|
|
<p>An object that can be used to collect performance metrics from the current
|
|
Node.js instance. It is similar to <a href="https://developer.mozilla.org/en-US/docs/Web/API/Window/performance"><code>window.performance</code></a> in browsers.</p>
|
|
<h3><code>performance.clearMarks([name])</code><span><a class="mark" href="#perf_hooks_performance_clearmarks_name" id="perf_hooks_performance_clearmarks_name">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v8.5.0</span>
|
|
</div>
|
|
<ul>
|
|
<li><code>name</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li>
|
|
</ul>
|
|
<p>If <code>name</code> is not provided, removes all <code>PerformanceMark</code> objects from the
|
|
Performance Timeline. If <code>name</code> is provided, removes only the named mark.</p>
|
|
<h3><code>performance.eventLoopUtilization([utilization1[, utilization2]])</code><span><a class="mark" href="#perf_hooks_performance_eventlooputilization_utilization1_utilization2" id="perf_hooks_performance_eventlooputilization_utilization1_utilization2">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v14.10.0, v12.19.0</span>
|
|
</div>
|
|
<ul>
|
|
<li><code>utilization1</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> The result of a previous call to
|
|
<code>eventLoopUtilization()</code>.</li>
|
|
<li><code>utilization2</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> The result of a previous call to
|
|
<code>eventLoopUtilization()</code> prior to <code>utilization1</code>.</li>
|
|
<li>Returns <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a>
|
|
<ul>
|
|
<li><code>idle</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a></li>
|
|
<li><code>active</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a></li>
|
|
<li><code>utilization</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a></li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
<p>The <code>eventLoopUtilization()</code> 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 <code>utilization</code> value is the calculated
|
|
Event Loop Utilization (ELU).</p>
|
|
<p>If bootstrapping has not yet finished on the main thread the properties have
|
|
the value of <code>0</code>. The ELU is immediately available on <a href="worker_threads.md#worker_threads_worker_threads">Worker threads</a> since
|
|
bootstrap happens within the event loop.</p>
|
|
<p>Both <code>utilization1</code> and <code>utilization2</code> are optional parameters.</p>
|
|
<p>If <code>utilization1</code> is passed, then the delta between the current call's <code>active</code>
|
|
and <code>idle</code> times, as well as the corresponding <code>utilization</code> value are
|
|
calculated and returned (similar to <a href="process.html#process_process_hrtime_time"><code>process.hrtime()</code></a>).</p>
|
|
<p>If <code>utilization1</code> and <code>utilization2</code> are both passed, then the delta is
|
|
calculated between the two arguments. This is a convenience option because,
|
|
unlike <a href="process.html#process_process_hrtime_time"><code>process.hrtime()</code></a>, calculating the ELU is more complex than a
|
|
single subtraction.</p>
|
|
<p>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. <code>epoll_wait</code>).
|
|
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.</p>
|
|
<pre><code class="language-js"><span class="hljs-meta">'use strict'</span>;
|
|
<span class="hljs-keyword">const</span> { eventLoopUtilization } = <span class="hljs-built_in">require</span>(<span class="hljs-string">'perf_hooks'</span>).performance;
|
|
<span class="hljs-keyword">const</span> { spawnSync } = <span class="hljs-built_in">require</span>(<span class="hljs-string">'child_process'</span>);
|
|
|
|
setImmediate(<span class="hljs-function">() =></span> {
|
|
<span class="hljs-keyword">const</span> elu = eventLoopUtilization();
|
|
spawnSync(<span class="hljs-string">'sleep'</span>, [<span class="hljs-string">'5'</span>]);
|
|
<span class="hljs-built_in">console</span>.log(eventLoopUtilization(elu).utilization);
|
|
});</code></pre>
|
|
<p>Although the CPU is mostly idle while running this script, the value of
|
|
<code>utilization</code> is <code>1</code>. This is because the call to
|
|
<a href="child_process.html#child_process_child_process_spawnsync_command_args_options"><code>child_process.spawnSync()</code></a> blocks the event loop from proceeding.</p>
|
|
<p>Passing in a user-defined object instead of the result of a previous call to
|
|
<code>eventLoopUtilization()</code> will lead to undefined behavior. The return values
|
|
are not guaranteed to reflect any correct state of the event loop.</p>
|
|
<h3><code>performance.mark([name])</code><span><a class="mark" href="#perf_hooks_performance_mark_name" id="perf_hooks_performance_mark_name">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v8.5.0</span>
|
|
</div>
|
|
<ul>
|
|
<li><code>name</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li>
|
|
</ul>
|
|
<p>Creates a new <code>PerformanceMark</code> entry in the Performance Timeline. A
|
|
<code>PerformanceMark</code> is a subclass of <code>PerformanceEntry</code> whose
|
|
<code>performanceEntry.entryType</code> is always <code>'mark'</code>, and whose
|
|
<code>performanceEntry.duration</code> is always <code>0</code>. Performance marks are used
|
|
to mark specific significant moments in the Performance Timeline.</p>
|
|
<h3><code>performance.measure(name[, startMark[, endMark]])</code><span><a class="mark" href="#perf_hooks_performance_measure_name_startmark_endmark" id="perf_hooks_performance_measure_name_startmark_endmark">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<details class="changelog"><summary>History</summary>
|
|
<table>
|
|
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
|
<tr><td>v12.16.3</td>
|
|
<td><p>Make <code>startMark</code> and <code>endMark</code> parameters optional.</p></td></tr>
|
|
<tr><td>v8.5.0</td>
|
|
<td><p><span>Added in: v8.5.0</span></p></td></tr>
|
|
</tbody></table>
|
|
</details>
|
|
</div>
|
|
<ul>
|
|
<li><code>name</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li>
|
|
<li><code>startMark</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> Optional.</li>
|
|
<li><code>endMark</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> Optional.</li>
|
|
</ul>
|
|
<p>Creates a new <code>PerformanceMeasure</code> entry in the Performance Timeline. A
|
|
<code>PerformanceMeasure</code> is a subclass of <code>PerformanceEntry</code> whose
|
|
<code>performanceEntry.entryType</code> is always <code>'measure'</code>, and whose
|
|
<code>performanceEntry.duration</code> measures the number of milliseconds elapsed since
|
|
<code>startMark</code> and <code>endMark</code>.</p>
|
|
<p>The <code>startMark</code> argument may identify any <em>existing</em> <code>PerformanceMark</code> in the
|
|
Performance Timeline, or <em>may</em> identify any of the timestamp properties
|
|
provided by the <code>PerformanceNodeTiming</code> class. If the named <code>startMark</code> does
|
|
not exist, then <code>startMark</code> is set to <a href="https://w3c.github.io/hr-time/#dom-performance-timeorigin"><code>timeOrigin</code></a> by default.</p>
|
|
<p>The optional <code>endMark</code> argument must identify any <em>existing</em> <code>PerformanceMark</code>
|
|
in the Performance Timeline or any of the timestamp properties provided by the
|
|
<code>PerformanceNodeTiming</code> class. <code>endMark</code> will be <code>performance.now()</code>
|
|
if no parameter is passed, otherwise if the named <code>endMark</code> does not exist, an
|
|
error will be thrown.</p>
|
|
<h3><code>performance.nodeTiming</code><span><a class="mark" href="#perf_hooks_performance_nodetiming" id="perf_hooks_performance_nodetiming">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v8.5.0</span>
|
|
</div>
|
|
<ul>
|
|
<li><a href="perf_hooks.html#perf_hooks_class_performancenodetiming_extends_performanceentry" class="type"><PerformanceNodeTiming></a></li>
|
|
</ul>
|
|
<p><em>This property is an extension by Node.js. It is not available in Web browsers.</em></p>
|
|
<p>An instance of the <code>PerformanceNodeTiming</code> class that provides performance
|
|
metrics for specific Node.js operational milestones.</p>
|
|
<h3><code>performance.now()</code><span><a class="mark" href="#perf_hooks_performance_now" id="perf_hooks_performance_now">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v8.5.0</span>
|
|
</div>
|
|
<ul>
|
|
<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a></li>
|
|
</ul>
|
|
<p>Returns the current high resolution millisecond timestamp, where 0 represents
|
|
the start of the current <code>node</code> process.</p>
|
|
<h3><code>performance.timeOrigin</code><span><a class="mark" href="#perf_hooks_performance_timeorigin" id="perf_hooks_performance_timeorigin">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v8.5.0</span>
|
|
</div>
|
|
<ul>
|
|
<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a></li>
|
|
</ul>
|
|
<p>The <a href="https://w3c.github.io/hr-time/#dom-performance-timeorigin"><code>timeOrigin</code></a> specifies the high resolution millisecond timestamp at
|
|
which the current <code>node</code> process began, measured in Unix time.</p>
|
|
<h3><code>performance.timerify(fn)</code><span><a class="mark" href="#perf_hooks_performance_timerify_fn" id="perf_hooks_performance_timerify_fn">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v8.5.0</span>
|
|
</div>
|
|
<ul>
|
|
<li><code>fn</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a></li>
|
|
</ul>
|
|
<p><em>This property is an extension by Node.js. It is not available in Web browsers.</em></p>
|
|
<p>Wraps a function within a new function that measures the running time of the
|
|
wrapped function. A <code>PerformanceObserver</code> must be subscribed to the <code>'function'</code>
|
|
event type in order for the timing details to be accessed.</p>
|
|
<pre><code class="language-js"><span class="hljs-keyword">const</span> {
|
|
performance,
|
|
PerformanceObserver
|
|
} = <span class="hljs-built_in">require</span>(<span class="hljs-string">'perf_hooks'</span>);
|
|
|
|
<span class="hljs-function"><span class="hljs-keyword">function</span> <span class="hljs-title">someFunction</span>(<span class="hljs-params"></span>) </span>{
|
|
<span class="hljs-built_in">console</span>.log(<span class="hljs-string">'hello world'</span>);
|
|
}
|
|
|
|
<span class="hljs-keyword">const</span> wrapped = performance.timerify(someFunction);
|
|
|
|
<span class="hljs-keyword">const</span> obs = <span class="hljs-keyword">new</span> PerformanceObserver(<span class="hljs-function">(<span class="hljs-params">list</span>) =></span> {
|
|
<span class="hljs-built_in">console</span>.log(list.getEntries()[<span class="hljs-number">0</span>].duration);
|
|
obs.disconnect();
|
|
});
|
|
obs.observe({ <span class="hljs-attr">entryTypes</span>: [<span class="hljs-string">'function'</span>] });
|
|
|
|
<span class="hljs-comment">// A performance timeline entry will be created</span>
|
|
wrapped();</code></pre>
|
|
<h3><code>performance.eventLoopUtilization([util1][,util2])</code><span><a class="mark" href="#perf_hooks_performance_eventlooputilization_util1_util2" id="perf_hooks_performance_eventlooputilization_util1_util2">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v12.19.0</span>
|
|
</div>
|
|
<ul>
|
|
<li><code>util1</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> The result of a previous call to <code>eventLoopUtilization()</code></li>
|
|
<li><code>util2</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> The result of a previous call to <code>eventLoopUtilization()</code>
|
|
prior to <code>util1</code></li>
|
|
<li>Returns <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a>
|
|
<ul>
|
|
<li><code>idle</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a></li>
|
|
<li><code>active</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a></li>
|
|
<li><code>utilization</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a></li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
<p>The <code>eventLoopUtilization()</code> 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 <code>utilization</code> value is the calculated
|
|
Event Loop Utilization (ELU). If bootstrapping has not yet finished, the
|
|
properties have the value of 0.</p>
|
|
<p><code>util1</code> and <code>util2</code> are optional parameters.</p>
|
|
<p>If <code>util1</code> is passed then the delta between the current call's <code>active</code> and
|
|
<code>idle</code> times are calculated and returned (similar to <a href="process.html#process_process_hrtime_time"><code>process.hrtime()</code></a>).
|
|
Likewise the adjusted <code>utilization</code> value is calculated.</p>
|
|
<p>If <code>util1</code> and <code>util2</code> are both passed then the calculation adjustments are
|
|
done between the two arguments. This is a convenience option because unlike
|
|
<a href="process.html#process_process_hrtime_time"><code>process.hrtime()</code></a> additional work is done to calculate the ELU.</p>
|
|
<p>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. <code>epoll_wait</code>). 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.</p>
|
|
<!-- eslint-skip -->
|
|
<pre><code class="language-js"><span class="hljs-meta">'use strict'</span>;
|
|
<span class="hljs-keyword">const</span> { eventLoopUtilization } = <span class="hljs-built_in">require</span>(<span class="hljs-string">'perf_hooks'</span>).performance;
|
|
<span class="hljs-keyword">const</span> { spawnSync } = <span class="hljs-built_in">require</span>(<span class="hljs-string">'child_process'</span>);
|
|
|
|
setImmediate(<span class="hljs-function">() =></span> {
|
|
<span class="hljs-keyword">const</span> elu = eventLoopUtilization();
|
|
spawnSync(<span class="hljs-string">'sleep'</span>, [<span class="hljs-string">'5'</span>]);
|
|
<span class="hljs-built_in">console</span>.log(eventLoopUtilization(elu).utilization);
|
|
});</code></pre>
|
|
<p>Although the CPU is mostly idle while running this script, the value of
|
|
<code>utilization</code> is 1. This is because the call to <a href="child_process.html#child_process_child_process_spawnsync_command_args_options"><code>child_process.spawnSync()</code></a>
|
|
blocks the event loop from proceeding.</p>
|
|
<p>Passing in a user-defined object instead of the result of a previous call to
|
|
<code>eventLoopUtilization()</code> will lead to undefined behavior. The return values
|
|
are not guaranteed to reflect any correct state of the event loop.</p>
|
|
<h2>Class: <code>PerformanceEntry</code><span><a class="mark" href="#perf_hooks_class_performanceentry" id="perf_hooks_class_performanceentry">#</a></span></h2>
|
|
<div class="api_metadata">
|
|
<span>Added in: v8.5.0</span>
|
|
</div>
|
|
<h3><code>performanceEntry.duration</code><span><a class="mark" href="#perf_hooks_performanceentry_duration" id="perf_hooks_performanceentry_duration">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v8.5.0</span>
|
|
</div>
|
|
<ul>
|
|
<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a></li>
|
|
</ul>
|
|
<p>The total number of milliseconds elapsed for this entry. This value will not
|
|
be meaningful for all Performance Entry types.</p>
|
|
<h3><code>performanceEntry.name</code><span><a class="mark" href="#perf_hooks_performanceentry_name" id="perf_hooks_performanceentry_name">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v8.5.0</span>
|
|
</div>
|
|
<ul>
|
|
<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li>
|
|
</ul>
|
|
<p>The name of the performance entry.</p>
|
|
<h3><code>performanceEntry.startTime</code><span><a class="mark" href="#perf_hooks_performanceentry_starttime" id="perf_hooks_performanceentry_starttime">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v8.5.0</span>
|
|
</div>
|
|
<ul>
|
|
<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a></li>
|
|
</ul>
|
|
<p>The high resolution millisecond timestamp marking the starting time of the
|
|
Performance Entry.</p>
|
|
<h3><code>performanceEntry.entryType</code><span><a class="mark" href="#perf_hooks_performanceentry_entrytype" id="perf_hooks_performanceentry_entrytype">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v8.5.0</span>
|
|
</div>
|
|
<ul>
|
|
<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li>
|
|
</ul>
|
|
<p>The type of the performance entry. It may be one of:</p>
|
|
<ul>
|
|
<li><code>'node'</code> (Node.js only)</li>
|
|
<li><code>'mark'</code> (available on the Web)</li>
|
|
<li><code>'measure'</code> (available on the Web)</li>
|
|
<li><code>'gc'</code> (Node.js only)</li>
|
|
<li><code>'function'</code> (Node.js only)</li>
|
|
<li><code>'http2'</code> (Node.js only)</li>
|
|
<li><code>'http'</code> (Node.js only)</li>
|
|
</ul>
|
|
<h3><code>performanceEntry.kind</code><span><a class="mark" href="#perf_hooks_performanceentry_kind" id="perf_hooks_performanceentry_kind">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v8.5.0</span>
|
|
</div>
|
|
<ul>
|
|
<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a></li>
|
|
</ul>
|
|
<p><em>This property is an extension by Node.js. It is not available in Web browsers.</em></p>
|
|
<p>When <code>performanceEntry.entryType</code> is equal to <code>'gc'</code>, the <code>performance.kind</code>
|
|
property identifies the type of garbage collection operation that occurred.
|
|
The value may be one of:</p>
|
|
<ul>
|
|
<li><code>perf_hooks.constants.NODE_PERFORMANCE_GC_MAJOR</code></li>
|
|
<li><code>perf_hooks.constants.NODE_PERFORMANCE_GC_MINOR</code></li>
|
|
<li><code>perf_hooks.constants.NODE_PERFORMANCE_GC_INCREMENTAL</code></li>
|
|
<li><code>perf_hooks.constants.NODE_PERFORMANCE_GC_WEAKCB</code></li>
|
|
</ul>
|
|
<h3>performanceEntry.flags<span><a class="mark" href="#perf_hooks_performanceentry_flags" id="perf_hooks_performanceentry_flags">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v12.17.0</span>
|
|
</div>
|
|
<ul>
|
|
<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a></li>
|
|
</ul>
|
|
<p><em>This property is an extension by Node.js. It is not available in Web browsers.</em></p>
|
|
<p>When <code>performanceEntry.entryType</code> is equal to <code>'gc'</code>, the <code>performance.flags</code>
|
|
property contains additional information about garbage collection operation.
|
|
The value may be one of:</p>
|
|
<ul>
|
|
<li><code>perf_hooks.constants.NODE_PERFORMANCE_GC_FLAGS_NO</code></li>
|
|
<li><code>perf_hooks.constants.NODE_PERFORMANCE_GC_FLAGS_CONSTRUCT_RETAINED</code></li>
|
|
<li><code>perf_hooks.constants.NODE_PERFORMANCE_GC_FLAGS_FORCED</code></li>
|
|
<li><code>perf_hooks.constants.NODE_PERFORMANCE_GC_FLAGS_SYNCHRONOUS_PHANTOM_PROCESSING</code></li>
|
|
<li><code>perf_hooks.constants.NODE_PERFORMANCE_GC_FLAGS_ALL_AVAILABLE_GARBAGE</code></li>
|
|
<li><code>perf_hooks.constants.NODE_PERFORMANCE_GC_FLAGS_ALL_EXTERNAL_MEMORY</code></li>
|
|
<li><code>perf_hooks.constants.NODE_PERFORMANCE_GC_FLAGS_SCHEDULE_IDLE</code></li>
|
|
</ul>
|
|
<h2>Class: <code>PerformanceNodeTiming extends PerformanceEntry</code><span><a class="mark" href="#perf_hooks_class_performancenodetiming_extends_performanceentry" id="perf_hooks_class_performancenodetiming_extends_performanceentry">#</a></span></h2>
|
|
<div class="api_metadata">
|
|
<span>Added in: v8.5.0</span>
|
|
</div>
|
|
<p><em>This property is an extension by Node.js. It is not available in Web browsers.</em></p>
|
|
<p>Provides timing details for Node.js itself. The constructor of this class
|
|
is not exposed to users.</p>
|
|
<h3><code>performanceNodeTiming.bootstrapComplete</code><span><a class="mark" href="#perf_hooks_performancenodetiming_bootstrapcomplete" id="perf_hooks_performancenodetiming_bootstrapcomplete">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v8.5.0</span>
|
|
</div>
|
|
<ul>
|
|
<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a></li>
|
|
</ul>
|
|
<p>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.</p>
|
|
<h3><code>performanceNodeTiming.environment</code><span><a class="mark" href="#perf_hooks_performancenodetiming_environment" id="perf_hooks_performancenodetiming_environment">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v8.5.0</span>
|
|
</div>
|
|
<ul>
|
|
<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a></li>
|
|
</ul>
|
|
<p>The high resolution millisecond timestamp at which the Node.js environment was
|
|
initialized.</p>
|
|
<h3><code>performanceNodeTiming.loopExit</code><span><a class="mark" href="#perf_hooks_performancenodetiming_loopexit" id="perf_hooks_performancenodetiming_loopexit">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v8.5.0</span>
|
|
</div>
|
|
<ul>
|
|
<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a></li>
|
|
</ul>
|
|
<p>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 <a href="process.html#process_event_exit"><code>'exit'</code></a> event.</p>
|
|
<h3><code>performanceNodeTiming.loopStart</code><span><a class="mark" href="#perf_hooks_performancenodetiming_loopstart" id="perf_hooks_performancenodetiming_loopstart">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v8.5.0</span>
|
|
</div>
|
|
<ul>
|
|
<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a></li>
|
|
</ul>
|
|
<p>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.</p>
|
|
<h3><code>performanceNodeTiming.nodeStart</code><span><a class="mark" href="#perf_hooks_performancenodetiming_nodestart" id="perf_hooks_performancenodetiming_nodestart">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v8.5.0</span>
|
|
</div>
|
|
<ul>
|
|
<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a></li>
|
|
</ul>
|
|
<p>The high resolution millisecond timestamp at which the Node.js process was
|
|
initialized.</p>
|
|
<h3><code>performanceNodeTiming.v8Start</code><span><a class="mark" href="#perf_hooks_performancenodetiming_v8start" id="perf_hooks_performancenodetiming_v8start">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v8.5.0</span>
|
|
</div>
|
|
<ul>
|
|
<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a></li>
|
|
</ul>
|
|
<p>The high resolution millisecond timestamp at which the V8 platform was
|
|
initialized.</p>
|
|
<h3><code>performanceNodeTiming.idleTime</code><span><a class="mark" href="#perf_hooks_performancenodetiming_idletime" id="perf_hooks_performancenodetiming_idletime">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v12.19.0</span>
|
|
</div>
|
|
<ul>
|
|
<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a></li>
|
|
</ul>
|
|
<p>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. <code>epoll_wait</code>). 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.</p>
|
|
<h2>Class: <code>perf_hooks.PerformanceObserver</code><span><a class="mark" href="#perf_hooks_class_perf_hooks_performanceobserver" id="perf_hooks_class_perf_hooks_performanceobserver">#</a></span></h2>
|
|
<h3><code>new PerformanceObserver(callback)</code><span><a class="mark" href="#perf_hooks_new_performanceobserver_callback" id="perf_hooks_new_performanceobserver_callback">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v8.5.0</span>
|
|
</div>
|
|
<ul>
|
|
<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a>
|
|
<ul>
|
|
<li><code>list</code> <a href="perf_hooks.html#perf_hooks_class_performanceobserverentrylist" class="type"><PerformanceObserverEntryList></a></li>
|
|
<li><code>observer</code> <a href="perf_hooks.html#perf_hooks_class_perf_hooks_performanceobserver" class="type"><PerformanceObserver></a></li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
<p><code>PerformanceObserver</code> objects provide notifications when new
|
|
<code>PerformanceEntry</code> instances have been added to the Performance Timeline.</p>
|
|
<pre><code class="language-js"><span class="hljs-keyword">const</span> {
|
|
performance,
|
|
PerformanceObserver
|
|
} = <span class="hljs-built_in">require</span>(<span class="hljs-string">'perf_hooks'</span>);
|
|
|
|
<span class="hljs-keyword">const</span> obs = <span class="hljs-keyword">new</span> PerformanceObserver(<span class="hljs-function">(<span class="hljs-params">list, observer</span>) =></span> {
|
|
<span class="hljs-built_in">console</span>.log(list.getEntries());
|
|
observer.disconnect();
|
|
});
|
|
obs.observe({ <span class="hljs-attr">entryTypes</span>: [<span class="hljs-string">'mark'</span>], <span class="hljs-attr">buffered</span>: <span class="hljs-literal">true</span> });
|
|
|
|
performance.mark(<span class="hljs-string">'test'</span>);</code></pre>
|
|
<p>Because <code>PerformanceObserver</code> 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.</p>
|
|
<p>The <code>callback</code> is invoked when a <code>PerformanceObserver</code> is
|
|
notified about new <code>PerformanceEntry</code> instances. The callback receives a
|
|
<code>PerformanceObserverEntryList</code> instance and a reference to the
|
|
<code>PerformanceObserver</code>.</p>
|
|
<h3><code>performanceObserver.disconnect()</code><span><a class="mark" href="#perf_hooks_performanceobserver_disconnect" id="perf_hooks_performanceobserver_disconnect">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v8.5.0</span>
|
|
</div>
|
|
<p>Disconnects the <code>PerformanceObserver</code> instance from all notifications.</p>
|
|
<h3><code>performanceObserver.observe(options)</code><span><a class="mark" href="#perf_hooks_performanceobserver_observe_options" id="perf_hooks_performanceobserver_observe_options">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v8.5.0</span>
|
|
</div>
|
|
<ul>
|
|
<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a>
|
|
<ul>
|
|
<li><code>entryTypes</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string[]></a> An array of strings identifying the types of
|
|
<code>PerformanceEntry</code> instances the observer is interested in. If not
|
|
provided an error will be thrown.</li>
|
|
<li><code>buffered</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> If true, the notification callback will be
|
|
called using <code>setImmediate()</code> and multiple <code>PerformanceEntry</code> instance
|
|
notifications will be buffered internally. If <code>false</code>, notifications will
|
|
be immediate and synchronous. <strong>Default:</strong> <code>false</code>.</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
<p>Subscribes the <code>PerformanceObserver</code> instance to notifications of new
|
|
<code>PerformanceEntry</code> instances identified by <code>options.entryTypes</code>.</p>
|
|
<p>When <code>options.buffered</code> is <code>false</code>, the <code>callback</code> will be invoked once for
|
|
every <code>PerformanceEntry</code> instance:</p>
|
|
<pre><code class="language-js"><span class="hljs-keyword">const</span> {
|
|
performance,
|
|
PerformanceObserver
|
|
} = <span class="hljs-built_in">require</span>(<span class="hljs-string">'perf_hooks'</span>);
|
|
|
|
<span class="hljs-keyword">const</span> obs = <span class="hljs-keyword">new</span> PerformanceObserver(<span class="hljs-function">(<span class="hljs-params">list, observer</span>) =></span> {
|
|
<span class="hljs-comment">// Called three times synchronously. `list` contains one item.</span>
|
|
});
|
|
obs.observe({ <span class="hljs-attr">entryTypes</span>: [<span class="hljs-string">'mark'</span>] });
|
|
|
|
<span class="hljs-keyword">for</span> (<span class="hljs-keyword">let</span> n = <span class="hljs-number">0</span>; n < <span class="hljs-number">3</span>; n++)
|
|
performance.mark(<span class="hljs-string">`test<span class="hljs-subst">${n}</span>`</span>);</code></pre>
|
|
<pre><code class="language-js"><span class="hljs-keyword">const</span> {
|
|
performance,
|
|
PerformanceObserver
|
|
} = <span class="hljs-built_in">require</span>(<span class="hljs-string">'perf_hooks'</span>);
|
|
|
|
<span class="hljs-keyword">const</span> obs = <span class="hljs-keyword">new</span> PerformanceObserver(<span class="hljs-function">(<span class="hljs-params">list, observer</span>) =></span> {
|
|
<span class="hljs-comment">// Called once. `list` contains three items.</span>
|
|
});
|
|
obs.observe({ <span class="hljs-attr">entryTypes</span>: [<span class="hljs-string">'mark'</span>], <span class="hljs-attr">buffered</span>: <span class="hljs-literal">true</span> });
|
|
|
|
<span class="hljs-keyword">for</span> (<span class="hljs-keyword">let</span> n = <span class="hljs-number">0</span>; n < <span class="hljs-number">3</span>; n++)
|
|
performance.mark(<span class="hljs-string">`test<span class="hljs-subst">${n}</span>`</span>);</code></pre>
|
|
<h2>Class: <code>PerformanceObserverEntryList</code><span><a class="mark" href="#perf_hooks_class_performanceobserverentrylist" id="perf_hooks_class_performanceobserverentrylist">#</a></span></h2>
|
|
<div class="api_metadata">
|
|
<span>Added in: v8.5.0</span>
|
|
</div>
|
|
<p>The <code>PerformanceObserverEntryList</code> class is used to provide access to the
|
|
<code>PerformanceEntry</code> instances passed to a <code>PerformanceObserver</code>.
|
|
The constructor of this class is not exposed to users.</p>
|
|
<h3><code>performanceObserverEntryList.getEntries()</code><span><a class="mark" href="#perf_hooks_performanceobserverentrylist_getentries" id="perf_hooks_performanceobserverentrylist_getentries">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v8.5.0</span>
|
|
</div>
|
|
<ul>
|
|
<li>Returns: <a href="perf_hooks.html#perf_hooks_class_performanceentry" class="type"><PerformanceEntry[]></a></li>
|
|
</ul>
|
|
<p>Returns a list of <code>PerformanceEntry</code> objects in chronological order
|
|
with respect to <code>performanceEntry.startTime</code>.</p>
|
|
<h3><code>performanceObserverEntryList.getEntriesByName(name[, type])</code><span><a class="mark" href="#perf_hooks_performanceobserverentrylist_getentriesbyname_name_type" id="perf_hooks_performanceobserverentrylist_getentriesbyname_name_type">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v8.5.0</span>
|
|
</div>
|
|
<ul>
|
|
<li><code>name</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li>
|
|
<li><code>type</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li>
|
|
<li>Returns: <a href="perf_hooks.html#perf_hooks_class_performanceentry" class="type"><PerformanceEntry[]></a></li>
|
|
</ul>
|
|
<p>Returns a list of <code>PerformanceEntry</code> objects in chronological order
|
|
with respect to <code>performanceEntry.startTime</code> whose <code>performanceEntry.name</code> is
|
|
equal to <code>name</code>, and optionally, whose <code>performanceEntry.entryType</code> is equal to
|
|
<code>type</code>.</p>
|
|
<h3><code>performanceObserverEntryList.getEntriesByType(type)</code><span><a class="mark" href="#perf_hooks_performanceobserverentrylist_getentriesbytype_type" id="perf_hooks_performanceobserverentrylist_getentriesbytype_type">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v8.5.0</span>
|
|
</div>
|
|
<ul>
|
|
<li><code>type</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li>
|
|
<li>Returns: <a href="perf_hooks.html#perf_hooks_class_performanceentry" class="type"><PerformanceEntry[]></a></li>
|
|
</ul>
|
|
<p>Returns a list of <code>PerformanceEntry</code> objects in chronological order
|
|
with respect to <code>performanceEntry.startTime</code> whose <code>performanceEntry.entryType</code>
|
|
is equal to <code>type</code>.</p>
|
|
<h2><code>perf_hooks.monitorEventLoopDelay([options])</code><span><a class="mark" href="#perf_hooks_perf_hooks_monitoreventloopdelay_options" id="perf_hooks_perf_hooks_monitoreventloopdelay_options">#</a></span></h2>
|
|
<div class="api_metadata">
|
|
<span>Added in: v11.10.0</span>
|
|
</div>
|
|
<ul>
|
|
<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a>
|
|
<ul>
|
|
<li><code>resolution</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> The sampling rate in milliseconds. Must be greater
|
|
than zero. <strong>Default:</strong> <code>10</code>.</li>
|
|
</ul>
|
|
</li>
|
|
<li>Returns: <a href="perf_hooks.html#perf_hooks_class_histogram" class="type"><Histogram></a></li>
|
|
</ul>
|
|
<p><em>This property is an extension by Node.js. It is not available in Web browsers.</em></p>
|
|
<p>Creates a <code>Histogram</code> object that samples and reports the event loop delay
|
|
over time. The delays will be reported in nanoseconds.</p>
|
|
<p>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.</p>
|
|
<pre><code class="language-js"><span class="hljs-keyword">const</span> { monitorEventLoopDelay } = <span class="hljs-built_in">require</span>(<span class="hljs-string">'perf_hooks'</span>);
|
|
<span class="hljs-keyword">const</span> h = monitorEventLoopDelay({ <span class="hljs-attr">resolution</span>: <span class="hljs-number">20</span> });
|
|
h.enable();
|
|
<span class="hljs-comment">// Do something.</span>
|
|
h.disable();
|
|
<span class="hljs-built_in">console</span>.log(h.min);
|
|
<span class="hljs-built_in">console</span>.log(h.max);
|
|
<span class="hljs-built_in">console</span>.log(h.mean);
|
|
<span class="hljs-built_in">console</span>.log(h.stddev);
|
|
<span class="hljs-built_in">console</span>.log(h.percentiles);
|
|
<span class="hljs-built_in">console</span>.log(h.percentile(<span class="hljs-number">50</span>));
|
|
<span class="hljs-built_in">console</span>.log(h.percentile(<span class="hljs-number">99</span>));</code></pre>
|
|
<h3>Class: <code>Histogram</code><span><a class="mark" href="#perf_hooks_class_histogram" id="perf_hooks_class_histogram">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v11.10.0</span>
|
|
</div>
|
|
<p>Tracks the event loop delay at a given sampling rate. The constructor of
|
|
this class not exposed to users.</p>
|
|
<p><em>This property is an extension by Node.js. It is not available in Web browsers.</em></p>
|
|
<h4><code>histogram.disable()</code><span><a class="mark" href="#perf_hooks_histogram_disable" id="perf_hooks_histogram_disable">#</a></span></h4>
|
|
<div class="api_metadata">
|
|
<span>Added in: v11.10.0</span>
|
|
</div>
|
|
<ul>
|
|
<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a></li>
|
|
</ul>
|
|
<p>Disables the event loop delay sample timer. Returns <code>true</code> if the timer was
|
|
stopped, <code>false</code> if it was already stopped.</p>
|
|
<h4><code>histogram.enable()</code><span><a class="mark" href="#perf_hooks_histogram_enable" id="perf_hooks_histogram_enable">#</a></span></h4>
|
|
<div class="api_metadata">
|
|
<span>Added in: v11.10.0</span>
|
|
</div>
|
|
<ul>
|
|
<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a></li>
|
|
</ul>
|
|
<p>Enables the event loop delay sample timer. Returns <code>true</code> if the timer was
|
|
started, <code>false</code> if it was already started.</p>
|
|
<h4><code>histogram.exceeds</code><span><a class="mark" href="#perf_hooks_histogram_exceeds" id="perf_hooks_histogram_exceeds">#</a></span></h4>
|
|
<div class="api_metadata">
|
|
<span>Added in: v11.10.0</span>
|
|
</div>
|
|
<ul>
|
|
<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a></li>
|
|
</ul>
|
|
<p>The number of times the event loop delay exceeded the maximum 1 hour event
|
|
loop delay threshold.</p>
|
|
<h4><code>histogram.max</code><span><a class="mark" href="#perf_hooks_histogram_max" id="perf_hooks_histogram_max">#</a></span></h4>
|
|
<div class="api_metadata">
|
|
<span>Added in: v11.10.0</span>
|
|
</div>
|
|
<ul>
|
|
<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a></li>
|
|
</ul>
|
|
<p>The maximum recorded event loop delay.</p>
|
|
<h4><code>histogram.mean</code><span><a class="mark" href="#perf_hooks_histogram_mean" id="perf_hooks_histogram_mean">#</a></span></h4>
|
|
<div class="api_metadata">
|
|
<span>Added in: v11.10.0</span>
|
|
</div>
|
|
<ul>
|
|
<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a></li>
|
|
</ul>
|
|
<p>The mean of the recorded event loop delays.</p>
|
|
<h4><code>histogram.min</code><span><a class="mark" href="#perf_hooks_histogram_min" id="perf_hooks_histogram_min">#</a></span></h4>
|
|
<div class="api_metadata">
|
|
<span>Added in: v11.10.0</span>
|
|
</div>
|
|
<ul>
|
|
<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a></li>
|
|
</ul>
|
|
<p>The minimum recorded event loop delay.</p>
|
|
<h4><code>histogram.percentile(percentile)</code><span><a class="mark" href="#perf_hooks_histogram_percentile_percentile" id="perf_hooks_histogram_percentile_percentile">#</a></span></h4>
|
|
<div class="api_metadata">
|
|
<span>Added in: v11.10.0</span>
|
|
</div>
|
|
<ul>
|
|
<li><code>percentile</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> A percentile value between 1 and 100.</li>
|
|
<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a></li>
|
|
</ul>
|
|
<p>Returns the value at the given percentile.</p>
|
|
<h4><code>histogram.percentiles</code><span><a class="mark" href="#perf_hooks_histogram_percentiles" id="perf_hooks_histogram_percentiles">#</a></span></h4>
|
|
<div class="api_metadata">
|
|
<span>Added in: v11.10.0</span>
|
|
</div>
|
|
<ul>
|
|
<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map" class="type"><Map></a></li>
|
|
</ul>
|
|
<p>Returns a <code>Map</code> object detailing the accumulated percentile distribution.</p>
|
|
<h4><code>histogram.reset()</code><span><a class="mark" href="#perf_hooks_histogram_reset" id="perf_hooks_histogram_reset">#</a></span></h4>
|
|
<div class="api_metadata">
|
|
<span>Added in: v11.10.0</span>
|
|
</div>
|
|
<p>Resets the collected histogram data.</p>
|
|
<h4><code>histogram.stddev</code><span><a class="mark" href="#perf_hooks_histogram_stddev" id="perf_hooks_histogram_stddev">#</a></span></h4>
|
|
<div class="api_metadata">
|
|
<span>Added in: v11.10.0</span>
|
|
</div>
|
|
<ul>
|
|
<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a></li>
|
|
</ul>
|
|
<p>The standard deviation of the recorded event loop delays.</p>
|
|
<h2>Examples<span><a class="mark" href="#perf_hooks_examples" id="perf_hooks_examples">#</a></span></h2>
|
|
<h3>Measuring the duration of async operations<span><a class="mark" href="#perf_hooks_measuring_the_duration_of_async_operations" id="perf_hooks_measuring_the_duration_of_async_operations">#</a></span></h3>
|
|
<p>The following example uses the <a href="async_hooks.html">Async Hooks</a> and Performance APIs to measure
|
|
the actual duration of a Timeout operation (including the amount of time it took
|
|
to execute the callback).</p>
|
|
<pre><code class="language-js"><span class="hljs-meta">'use strict'</span>;
|
|
<span class="hljs-keyword">const</span> async_hooks = <span class="hljs-built_in">require</span>(<span class="hljs-string">'async_hooks'</span>);
|
|
<span class="hljs-keyword">const</span> {
|
|
performance,
|
|
PerformanceObserver
|
|
} = <span class="hljs-built_in">require</span>(<span class="hljs-string">'perf_hooks'</span>);
|
|
|
|
<span class="hljs-keyword">const</span> set = <span class="hljs-keyword">new</span> <span class="hljs-built_in">Set</span>();
|
|
<span class="hljs-keyword">const</span> hook = async_hooks.createHook({
|
|
init(id, type) {
|
|
<span class="hljs-keyword">if</span> (type === <span class="hljs-string">'Timeout'</span>) {
|
|
performance.mark(<span class="hljs-string">`Timeout-<span class="hljs-subst">${id}</span>-Init`</span>);
|
|
set.add(id);
|
|
}
|
|
},
|
|
destroy(id) {
|
|
<span class="hljs-keyword">if</span> (set.has(id)) {
|
|
set.delete(id);
|
|
performance.mark(<span class="hljs-string">`Timeout-<span class="hljs-subst">${id}</span>-Destroy`</span>);
|
|
performance.measure(<span class="hljs-string">`Timeout-<span class="hljs-subst">${id}</span>`</span>,
|
|
<span class="hljs-string">`Timeout-<span class="hljs-subst">${id}</span>-Init`</span>,
|
|
<span class="hljs-string">`Timeout-<span class="hljs-subst">${id}</span>-Destroy`</span>);
|
|
}
|
|
}
|
|
});
|
|
hook.enable();
|
|
|
|
<span class="hljs-keyword">const</span> obs = <span class="hljs-keyword">new</span> PerformanceObserver(<span class="hljs-function">(<span class="hljs-params">list, observer</span>) =></span> {
|
|
<span class="hljs-built_in">console</span>.log(list.getEntries()[<span class="hljs-number">0</span>]);
|
|
performance.clearMarks();
|
|
observer.disconnect();
|
|
});
|
|
obs.observe({ <span class="hljs-attr">entryTypes</span>: [<span class="hljs-string">'measure'</span>], <span class="hljs-attr">buffered</span>: <span class="hljs-literal">true</span> });
|
|
|
|
<span class="hljs-built_in">setTimeout</span>(<span class="hljs-function">() =></span> {}, <span class="hljs-number">1000</span>);</code></pre>
|
|
<h3>Measuring how long it takes to load dependencies<span><a class="mark" href="#perf_hooks_measuring_how_long_it_takes_to_load_dependencies" id="perf_hooks_measuring_how_long_it_takes_to_load_dependencies">#</a></span></h3>
|
|
<p>The following example measures the duration of <code>require()</code> operations to load
|
|
dependencies:</p>
|
|
<!-- eslint-disable no-global-assign -->
|
|
<pre><code class="language-js"><span class="hljs-meta">'use strict'</span>;
|
|
<span class="hljs-keyword">const</span> {
|
|
performance,
|
|
PerformanceObserver
|
|
} = <span class="hljs-built_in">require</span>(<span class="hljs-string">'perf_hooks'</span>);
|
|
<span class="hljs-keyword">const</span> mod = <span class="hljs-built_in">require</span>(<span class="hljs-string">'module'</span>);
|
|
|
|
<span class="hljs-comment">// Monkey patch the require function</span>
|
|
mod.Module.prototype.require =
|
|
performance.timerify(mod.Module.prototype.require);
|
|
<span class="hljs-built_in">require</span> = performance.timerify(<span class="hljs-built_in">require</span>);
|
|
|
|
<span class="hljs-comment">// Activate the observer</span>
|
|
<span class="hljs-keyword">const</span> obs = <span class="hljs-keyword">new</span> PerformanceObserver(<span class="hljs-function">(<span class="hljs-params">list</span>) =></span> {
|
|
<span class="hljs-keyword">const</span> entries = list.getEntries();
|
|
entries.forEach(<span class="hljs-function">(<span class="hljs-params">entry</span>) =></span> {
|
|
<span class="hljs-built_in">console</span>.log(<span class="hljs-string">`require('<span class="hljs-subst">${entry[<span class="hljs-number">0</span>]}</span>')`</span>, entry.duration);
|
|
});
|
|
obs.disconnect();
|
|
});
|
|
obs.observe({ <span class="hljs-attr">entryTypes</span>: [<span class="hljs-string">'function'</span>], <span class="hljs-attr">buffered</span>: <span class="hljs-literal">true</span> });
|
|
|
|
<span class="hljs-built_in">require</span>(<span class="hljs-string">'some-module'</span>);</code></pre>
|
|
<!-- API END -->
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</body>
|
|
</html>
|