Copyright © 2020 W3C® (MIT, ERCIM, Keio, Beihang). W3C liability, trademark and permissive document license rules apply.
This specification defines an interface to help web developers measure the performance of their applications by giving them access to high precision timestamps.
This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at https://www.w3.org/TR/.
User Timing Level 3 is intended to supersede [USER-TIMING-2] and includes:
This document was published by the Web Performance Working Group as a Working Draft. This document is intended to become a W3C Recommendation.
GitHub Issues are preferred for
discussion of this specification.
Alternatively, you can send comments to our mailing list.
Please send them to
public-web-perf@w3.org
(archives)
with [UserTiming]
at the start of your
email's subject
.
Please see the Working Group's implementation report.
Publication as a Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.
This document was produced by a group operating under the W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.
This document is governed by the 1 March 2019 W3C Process Document.
This section is non-normative.
Web developers need the ability to assess and understand the performance characteristics of their applications. While JavaScript [ECMA-262] provides a mechanism to measure application latency (retrieving the current timestamp from the Date.now()
method), the precision of this timestamp varies between user agents.
This document defines the PerformanceMark
and PerformanceMeasure
interfaces, and extensions to the Performance
interface, which expose a high precision, monotonically increasing timestamp so that developers can better measure the performance characteristics of their applications.
The following script shows how a developer can use the interfaces defined in this document to obtain timing data related to developer scripts.
async function run() {
performance.mark("startTask1");
await doTask1(); // Some developer code
performance.mark("endTask1");
performance.mark("startTask2");
await doTask2(); // Some developer code
performance.mark("endTask2");
// Log them out
const entries = performance.getEntriesByType("mark");
for (const entry of entries) {
console.table(entry.toJSON());
}
}
run();
[PERFORMANCE-TIMELINE-2] defines two mechanisms that
can be used to retrieve recorded metrics: getEntries()
and getEntriesByType()
methods, and the
PerformanceObserver
interface. The former is best suited
for cases where you want to retrieve a particular metric by name at a
single point in time, and the latter is optimized for cases where you
may want to receive notifications of new metrics as they become
available.
As another example, suppose that there is an element which, when clicked, fetches some new content and indicates that it has been fetched. We'd like to report the time from when the user clicked to when the fetch was complete. We can't mark the time the click handler executes since that will miss latency to process the event, so instead we use the event hardware timestamp. We also want to know the name of the component to have more detailed analytics.
element.addEventListener("click", e => {
const component = getComponent(element);
fetch(component.url).then(() => {
element.textContent = "Updated";
const updateMark = performance.mark("update_component", {
detail: {component: component.name},
});
performance.measure("click_to_update_component", {
detail: {component: component.name},
start: e.timeStamp,
end: updateMark.startTime,
});
});
});
As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.
The key words MAY and MUST in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.
Some conformance requirements are phrased as requirements on attributes, methods or objects. Such requirements are to be interpreted as requirements on user agents.
The IDL fragments in this specification MUST be interpreted as required for conforming IDL fragments, as described in the Web IDL specification. [WEBIDL]
Performance
interfaceThe Performance
interface and DOMHighResTimeStamp are defined in [HR-TIME-2].
The PerformanceEntry interface is defined in [PERFORMANCE-TIMELINE-2].
WebIDLdictionaryPerformanceMarkOptions
{ anydetail
; DOMHighResTimeStampstartTime
; }; dictionaryPerformanceMeasureOptions
{ anydetail
; (DOMString or DOMHighResTimeStamp)start
; DOMHighResTimeStampduration
; (DOMString or DOMHighResTimeStamp)end
; }; partial interfacePerformance
{PerformanceMark
mark
(DOMString markName, optionalPerformanceMarkOptions
markOptions = {}); voidclearMarks
(optional DOMString markName);PerformanceMeasure
measure
(DOMString measureName, optional (DOMString orPerformanceMeasureOptions
) startOrMeasureOptions = {}, optional DOMString endMark); voidclearMeasures
(optional DOMString measureName); };
mark()
methodStores a timestamp with the associated name (a "mark"). It MUST run these steps:
PerformanceMarkOptions
dictionarydetail
startTime
clearMarks()
methodRemoves the stored timestamp with the associated name. It MUST run these steps:
PerformanceMark
objects from the performance entry buffer.PerformanceMark
objects listed in the performance entry buffer whose name matchesmarkName.measure()
methodStores the DOMHighResTimeStamp
duration between two marks along with the associated name (a "measure"). It MUST run these steps:
PerformanceMeasureOptions
object, run the following checks:
PerformanceMeasureOptions
object, and if its end
member is present, let end time be the value returned by running the convert a mark to a timestamp algorithm passing in startOrMeasureOptions's end
.PerformanceMeasureOptions
object, and if its start
and duration
members are both present:
start
.duration
.Performance
object's now()
method.PerformanceMeasureOptions
object, and if its start
member is present, let start time be the value returned by running the convert a mark to a timestamp algorithm passing in startOrMeasureOptions's start
.PerformanceMeasureOptions
object, and if its duration
and end
members are both present:
duration
.end
.DOMString
, let start time be the value returned by running the convert a mark to a timestamp algorithm passing in startOrMeasureOptions.0
.PerformanceMeasure
object (entry) with this's relevant realm.name
attribute to measureName.entryType
attribute to DOMString "measure"
.startTime
attribute to start time.duration
attribute to the duration from start time to end time. The resulting duration value MAY be negative.detail
attribute as follows:
PerformanceMeasureOptions
object:
detail
.detail
to the result of calling the StructuredDeserialize algorithm on record and the current realm.null
.PerformanceMeasureOptions
dictionarydetail
start
duration
end
clearMeasures()
methodRemoves stored timestamp with the associated name. It MUST run these steps:
PerformanceMeasure
objects in the performance entry buffer.PerformanceMeasure
objects listed in the performance entry buffer whose name
matches measureName.PerformanceMark
InterfaceThe PerformanceMark
interface also exposes marks created via the performance.mark method to the Performance Timeline.
WebIDL[Exposed=(Window,Worker)] interfacePerformanceMark
: PerformanceEntry {constructor
(DOMString markName, optionalPerformanceMarkOptions
markOptions = {}); readonly attribute anydetail
; };
The PerformanceMark
interface extends the following attributes of the PerformanceEntry
interface:
The name
attribute must return the mark's name.
The entryType
attribute must return the DOMString
"mark"
.
The startTime
attribute must return a DOMHighResTimeStamp
with the mark's time value.
The duration
attribute must return a DOMHighResTimeStamp
of value 0
.
The PerformanceMark
interface contains the following additional attribute:
The detail
attribute must return the value it is set to (it's copied from the PerformanceMarkOptions
dictionary).
PerformanceMark
ConstructorThe PerformanceMark constructor must run the following steps:
Window
object and markName uses the same name as a read only attribute in the PerformanceTiming
interface, throw a SyntaxError
.PerformanceMark
object (entry) with the current global object's realm.name
attribute to markName.entryType
attribute to DOMString "mark"
.startTime
attribute as follows:
duration
attribute to 0
.detail
.detail
to the result of calling the StructuredDeserialize algorithm on record and the current realm.PerformanceMeasure
InterfaceThe PerformanceMeasure
interface also exposes measures created via the performance.measure method to the Performance Timeline.
WebIDL[Exposed=(Window,Worker)] interfacePerformanceMeasure
: PerformanceEntry { readonly attribute anydetail
; };
The PerformanceMeasure
interface extends the following attributes of the PerformanceEntry
interface:
The name
attribute must return the measure's name.
The entryType
attribute must return the DOMString
"measure"
.
The startTime
attribute must return a DOMHighResTimeStamp
with the measure's start mark.
The duration
attribute must return a DOMHighResTimeStamp
with the duration of the measure.
The PerformanceMeasure
interface contains the following additional attribute:
The detail
attribute must return the value it is set to (it's copied from the PerformanceMeasureOptions
dictionary).
A user agent implementing the User Timing API would need to include "mark"
and
"measure"
in
supportedEntryTypes. This allows developers to detect support for User Timing.
To convert a mark to a timestamp, given a mark that is a DOMString
or DOMHighResTimeStamp
run these steps:
DOMString
and it has the same name as a read only attribute in the PerformanceTiming
interface, let end time be the value returned by running the convert a name to a timestamp algorithm with name set to the value of mark.DOMString
, let end time be the value of the startTime
attribute from the most recent occurrence of a PerformanceMark
object in the performance entry buffer whose name
matches the value of mark. If no matching entry is found, throw a SyntaxError
.DOMHighResTimeStamp
:
TypeError
.To convert a name to a timestamp given a name that is a read only attribute in the PerformanceTiming
interface, run these steps:
Window
object, throw a TypeError
.navigationStart
, return 0
.navigationStart
in the PerformanceTiming
interface.PerformanceTiming
interface.0
, throw an InvalidAccessError
.The PerformanceTiming interface was defined in [NAVIGATION-TIMING] and is now considered obsolete. The use of names from the PerformanceTiming interface is supported to remain backwards compatible, but there are no plans to extend this functionality to names in the PerformanceNavigationTiming interface defined in [NAVIGATION-TIMING-2] (or other interfaces) in the future.
This section is non-normative.
The interfaces defined in this specification expose potentially sensitive timing information on specific JavaScript activity of a page. Please refer to [HR-TIME-2] for privacy and security considerations of exposing high-resolution timing information.
Because the web platform has been designed with the invariant that any script included on a page has the same access as any other script included on the same page, regardless of the origin of either scripts, the interfaces defined by this specification do not place any restrictions on recording or retrieval of recorded timing information - i.e. a user timing mark or measure recorded by any script included on the page can be read by any other script running on the same page, regardless of origin.
Thanks to James Simonsen, Jason Weber, Nic Jansma, Philippe Le Hegaret, Karen Anderson, Steve Souders, Sigbjorn Vik, Todd Reifsteck, and Tony Gentilcore for their contributions to this work.