User Timing Level 2

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 replaces the first version of [USER-TIMING] and includes:

Support for PerformanceMark and PerformanceMeasure in Web Workers [WORKERS] via integration with [HR-TIME-2];
Processing clarifications for mark names that reference PerformanceTiming interface defined in [NAVIGATION-TIMING-2].

This document was published by the Web Performance Working Group as a Working Draft. This document is intended to become a W3C Recommendation. Comments regarding this document are welcome. Please send them to public-web-perf@w3.org (subscribe, archives) with [UserTiming] at the start of your email's subject.

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 2017 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 [ECMA262] 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 they 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

<!doctype html>
<html>
  <head>
    <title>User Timing example</title>
  </head>
  <body onload="init()">
    <script>
       function init()
       {
            performance.mark("startTask1");
            doTask1(); // Some developer code
            performance.mark("endTask1");

            performance.mark("startTask2");
            doTask2(); // Some developer code
            performance.mark("endTask2");

            measurePerf();
       }

       function measurePerf()
       {
           var perfEntries = performance.getEntriesByType("mark");
           for (var i = 0; i < perfEntries.length; i++)
           {
                 if (window.console) console.log("Name: "        + perfEntries[i].name      +
                                                 " Entry Type: " + perfEntries[i].entryType +
                                                 " Start Time: " + perfEntries[i].startTime +
                                                 " Duration: "   + perfEntries[i].duration  + "\n");
           }
       }
    </script>
  </body>
</html>

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.

3. 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);
};

The mark(markName) method stores a timestamp with the associated name (a "mark"). It MUST run these steps:

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

The clearMarks(markName) method 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 matchesmarkName.
Return undefined.

The measure(measureName, startMark, endMark) method stores the DOMHighResTimeStamp duration between two marks along with the associated name (a "measure"). It MUST run these steps:

Let end time be 0.
If endMark is omitted, let end time be the value that would be returned by the Performance object's now() method. Otherwise let end time be the value of the startTime attribute from the most recent occurence PerformanceMark object in the performance entry buffer whose name matches value endMark.
If startMark is omitted, let start time be 0. Otherwise let start time be the value of the startTime attribute from the most recent occurence PerformanceMark object in the performance entry buffer whose name matches value startMark.
Create a new PerformanceMeasure object.
Set name to measureName.
Set entryType to DOMString "measure".
Set startTime to start time.
Set duration to the duration from start time to end time. The resulting duration value MAY be negative.
Queue the PerformanceMeasure object.
Add the PerformanceMeasure object to the performance entry buffer.
Return undefined.

The clearMeasures(measureName) 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 matches measureName.
Return undefined.

4. The `PerformanceMark` Interface

The PerformanceMark interface also exposes marks created via the Performance.mark method to the Performance Timeline [PERFORMANCE-TIMELINE-2].

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

The PerformanceMark interface extends the following attributes of the PerformanceEntry interface:

The name attribute will return the mark's name.

The entryType attribute will return the DOMString "mark".

The startTime attribute will return a DOMHighResTimeStamp with the mark's time value [HR-TIME-2].

The duration attribute will return a DOMHighResTimeStamp of value 0.

5. The `PerformanceMeasure` Interface

The PerformanceMeasure interface also exposes measures created via the Performance.measure method to the Performance Timeline [PERFORMANCE-TIMELINE-2].

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

The PerformanceMeasure interface extends the following attributes of the PerformanceEntry interface:

The name attribute will return the measure's name.

The entryType attribute will return the DOMString "measure".

The startTime attribute will return a DOMHighResTimeStamp with the measure's start mark [HR-TIME-2].

The duration attribute will return a DOMHighResTimeStamp with the duration of the measure.

User Timing Level 2

W3C Working Draft 06 December 2017

Abstract

Status of This Document

1. Introduction

2. Conformance

3. Extensions to the `Performance` Interface

4. The `PerformanceMark` Interface

5. The `PerformanceMeasure` Interface

6. Privacy and Security

A. Acknowledgments

B. References

B.1 Normative references

B.2 Informative references

User Timing Level 2

W3C Working Draft 06 December 2017

Abstract

Status of This Document

1. Introduction

2. Conformance

3. Extensions to the Performance Interface

4. The PerformanceMark Interface

5. The PerformanceMeasure Interface

6. Privacy and Security

A. Acknowledgments

B. References

B.1 Normative references

B.2 Informative references

3. Extensions to the `Performance` Interface

4. The `PerformanceMark` Interface

5. The `PerformanceMeasure` Interface