User Timing

W3C Candidate Recommendation Draft 31 October 2024

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

This User Timing specification is intended to supersede [USER-TIMING-2] and includes:

Ability to execute marks and measures across arbitrary timestamps.
Support for reporting arbitrary metadata along with marks and measures.

This document was published by the Web Performance Working Group as a Candidate Recommendation Draft using the Recommendation track.

Publication as a Candidate Recommendation does not imply endorsement by W3C and its Members. A Candidate Recommendation Draft integrates changes from the previous Candidate Recommendation that the Working Group intends to include in a subsequent Candidate Recommendation Snapshot.

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 03 November 2023 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.

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.

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.

Example 2

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]

The Performance interface and DOMHighResTimeStamp are defined in [HR-TIME-2]. The PerformanceEntry interface is defined in [PERFORMANCE-TIMELINE-2].

WebIDLdictionary PerformanceMarkOptions {
    any detail;
    DOMHighResTimeStamp startTime;
};

dictionary PerformanceMeasureOptions {
    any detail;
    (DOMString or DOMHighResTimeStamp) start;
    DOMHighResTimeStamp duration;
    (DOMString or DOMHighResTimeStamp) end;
};

partial interface Performance {
    PerformanceMark mark(DOMString markName, optional PerformanceMarkOptions markOptions = {});
    undefined clearMarks(optional DOMString markName);
    PerformanceMeasure measure(DOMString measureName, optional (DOMString or PerformanceMeasureOptions) startOrMeasureOptions = {}, optional DOMString endMark);
    undefined clearMeasures(optional DOMString measureName);
};

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

Run the PerformanceMark constructor and let entry be the newly created object.
Queue entry.
Add entry to the performance entry buffer.
Return entry.

detail: Metadata to be included in the mark.
startTime: Timestamp to be used as the mark time.

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

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

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

If startOrMeasureOptions is a PerformanceMeasureOptions object and at least one of start, end, duration, and detail exist, run the following checks:
1. If endMark is given, throw a TypeError.
2. If startOrMeasureOptions's start and end members are both omitted, throw a TypeError.
3. If startOrMeasureOptions's start, duration, and end members all exist, throw a TypeError.
Compute end time as follows:
1. If endMark is given, let end time be the value returned by running the convert a mark to a timestamp algorithm passing in endMark.
2. Otherwise, if startOrMeasureOptions is a PerformanceMeasureOptions object, and if its end member exists, let end time be the value returned by running the convert a mark to a timestamp algorithm passing in startOrMeasureOptions's end.
3. Otherwise, if startOrMeasureOptions is a PerformanceMeasureOptions object, and if its start and duration members both exist:
  1. Let start be the value returned by running the convert a mark to a timestamp algorithm passing in start.
  2. Let duration be the value returned by running the convert a mark to a timestamp algorithm passing in duration.
  3. Let end time be start plus duration.
4. Otherwise, let end time be the value that would be returned by the Performance object's now() method.
Compute start time as follows:
1. If startOrMeasureOptions is a PerformanceMeasureOptions object, and if its start member exists, let start time be the value returned by running the convert a mark to a timestamp algorithm passing in startOrMeasureOptions's start.
2. Otherwise, if startOrMeasureOptions is a PerformanceMeasureOptions object, and if its duration and end members both exist:
  1. Let duration be the value returned by running the convert a mark to a timestamp algorithm passing in duration.
  2. Let end be the value returned by running the convert a mark to a timestamp algorithm passing in end.
  3. Let start time be end minus duration.
3. Otherwise, if startOrMeasureOptions is a DOMString, let start time be the value returned by running the convert a mark to a timestamp algorithm passing in startOrMeasureOptions.
4. Otherwise, let start time be 0.
Create a new PerformanceMeasure object (entry) with this's relevant realm.
Set entry's name attribute to measureName.
Set entry's entryType attribute to DOMString "measure".
Set entry's startTime attribute to start time.
Set entry's duration attribute to the duration from start time to end time. The resulting duration value MAY be negative.
Set entry's detail attribute as follows:
1. If startOrMeasureOptions is a PerformanceMeasureOptions object and startOrMeasureOptions's detail member exists:
  1. Let record be the result of calling the StructuredSerialize algorithm on startOrMeasureOptions's detail.
  2. Set entry's detail to the result of calling the StructuredDeserialize algorithm on record and the current realm.
