performance.measure()

The measure() method creates a named timestamp in the browser's performance entry buffer between marks, the navigation start time, or the current time.

When measuring between two marks, there is a start mark and end mark, respectively. The named timestamp is referred to as a measure.

The measure can be retrieved using any of the Performance interfaces: (getEntries(), getEntriesByName() or getEntriesByType()).

measure(measureName)
measure(measureName, MeasureOptions)
measure(measureName, startMark)
measure(measureName, startMark, endMark)

If only measureName is specified, the start timestamp is set to zero, and the end timestamp (which is used to calculate the duration) is the value that would be returned by Performance.now().

measureName

A DOMString representing the name of the measure.

MeasureOptions Optional

An object that may contain all measure options (the startMark and endMark may be specified in this object or as their own arguments):

detail

Arbitrary metadata to be included in the measure.

start

Timestamp DOMHighResTimeStamp to be used as the start time, or DOMString to be used as start mark. If this represents the name of a start mark, then it is defined in the same way as startMark (in other words it must be the name of an existing mark or a PerformanceTiming property).

duration

Duration between the start and end mark times (DOMHighResTimeStamp).

end

Timestamp (DOMHighResTimeStamp) to be used as the end time, or DOMString to be used as end mark. If this represents the name of an end mark, then it is defined in the same way as endMark (in other words it must be the name of an existing mark or a PerformanceTiming property).

startMark Optional

A DOMString representing the name of the measure's starting mark. May also be the name of a PerformanceTiming property. Specifying a name that does not represent an existing PerformanceMark or PerformanceTiming raises a SyntaxError DOMException.

endMark Optional

A DOMString representing the name of the measure's ending mark. This may also be the name of a PerformanceTiming property. Specifying a name that does not represent an existing PerformanceMark or PerformanceTiming raises a SyntaxError DOMException.

The PerformanceMeasure entry that was created.

The returned measure will have the following property values:

• entryType - set to "measure".
• name - set to the "name" argument.
• startTime - set to:
  • a timestamp, if specified in MeasureOptions.start.
  • the timestamp of a start mark, if specified in MeasureOptions.start or startMark
  • a timestamp calculated from the MeasureOptions.end and MeasureOptions.duration (if MeasureOptions.start was not specified)
  • 0, if it isn't specified and can't be determined from other values.
• duration - set to a DOMHighResTimeStamp that is the duration of the measure calculated by subtracting the startTime from the end timestamp. The end timestamp is one of:
  • a timestamp, if specified in MeasureOptions.end.
  • the timestamp of an end mark, if one is specified in MeasureOptions.end or endMark
  • a timestamp calculated from the MeasureOptions.start and MeasureOptions.duration (if MeasureOptions.end was not specified)
  • the value returned by Performance.now(), if no end mark is specified or can be determined from other values.
• detail - set to the value passed in MeasureOptions.

TypeError DOMException

This can be thrown in any case where the start, end or duration might be ambiguous:

• Both endMark and MeasureOptions are specified.
• MeasureOptions is specified without either start and end members.
• MeasureOptions is specified with all of start, end, and duration members (which might then be inconsistent).

SyntaxError DOMException

The named mark does not exist.

• An end mark is specified using either endMark or MeasureOptions.end, but there is no PerformanceMark in the performance buffer with the matching name.
• An end mark is specified using either endMark or MeasureOptions.end, but it cannot be converted to match that of a read only attribute in the PerformanceTiming interface.
• A start mark is specified using either startMark or MeasureOptions.start, but there is no PerformanceMark in the performance buffer with the matching name.
• A start mark is specified using either startMark or MeasureOptions.start, but it cannot be converted to match that of a read only attribute in the PerformanceTiming interface.

DataCloneError DOMException

The MeasureOptions.detail value is non-null and cannot be serialized using the HTML "StructuredSerialize" algorithm.

RangeError

The MeasureOptions.detail value is non-null and memory cannot be allocated during serialization using the HTML "StructuredSerialize" algorithm.

The following example shows how measure() is used to create a new measure performance entry in the browser's performance entry buffer.

const markerNameA = "example-marker-a"
const markerNameB = "example-marker-b"

// Run some nested timeouts, and create a PerformanceMark for each.
performance.mark(markerNameA);
setTimeout(function() {
  performance.mark(markerNameB);
  setTimeout(function() {

    // Create a variety of measurements.
    performance.measure("measure a to b", markerNameA, markerNameB);
    performance.measure("measure a to now", markerNameA);
    performance.measure("measure from navigation start to b", undefined, markerNameB);
    performance.measure("measure from navigation start to now");

    // Pull out all of the measurements.
    console.log(performance.getEntriesByType("measure"));

    // Finally, clean up the entries.
    performance.clearMarks();
    performance.clearMeasures();
  }, 1000);
}, 1000);