Node.js v8.x 中文文档
目录
- Performance Timing API
- Class: Performance
- performance.clearFunctions([name])
- performance.clearGC()
- performance.clearMarks([name])
- performance.clearMeasures([name])
- performance.getEntries()
- performance.getEntriesByName(name[, type])
- performance.getEntriesByType(type)
- performance.mark([name])
- performance.measure(name, startMark, endMark)
- performance.nodeTiming
- performance.now()
- performance.timeOrigin
- performance.timerify(fn)
- Class: PerformanceEntry
- Class: PerformanceNodeTiming extends PerformanceEntry
- performanceNodeTiming.bootstrapComplete
- performanceNodeTiming.clusterSetupEnd
- performanceNodeTiming.clusterSetupStart
- performanceNodeTiming.loopExit
- performanceNodeTiming.loopStart
- performanceNodeTiming.moduleLoadEnd
- performanceNodeTiming.moduleLoadStart
- performanceNodeTiming.nodeStart
- performanceNodeTiming.preloadModuleLoadEnd
- performanceNodeTiming.preloadModuleLoadStart
- performanceNodeTiming.thirdPartyMainEnd
- performanceNodeTiming.thirdPartyMainStart
- performanceNodeTiming.v8Start
- Class: PerformanceObserver(callback)
- Examples
- Class: Performance
Performance Timing API#
The Performance Timing API provides an implementation of theW3C Performance Timeline specification. The purpose of the APIis to support collection of high resolution performance metrics.This is the same Performance API as implemented in modern Web browsers.
const { performance } = require('perf_hooks');performance.mark('A');doSomeLongRunningProcess(() => { performance.mark('B'); performance.measure('A to B', 'A', 'B'); const measure = performance.getEntriesByName('A to B')[0]; console.log(measure.duration); // Prints the number of milliseconds between Mark 'A' and Mark 'B'});
Class: Performance#
The Performance
provides access to performance metric data. A singleinstance of this class is provided via the performance
property.
performance.clearFunctions([name])#
If name
is not provided, removes all PerformanceFunction
objects from thePerformance Timeline. If name
is provided, removes entries with name
.
performance.clearGC()#
Remove all performance entry objects with entryType
equal to gc
from thePerformance Timeline.
performance.clearMarks([name])#
If name
is not provided, removes all PerformanceMark
objects from thePerformance Timeline. If name
is provided, removes only the named mark.
performance.clearMeasures([name])#
If name
is not provided, removes all PerformanceMeasure
objects from thePerformance Timeline. If name
is provided, removes only objects whoseperformanceEntry.name
matches name
.
performance.getEntries()#
Returns a list of all PerformanceEntry
objects in chronological orderwith respect to performanceEntry.startTime
.
performance.getEntriesByName(name[, type])#
Returns a list of all PerformanceEntry
objects in chronological orderwith respect to performanceEntry.startTime
whose performanceEntry.name
isequal to name
, and optionally, whose performanceEntry.entryType
is equal totype
.
performance.getEntriesByType(type)#
Returns a list of all PerformanceEntry
objects in chronological orderwith respect to performanceEntry.startTime
whose performanceEntry.entryType
is equal to type
.
performance.mark([name])#
Creates a new PerformanceMark
entry in the Performance Timeline. APerformanceMark
is a subclass of PerformanceEntry
whoseperformanceEntry.entryType
is always 'mark'
, and whoseperformanceEntry.duration
is always 0
. Performance marks are usedto mark specific significant moments in the Performance Timeline.
performance.measure(name, startMark, endMark)#
Creates a new PerformanceMeasure
entry in the Performance Timeline. APerformanceMeasure
is a subclass of PerformanceEntry
whoseperformanceEntry.entryType
is always 'measure'
, and whoseperformanceEntry.duration
measures the number of milliseconds elapsed sincestartMark
and endMark
.
The startMark
argument may identify any existing PerformanceMark
in thePerformance Timeline, or may identify any of the timestamp propertiesprovided by the PerformanceNodeTiming
class. If the named startMark
doesnot exist, then startMark
is set to timeOrigin
by default.
The endMark
argument must identify any existing PerformanceMark
in thePerformance Timeline or any of the timestamp properties provided by thePerformanceNodeTiming
class. If the named endMark
does not exist, anerror will be thrown.
performance.nodeTiming#
An instance of the PerformanceNodeTiming
class that provides performancemetrics for specific Node.js operational milestones.
performance.now()#
Returns the current high resolution millisecond timestamp.
performance.timeOrigin#
The timeOrigin
specifies the high resolution millisecond timestamp fromwhich all performance metric durations are measured.
performance.timerify(fn)#
Wraps a function within a new function that measures the running time of thewrapped function. A PerformanceObserver
must be subscribed to the 'function'
event type in order for the timing details to be accessed.
const { performance, PerformanceObserver} = require('perf_hooks');function someFunction() { console.log('hello world');}const wrapped = performance.timerify(someFunction);const obs = new PerformanceObserver((list) => { console.log(list.getEntries()[0].duration); obs.disconnect(); performance.clearFunctions();});obs.observe({ entryTypes: ['function'] });// A performance timeline entry will be createdwrapped();
Class: PerformanceEntry#
performanceEntry.duration#
The total number of milliseconds elapsed for this entry. This value will notbe meaningful for all Performance Entry types.
performanceEntry.name#
The name of the performance entry.
performanceEntry.startTime#
The high resolution millisecond timestamp marking the starting time of thePerformance Entry.
performanceEntry.entryType#
The type of the performance entry. Current it may be one of: 'node'
, 'mark'
,'measure'
, 'gc'
, or 'function'
.
performanceEntry.kind#
When performanceEntry.entryType
is equal to 'gc'
, the performance.kind
property identifies the type of garbage collection operation that occurred.The value may be one of:
perf_hooks.constants.NODE_PERFORMANCE_GC_MAJOR
perf_hooks.constants.NODE_PERFORMANCE_GC_MINOR
perf_hooks.constants.NODE_PERFORMANCE_GC_INCREMENTAL
perf_hooks.constants.NODE_PERFORMANCE_GC_WEAKCB
Class: PerformanceNodeTiming extends PerformanceEntry#
Provides timing details for Node.js itself.
performanceNodeTiming.bootstrapComplete#
The high resolution millisecond timestamp at which the Node.js processcompleted bootstrap.
performanceNodeTiming.clusterSetupEnd#
The high resolution millisecond timestamp at which cluster processing ended.
performanceNodeTiming.clusterSetupStart#
The high resolution millisecond timestamp at which cluster processing started.
performanceNodeTiming.loopExit#
The high resolution millisecond timestamp at which the Node.js event loopexited.
performanceNodeTiming.loopStart#
The high resolution millisecond timestamp at which the Node.js event loopstarted.
performanceNodeTiming.moduleLoadEnd#
The high resolution millisecond timestamp at which main module load ended.
performanceNodeTiming.moduleLoadStart#
The high resolution millisecond timestamp at which main module load started.
performanceNodeTiming.nodeStart#
The high resolution millisecond timestamp at which the Node.js process wasinitialized.
performanceNodeTiming.preloadModuleLoadEnd#
The high resolution millisecond timestamp at which preload module load ended.
performanceNodeTiming.preloadModuleLoadStart#
The high resolution millisecond timestamp at which preload module load started.
performanceNodeTiming.thirdPartyMainEnd#
The high resolution millisecond timestamp at which third_party_main processingended.
performanceNodeTiming.thirdPartyMainStart#
The high resolution millisecond timestamp at which third_party_main processingstarted.
performanceNodeTiming.v8Start#
The high resolution millisecond timestamp at which the V8 platform wasinitialized.
Class: PerformanceObserver(callback)#
PerformanceObserver
objects provide notifications when newPerformanceEntry
instances have been added to the Performance Timeline.
const { performance, PerformanceObserver} = require('perf_hooks');const obs = new PerformanceObserver((list, observer) => { console.log(list.getEntries()); observer.disconnect();});obs.observe({ entryTypes: ['mark'], buffered: true });performance.mark('test');
Because PerformanceObserver
instances introduce their own additionalperformance overhead, instances should not be left subscribed to notificationsindefinitely. Users should disconnect observers as soon as they are nolonger needed.
Callback: PerformanceObserverCallback(list, observer)#
list
observer
The PerformanceObserverCallback
is invoked when a PerformanceObserver
isnotified about new PerformanceEntry
instances. The callback receives aPerformanceObserverEntryList
instance and a reference to thePerformanceObserver
.
Class: PerformanceObserverEntryList#
The PerformanceObserverEntryList
class is used to provide access to thePerformanceEntry
instances passed to a PerformanceObserver
.
performanceObserverEntryList.getEntries()#
Returns a list of PerformanceEntry
objects in chronological orderwith respect to performanceEntry.startTime
.
performanceObserverEntryList.getEntriesByName(name[, type])#
Returns a list of PerformanceEntry
objects in chronological orderwith respect to performanceEntry.startTime
whose performanceEntry.name
isequal to name
, and optionally, whose performanceEntry.entryType
is equal totype
.
performanceObserverEntryList.getEntriesByType(type)#
Returns a list of PerformanceEntry
objects in chronological orderwith respect to performanceEntry.startTime
whose performanceEntry.entryType
is equal to type
.
performanceObserver.disconnect()#
Disconnects the PerformanceObserver
instance from all notifications.
performanceObserver.observe(options)#
options
entryTypes
An array of strings identifying the types of PerformanceEntry
instances the observer is interested in. If notprovided an error will be thrown.buffered
If true, the notification callback will becalled using setImmediate()
and multiplePerformanceEntry
instancenotifications will be buffered internally. Iffalse
, notifications willbe immediate and synchronous. Defaults tofalse
.
Subscribes the PerformanceObserver
instance to notifications of newPerformanceEntry
instances identified by options.entryTypes
.
When options.buffered
is false
, the callback
will be invoked once forevery PerformanceEntry
instance:
const { performance, PerformanceObserver} = require('perf_hooks');const obs = new PerformanceObserver((list, observer) => { // called three times synchronously. list contains one item});obs.observe({ entryTypes: ['mark'] });for (let n = 0; n < 3; n++) performance.mark(`test${n}`);
const { performance, PerformanceObserver} = require('perf_hooks');const obs = new PerformanceObserver((list, observer) => { // called once. list contains three items});obs.observe({ entryTypes: ['mark'], buffered: true });for (let n = 0; n < 3; n++) performance.mark(`test${n}`);
Examples#
Measuring the duration of async operations#
The following example uses the Async Hooks and Performance APIs to measurethe actual duration of a Timeout operation (including the amount of time itto execute the callback).
'use strict';const async_hooks = require('async_hooks');const { performance, PerformanceObserver} = require('perf_hooks');const set = new Set();const hook = async_hooks.createHook({ init(id, type) { if (type === 'Timeout') { performance.mark(`Timeout-${id}-Init`); set.add(id); } }, destroy(id) { if (set.has(id)) { set.delete(id); performance.mark(`Timeout-${id}-Destroy`); performance.measure(`Timeout-${id}`, `Timeout-${id}-Init`, `Timeout-${id}-Destroy`); } }});hook.enable();const obs = new PerformanceObserver((list, observer) => { console.log(list.getEntries()[0]); performance.clearMarks(); performance.clearMeasures(); observer.disconnect();});obs.observe({ entryTypes: ['measure'], buffered: true });setTimeout(() => {}, 1000);
Measuring how long it takes to load dependencies#
The following example measures the duration of require()
operations to loaddependencies:
'use strict';const { performance, PerformanceObserver} = require('perf_hooks');const mod = require('module');// Monkey patch the require functionmod.Module.prototype.require = performance.timerify(mod.Module.prototype.require);require = performance.timerify(require);// Activate the observerconst obs = new PerformanceObserver((list) => { const entries = list.getEntries(); entries.forEach((entry) => { console.log(`require('${entry[0]}')`, entry.duration); }); obs.disconnect(); // Free memory performance.clearFunctions();});obs.observe({ entryTypes: ['function'], buffered: true });require('some-module');