2. Otherwise, set it to null.
Queue entry.
Add entry to the performance entry buffer.
Return entry.

detail: Metadata to be included in the measure.
start: Timestamp to be used as the start time or string to be used as start mark.
duration: Duration between the start and end times.
end: Timestamp to be used as the end time or string to be used as end mark.

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

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

The PerformanceMark interface also exposes marks created via the Performance interface's mark() method to the Performance Timeline.

WebIDL[Exposed=(Window,Worker)]
interface PerformanceMark : PerformanceEntry {
  constructor(DOMString markName, optional PerformanceMarkOptions markOptions = {});
  readonly attribute any detail;
};

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

The PerformanceMark constructor must run the following steps:

If the current global object is a Window object and markName uses the same name as a read only attribute in the PerformanceTiming interface, throw a SyntaxError.
Create a new PerformanceMark object (entry) with the current global object's realm.
Set entry's name attribute to markName.
Set entry's entryType attribute to DOMString "mark".
Set entry's startTime attribute as follows:
1. If markOptions's startTime member exists, then:
  1. If markOptions's startTime is negative, throw a TypeError.
  2. Otherwise, set entry's startTime to the value of markOptions's startTime.
2. Otherwise, set it to the value that would be returned by the Performance object's now() method.
Set entry's duration attribute to 0.
If markOptions's detail is null, set entry's detail to null.
Otherwise:
1. Let record be the result of calling the StructuredSerialize algorithm on markOptions's detail.
2. Set entry's detail to the result of calling the StructuredDeserialize algorithm on record and the current realm.

The PerformanceMeasure interface also exposes measures created via the Performance interface's measure() method to the Performance Timeline.

WebIDL[Exposed=(Window,Worker)]
interface PerformanceMeasure : PerformanceEntry {
  readonly attribute any detail;
};

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

Note

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:

If mark is a 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.
Otherwise, if mark is a 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 is mark. If no matching entry is found, throw a SyntaxError.
Otherwise, if mark is a DOMHighResTimeStamp:
1. If mark is negative, throw a TypeError.
2. Otherwise, let end time be mark.

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

If the global object is not a Window object, throw a TypeError.
If name is navigationStart, return 0.
Let startTime be the value of navigationStart in the PerformanceTiming interface.
Let endTime be the value of name in the PerformanceTiming interface.
If endTime is 0, throw an InvalidAccessError.
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.

Developers are encouraged to use the following recommended mark names to mark common timings. The user agent does not validate that the usage of these names is appropriate or consistent with its description.

Note

Adding such recommended mark names can help performance tools tailor guidance to a site. These mark names can also help real user monitoring providers and user agents collect web developer signals regarding their application's performance at scale, and surface this information to developers without requiring any site-specific work.

"mark_fully_loaded"

The time when the page is considered fully loaded as marked by the developer in their application.

Note

In this example, the page asynchonously initializes a chat widget, a searchbox, and a newsfeed upon loading. When finished, the "mark_fully_loaded" mark name enables lab tools and analytics providers to automatically show the timing.

Example 3

window.addEventListener("load", (event) => {
  Promise.all([
    loadChatWidget(),
    initializeSearchAutocomplete(),
    initializeNewsfeed()]).then(() => {
      performance.mark('mark_fully_loaded');
  });
});

"mark_fully_visible"

The time when the page is considered fully visible to an end-user as marked by the developer in their application.

"mark_interactive"

The time when the page is considered interactive to an end-user as marked by the developer in their application.

"mark_feature_usage"

Mark the usage of a feature which may impact performance so that tooling and analytics can take it into account. The detail metadata can contain any useful information about the feature, including:

feature: The name of the feature used.
framework: If applicable, the underlying framework the feature is intended for, such as a JavaScript framework, content management system, or e-commerce platform.

Note

