User Timing Level 2

W3C Recommendation

This version:
https://www.w3.org/TR/2019/REC-user-timing-2-20190226/
Latest published version:
https://www.w3.org/TR/user-timing-2/
Latest version of User Timing:
https://www.w3.org/TR/user-timing/
Latest editor's draft:
https://w3c.github.io/user-timing/
Previous version:
https://www.w3.org/TR/2019/PR-user-timing-2-20190110/
Test suite:
https://wpt.fyi/results/user-timing
Implementation report:
https://wpt.fyi/results/user-timing
Editor:
(Google)
Former editors:
Jatinder Mann (Microsoft Corp.) (Until February 2014)
Zhiheng Wang (Google Inc.) (Until July 2013)
Anderson Quach (Microsoft Corp.) (until March 2011)
Participate:
GitHub w3c/user-timing
File a bug
Commit history
Pull requests
Implementation:
Can I use User Timing?

Please check the errata for any errors or issues reported since publication.

See also translations.

Copyright © 2019 W3C® (MIT, ERCIM, Keio, Beihang). W3C liability, trademark and permissive document license rules apply.

Abstract

This specification defines an interface to help web developers measure the performance of their applications by giving them access to high precision timestamps.

Status of This Document

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 2 is intended to supersede the first version of [USER-TIMING] and includes:

This document was published by the Web Performance Working Group as a 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.

This document has been reviewed by W3C Members, by software developers, and by other W3C groups and interested parties, and is endorsed by the Director as a W3C Recommendation. It is a stable document and may be used as reference material or cited from another document. W3C's role in making the Recommendation is to draw attention to the specification and to promote its widespread deployment. This enhances the functionality and interoperability of the Web.

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 February 2018 W3C Process Document.

1. Introduction

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.

Example 1 
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();
Note

[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.

2. Conformance

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 are to be interpreted as described in [RFC2119].

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]

3. User Timing

3.1 Extensions to the Performance interface

The Performance interface is defined in [HR-TIME-2].

partial interface Performance {
    void mark(DOMString markName);
    void clearMarks(optional DOMString markName);
    void measure(DOMString measureName, optional DOMString startMark, optional DOMString endMark);
    void clearMeasures(optional DOMString measureName);
};

3.1.1 mark() method

Stores a timestamp with the associated name (a "mark"). It MUST run these steps:

  1. If the global object is a Window object and markName uses the same name as a read only attribute in the PerformanceTiming interface, throw a SyntaxError.
  2. Create a new PerformanceMark object (entry).
  3. Set entry's name attribute to markName.
  4. Set entry's entryType attribute to DOMString "mark".
  5. Set entry's startTime attribute to the value that would be returned by the Performance object's now() method.
  6. Set entry's duration attribute to 0.
  7. Queue entry.
  8. Add entry to the performance entry buffer.
  9. Return undefined.

3.1.2 clearMarks() method

Removes the stored timestamp with the associated name. It MUST run these steps:

  1. If markName is omitted, remove all PerformanceMark objects from the performance entry buffer.
  2. Otherwise, remove all PerformanceMark objects listed in the performance entry buffer whose name matchesmarkName.
  3. Return undefined.

3.1.3 measure() method

Stores the DOMHighResTimeStamp duration between two marks along with the associated name (a "measure"). It MUST run these steps:

  1. Let end time be 0.
  2. If endMark is omitted, let end time be the value that would be returned by the Performance object's now() method. Otherwise:
    1. If endMark 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 endMark.
    2. Otherwise 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 endMark. If no matching entry is found, throw a SyntaxError.
  3. If startMark is omitted, let start time be 0. Otherwise:
    1. If startMark has the same name as a read only attribute in the PerformanceTiming interface, let start time be the value returned by running the convert a name to a timestamp algorithm with name set to startMark.
    2. Otherwise let start 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 startMark. If no matching entry is found, throw a SyntaxError.
  4. Create a new PerformanceMeasure object (entry).
  5. Set entry's name attribute to measureName.
  6. Set entry's entryType attribute to DOMString "measure".
  7. Set entry's startTime attribute to start time.
  8. Set entry's duration attribute to the duration from start time to end time. The resulting duration value MAY be negative.
  9. Queue entry.
  10. Add entry to the performance entry buffer.
  11. Return undefined.

