Performance Timing API | Node.js v8.17.0 Documentation (original) (raw)

Performance Timing API#

The Performance Timing API provides an implementation of theW3C Performance Timeline specification. The purpose of the API is 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#

Added in: v8.5.0

The Performance provides access to performance metric data. A single instance of this class is provided via the performance property.

performance.clearEntries(name)#

Added in: v8.11.2

Remove all performance entry objects with entryType equal to name from the Performance Timeline.

performance.clearFunctions([name])#

Added in: v8.5.0

• name

If name is not provided, removes all PerformanceFunction objects from the Performance Timeline. If name is provided, removes entries with name.

performance.clearGC()#

Added in: v8.5.0

Remove all performance entry objects with entryType equal to gc from the Performance Timeline.

performance.clearMarks([name])#

Added in: v8.5.0

• name

If name is not provided, removes all PerformanceMark objects from the Performance Timeline. If name is provided, removes only the named mark.

performance.clearMeasures([name])#

Added in: v8.5.0

• name

If name is not provided, removes all PerformanceMeasure objects from the Performance Timeline. If name is provided, removes only objects whoseperformanceEntry.name matches name.

performance.getEntries()#

Added in: v8.5.0

• Returns:

Returns a list of all PerformanceEntry objects in chronological order with respect to performanceEntry.startTime.

performance.getEntriesByName(name[, type])#

Added in: v8.5.0

• name
• type
• Returns:

Returns a list of all PerformanceEntry objects in chronological order with respect to performanceEntry.startTime whose performanceEntry.name is equal to name, and optionally, whose performanceEntry.entryType is equal totype.

performance.getEntriesByType(type)#

Added in: v8.5.0

• type
• Returns:

Returns a list of all PerformanceEntry objects in chronological order with respect to performanceEntry.startTime whose performanceEntry.entryTypeis equal to type.

performance.mark([name])#

Added in: v8.5.0

• 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 used to mark specific significant moments in the Performance Timeline.

performance.maxEntries#

Added in: v8.12.0

Value:

The maximum number of Performance Entry items that should be added to the Performance Timeline. This limit is not strictly enforced, but a process warning will be emitted if the number of entries in the timeline exceeds this limit.

Defaults to 150.

performance.measure(name, startMark, endMark)#

Added in: v8.5.0

• 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 the Performance Timeline, or may identify any of the timestamp properties provided by the PerformanceNodeTiming class. If the named startMark does not exist, then startMark is set to timeOrigin by default.

The endMark argument must identify any existing PerformanceMark in the Performance Timeline or any of the timestamp properties provided by thePerformanceNodeTiming class. If the named endMark does not exist, an error will be thrown.

performance.nodeTiming#

Added in: v8.5.0

An instance of the PerformanceNodeTiming class that provides performance metrics for specific Node.js operational milestones.

performance.now()#

Added in: v8.5.0

• Returns:

Returns the current high resolution millisecond timestamp, where 0 represents the start of the current node process.

performance.timeOrigin#

Added in: v8.5.0

The timeOrigin specifies the high resolution millisecond timestamp at which the current node process began, measured in Unix time.

performance.timerify(fn)#

Added in: v8.5.0

• fn

Wraps a function within a new function that measures the running time of the wrapped 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 created
wrapped();

Class: PerformanceEntry#

Added in: v8.5.0

performanceEntry.duration#

Added in: v8.5.0

The total number of milliseconds elapsed for this entry. This value will not be meaningful for all Performance Entry types.

performanceEntry.name#

Added in: v8.5.0

The name of the performance entry.

performanceEntry.startTime#

Added in: v8.5.0

The high resolution millisecond timestamp marking the starting time of the Performance Entry.

performanceEntry.entryType#

Added in: v8.5.0

The type of the performance entry. Current it may be one of: 'node', 'mark','measure', 'gc', or 'function'.

performanceEntry.kind#

Added in: v8.5.0

When performanceEntry.entryType is equal to 'gc', the performance.kindproperty 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#

Added in: v8.5.0

Provides timing details for Node.js itself.

performanceNodeTiming.bootstrapComplete#

Added in: v8.5.0

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.

performanceNodeTiming.clusterSetupEnd#

Added in: v8.5.0