In this example, the ImageOptimizationComponent for FancyJavaScriptFramework is used to size images for optimal performance. The code notes this feature's usage so that lab tools and analytics can measure whether it helped improve performance.

Example 4

performance.mark('mark_feature_usage', {
  'detail': {
    'feature': 'ImageOptimizationComponent',
    'framework': 'FancyJavaScriptFramework'
  }
})

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.

[HR-TIME-2]: High Resolution Time Level 2. Ilya Grigorik. W3C. 21 November 2019. W3C Recommendation. URL: https://www.w3.org/TR/hr-time-2/
[HTML]: HTML Standard. Anne van Kesteren; Domenic Denicola; Dominic Farolino; Ian Hickson; Philip Jägenstedt; Simon Pieters. WHATWG. Living Standard. URL: https://html.spec.whatwg.org/multipage/
[infra]: Infra Standard. Anne van Kesteren; Domenic Denicola. WHATWG. Living Standard. URL: https://infra.spec.whatwg.org/
[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. Nicolas Pena Moreno. W3C. 16 February 2024. W3C Candidate Recommendation. URL: https://www.w3.org/TR/performance-timeline/
[RFC2119]: Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc2119
[RFC8174]: Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words. B. Leiba. IETF. May 2017. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc8174
[WEBIDL]: Web IDL Standard. Edgar Chen; Timothy Gu. WHATWG. Living Standard. URL: https://webidl.spec.whatwg.org/

[ECMA-262]: ECMAScript Language Specification. Ecma International. URL: https://tc39.es/ecma262/multipage/
[NAVIGATION-TIMING-2]: Navigation Timing Level 2. Yoav Weiss; Noam Rosenthal. W3C. 29 July 2024. W3C Working Draft. URL: https://www.w3.org/TR/navigation-timing-2/
[USER-TIMING-2]: User Timing Level 2. Ilya Grigorik. W3C. 26 February 2019. W3C Recommendation. URL: https://www.w3.org/TR/user-timing-2/

User Timing

Abstract

Status of This Document

1. Introduction

2. Conformance

3. User Timing

3.1 Extensions to the `Performance` interface

3.1.1 `mark()` method

3.1.1.1 `PerformanceMarkOptions` dictionary

3.1.2 `clearMarks()` method

3.1.3 `measure()` method

3.1.3.1 `PerformanceMeasureOptions` dictionary

3.1.4 `clearMeasures()` method

3.2 The `PerformanceMark` Interface

3.2.1 The `PerformanceMark` Constructor

3.3 The `PerformanceMeasure` Interface

4. Processing

4.1 Convert a `mark` to a `timestamp`

4.2 Convert a `name` to a `timestamp`

5. Recommended mark names

6. Privacy and Security

A. Acknowledgments

B. References

B.1 Normative references

B.2 Informative references

User Timing

Abstract

Status of This Document

1. Introduction

2. Conformance

3. User Timing

3.1 Extensions to the Performance interface

3.1.1 mark() method

3.1.1.1 PerformanceMarkOptions dictionary

3.1.2 clearMarks() method

3.1.3 measure() method

3.1.3.1 PerformanceMeasureOptions dictionary

3.1.4 clearMeasures() method

3.2 The PerformanceMark Interface

3.2.1 The PerformanceMark Constructor

3.3 The PerformanceMeasure Interface

4. Processing

4.1 Convert a mark to a timestamp

4.2 Convert a name to a timestamp

5. Recommended mark names

6. Privacy and Security

A. Acknowledgments

B. References

B.1 Normative references

B.2 Informative references

3.1 Extensions to the `Performance` interface

3.1.1 `mark()` method

3.1.1.1 `PerformanceMarkOptions` dictionary

3.1.2 `clearMarks()` method

3.1.3 `measure()` method

3.1.3.1 `PerformanceMeasureOptions` dictionary

3.1.4 `clearMeasures()` method

3.2 The `PerformanceMark` Interface

3.2.1 The `PerformanceMark` Constructor

3.3 The `PerformanceMeasure` Interface

4.1 Convert a `mark` to a `timestamp`

4.2 Convert a `name` to a `timestamp`