3.1.4 clearMeasures() method

Removes stored timestamp with the associated name. It MUST run these steps:

  1. If measureName is omitted, remove all PerformanceMeasure objects in the performance entry buffer.
  2. Otherwise remove all PerformanceMeasure objects listed in the performance entry buffer whose name matches measureName.
  3. Return undefined.

3.2 The PerformanceMark Interface

The PerformanceMark interface also exposes marks created via the performance.mark method to the Performance Timeline.

[Exposed=(Window,Worker)]
interface PerformanceMark : PerformanceEntry {
};

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.

3.3 The PerformanceMeasure Interface

The PerformanceMeasure interface also exposes measures created via the performance.measure method to the Performance Timeline.

[Exposed=(Window,Worker)]
interface PerformanceMeasure : PerformanceEntry {
};

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.

4. Processing

A user agent implementing the User Timing API must perform the following steps:

  1. Run the register a performance entry type algorithm with "mark" as input.
  2. Run the register a performance entry type algorithm with "measure" as input.

4.1 Convert a name to a timestamp

To convert a name to a timestamp given a name that is a read only attribute in the PerformanceTiming interface, run these steps:

  1. If the global object is not a Window object, throw a SyntaxError.
  2. If name is navigationStart, return 0.
  3. Let startTime be the value of navigationStart in the PerformanceTiming interface.
  4. Let endTime be the value of name in the PerformanceTiming interface.
  5. If endTime is 0, throw an InvalidAccessError.
  6. Return result of subtracting startTime from endTime.
Note

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.

5. Privacy and Security

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.

A. Acknowledgments

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.

B. References

B.1 Normative references

[HR-TIME-2]
High Resolution Time Level 2. Ilya Grigorik; James Simonsen; Jatinder Mann. W3C. 1 March 2018. W3C Candidate Recommendation. URL: https://www.w3.org/TR/hr-time-2/
[HTML51]
HTML 5.1 2nd Edition. Steve Faulkner; Arron Eicholz; Travis Leithead; Alex Danilo. W3C. 3 October 2017. W3C Recommendation. URL: https://www.w3.org/TR/html51/
[NAVIGATION-TIMING]
Navigation Timing. Zhiheng Wang. W3C. 17 December 2012. W3C Recommendation. URL: https://www.w3.org/TR/navigation-timing/
[PERFORMANCE-TIMELINE-2]
Performance Timeline Level 2. Ilya Grigorik. W3C. 10 January 2019. W3C Working Draft. URL: https://www.w3.org/TR/performance-timeline-2/
[RFC2119]
Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119
[WEBIDL]
Web IDL. Cameron McCormack; Boris Zbarsky; Tobie Langel. W3C. 15 December 2016. W3C Editor's Draft. URL: https://heycam.github.io/webidl/
[WORKERS]
Web Workers. Ian Hickson. W3C. 24 September 2015. W3C Working Draft. URL: https://www.w3.org/TR/workers/

B.2 Informative references

[ECMA-262]
ECMAScript Language Specification. Ecma International. URL: https://tc39.github.io/ecma262/
[NAVIGATION-TIMING-2]
Navigation Timing Level 2. Ilya Grigorik; Tobin Titus; Jatinder Mann; Arvind Jain. W3C. 30 November 2018. W3C Working Draft. URL: https://www.w3.org/TR/navigation-timing-2/
[USER-TIMING]
User Timing. Jatinder Mann; Zhiheng Wang; Anderson Quach. W3C. 12 December 2013. W3C Recommendation. URL: https://www.w3.org/TR/user-timing/