Performance: measure() method
The measure()
method creates a named PerformanceMeasure
object representing a time measurement between two marks in the browser's performance timeline.
When measuring between two marks, there is a start mark and end mark, respectively. The named timestamp is referred to as a measure.
Syntax
measure(measureName)
measure(measureName, startMark)
measure(measureName, startMark, endMark)
measure(measureName, measureOptions)
measure(measureName, measureOptions, 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()
.
You can use strings to identify PerformanceMark
objects as start and end marks.
To only provide an endMark
, you need to provide an empty measureOptions
object: performance.measure("myMeasure", {}, "myEndMarker")
.
Parameters
measureName
-
A string representing the name of the measure.
-
measureOptions
Optional
-
An object that may contain measure options.
-
detail
Optional
-
Arbitrary metadata to be included in the measure. Defaults to null
. Must be structured-cloneable.
-
start
Optional
-
Timestamp (DOMHighResTimeStamp
) to be used as the start time, or string that names a PerformanceMark
to use for the start time.
If this is a string naming a PerformanceMark
, then it is defined in the same way as startMark
.
-
duration
Optional
-
Duration between the start and end mark times. If omitted, this defaults to performance.now()
; the time that has elapsed since the context was created. If provided, you must also specify either start
or end
but not both.
-
end
Optional
-
Timestamp (DOMHighResTimeStamp
) to be used as the end time, or string that names a PerformanceMark
to use for the end time.
If this is a string naming a PerformanceMark
, then it is defined in the same way as endMark
.
-
startMark
Optional
-
A string naming a PerformanceMark
in the performance timeline. The PerformanceEntry.startTime
property of this mark will be used for calculating the measure.
-
endMark
Optional
-
A string naming a PerformanceMark
in the performance timeline. The PerformanceEntry.startTime
property of this mark will be used for calculating the measure. If you want to pass this argument, you must also pass either startMark
or an empty measureOptions
object.
Return value
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
.
Exceptions
TypeError
-
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 with duration
but without specifying either start
or end
. -
measureOptions
is specified with all of start
, end
, and duration
.
-
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.
Examples
Measuring duration between named markers
Given two of your own markers "login-started"
and "login-finished"
, you can create a measurement called "login-duration"
as shown in the following example. The returned PerformanceMeasure
object will then provide a duration
property to tell you the elapsed time between the two markers.
const loginMeasure = performance.measure(
"login-duration",
"login-started",
"login-finished",
);
console.log(loginMeasure.duration);
Measuring duration with custom start and end times
To do more advanced measurements, you can pass a measureOptions
parameter. For example, you can use the event.timeStamp
property from a click
event as the start time.
performance.measure("login-click", {
start: myClickEvent.timeStamp,
end: myMarker.startTime,
});
Providing additional measurement details
You can use the details
property to provide additional information of any type. Maybe you want to record which HTML element was clicked, for example.
performance.measure("login-click", {
detail: { htmlElement: myElement.id },
start: myClickEvent.timeStamp,
end: myMarker.startTime,
});
Specifications
Browser compatibility
|
Desktop |
Mobile |
|
Chrome |
Edge |
Firefox |
Internet Explorer |
Opera |
Safari |
WebView Android |
Chrome Android |
Firefox for Android |
Opera Android |
Safari on IOS |
Samsung Internet |
measure |
2825–28 |
12 |
38 |
10 |
33 |
11 |
4.4 |
2825–28 |
42 |
33 |
11 |
1.5 |
measureOptions_parameter |
78 |
79 |
103 |
No |
65 |
14.1 |
78 |
78 |
103 |
56 |
14.5 |
12.0 |
returns_performancemeasure |
78 |
79 |
103 |
No |
65 |
14.1 |
78 |
78 |
103 |
56 |
14.5 |
12.0 |