The high resolution millisecond timestamp at which cluster processing ended. If cluster processing has not yet ended, the property has the value of -1.

performanceNodeTiming.clusterSetupStart#

Added in: v8.5.0

The high resolution millisecond timestamp at which cluster processing started. If cluster processing has not yet started, the property has the value of -1.

performanceNodeTiming.loopExit#

Added in: v8.5.0

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 'exit' event.

performanceNodeTiming.loopStart#

Added in: v8.5.0

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.

performanceNodeTiming.moduleLoadEnd#

Added in: v8.5.0

The high resolution millisecond timestamp at which main module load ended.

performanceNodeTiming.moduleLoadStart#

Added in: v8.5.0

The high resolution millisecond timestamp at which main module load started.

performanceNodeTiming.nodeStart#

Added in: v8.5.0

The high resolution millisecond timestamp at which the Node.js process was initialized.

performanceNodeTiming.preloadModuleLoadEnd#

Added in: v8.5.0

The high resolution millisecond timestamp at which preload module load ended.

performanceNodeTiming.preloadModuleLoadStart#

Added in: v8.5.0

The high resolution millisecond timestamp at which preload module load started.

performanceNodeTiming.thirdPartyMainEnd#

Added in: v8.5.0

The high resolution millisecond timestamp at which third_party_main processing ended. If third_party_main processing has not yet ended, the property has the value of -1.

performanceNodeTiming.thirdPartyMainStart#

Added in: v8.5.0

The high resolution millisecond timestamp at which third_party_main processing started. If third_party_main processing has not yet started, the property has the value of -1.

performanceNodeTiming.v8Start#

Added in: v8.5.0

The high resolution millisecond timestamp at which the V8 platform was initialized.

Class: PerformanceObserver(callback)#

Added in: v8.5.0

• callback A PerformanceObserverCallback callback function.

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 additional performance overhead, instances should not be left subscribed to notifications indefinitely. Users should disconnect observers as soon as they are no longer needed.

Callback: PerformanceObserverCallback(list, observer)#

Added in: v8.5.0

• list
• observer

The PerformanceObserverCallback is invoked when a PerformanceObserver is notified about new PerformanceEntry instances. The callback receives aPerformanceObserverEntryList instance and a reference to thePerformanceObserver.

Class: PerformanceObserverEntryList#

Added in: v8.5.0

The PerformanceObserverEntryList class is used to provide access to thePerformanceEntry instances passed to a PerformanceObserver.

performanceObserverEntryList.getEntries()#

Added in: v8.5.0

• Returns:

Returns a list of PerformanceEntry objects in chronological order with respect to performanceEntry.startTime.

performanceObserverEntryList.getEntriesByName(name[, type])#

Added in: v8.5.0

• name
• type
• Returns:

Returns a list of PerformanceEntry objects in chronological order with respect to performanceEntry.startTime whose performanceEntry.name is equal to name, and optionally, whose performanceEntry.entryType is equal totype.

performanceObserverEntryList.getEntriesByType(type)#

Added in: v8.5.0

• type
• Returns:

Returns a list of PerformanceEntry objects in chronological order with respect to performanceEntry.startTime whose performanceEntry.entryTypeis equal to type.

performanceObserver.disconnect()#

Added in: v8.5.0

Disconnects the PerformanceObserver instance from all notifications.

performanceObserver.observe(options)#

Added in: v8.5.0

• options
  • entryTypes An array of strings identifying the types ofPerformanceEntry instances the observer is interested in. If not provided an error will be thrown.
  • buffered If true, the notification callback will be called using setImmediate() and multiple PerformanceEntry instance notifications will be buffered internally. If false, notifications will be immediate and synchronous. Default: false.

Subscribes the PerformanceObserver instance to notifications of newPerformanceEntry instances identified by options.entryTypes.

When options.buffered is false, the callback will be invoked once for every 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 measure the actual duration of a Timeout operation (including the amount of time it to 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 load dependencies:

'use strict';
const {
  performance,
  PerformanceObserver
} = require('perf_hooks');
const mod = require('module');

// Monkey patch the require function
mod.Module.prototype.require =
  performance.timerify(mod.Module.prototype.require);
require = performance.timerify(require);

// Activate the observer
const 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');