W3C

User Timing

W3C Working Draft 1 September 2011 8 May 2012

This version:
http://www.w3.org/TR/2011/WD-user-timing-20110901/ http://www.w3.org/TR/2012/WD-user-timing-20120508/
Latest version:
http://www.w3.org/TR/user-timing/
Latest Editor's Draft:
https://dvcs.w3.org/hg/webperf/raw-file/tip/specs/UserTiming/Overview.html
Previous version:
http://www.w3.org/TR/2011/WD-user-timing-20110811/ http://www.w3.org/TR/2011/WD-user-timing-20110901/
Editors:
Jatinder Mann , Microsoft Inc. Corp. ,
Zhiheng Wang , Google Inc. ,
Anderson Quach , Microsoft Inc. Corp. (Until March 2011)

Copyright © 2011 2012 W3C ® ( MIT , ERCIM , Keio ), All Rights Reserved. W3C liability , trademark and document use 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 http://www.w3.org/TR/.

This is a the second Last Call Working Draft of "User Timing".

Please send comments to public-web-perf@w3.org ( archived ) with [UserTiming] at the start of the subject line by 22 September 2011 . .

A diff document with the previous draft is available.

This document is produced by the Web Performance Working Group. The Web Performance Working Group is part of the Rich Web Clients Activity in the W3C Interaction Domain .

You can find the latest Editor's Draft of this document in the W3C's Mercurial repository , which is updated on a regular basis.

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 5 February 2004 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 .

Table of Contents

  1. 1 Introduction
  2. 2 Conformance requirements
  3. 3 Terminology
  4. 4 User Timing
    1. 4.1 Introduction
    2. 4.2 The Extensions to the UserTiming Performance Interface
    3. 4.3 The PerformanceMark Interface
    4. 4.4 The PerformanceMeasure Interface
    5. 4.5 Vendor Prefixes
  5. 5 Monotonic Clock
  6. 6 Privacy
  7. 7 Security Acknowledgements
  8. Acknowledgements References

1 Introduction

This section is non-normative.

Web developers need the ability to assess and understand the performance characteristics of their applications. While JavaScript 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 introduces defines the UserTiming PerformanceMark and PerformanceMeasure interfaces, and extensions to the Performance interface, which exposes expose a high precision timestamp to developers so they can better measure the performance of their applications.

TODO: Show example usage.

The following script shows how a developer can use the interfaces defined in this document to obtain timing data related to developer scripts. 

    <!doctype html>
    <html>
      <head>
      </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.getEntries("marks");
               for (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>

2 Conformance requirements

All diagrams, examples, and notes in this specification are non-normative, as are all sections explicitly marked non-normative. Everything else in this specification is normative.

The key words "MUST", "MUST NOT", "REQUIRED", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in the normative parts of this document are to be interpreted as described in RFC2119. For readability, these words do not appear in all uppercase letters in this specification. [RFC2119]

Requirements phrased in the imperative as part of algorithms (such as "strip any leading space characters" or "return false and abort these steps") are to be interpreted with the meaning of the key word ("must", "should", "may", etc) used in introducing the algorithm.

Some conformance requirements are phrased as requirements on attributes, methods or objects. Such requirements are to be interpreted as requirements on user agents.

Conformance requirements phrased as algorithms or specific steps may be implemented in any manner, so long as the end result is equivalent. (In particular, the algorithms defined in this specification are intended to be easy to follow, and not intended to be performant.)

The IDL fragments in this specification must be interpreted as required for conforming IDL fragments, as described in the Web IDL specification. [Web IDL]

3 Terminology

The construction "a Foo object", where Foo is actually an interface, is sometimes used instead of the more accurate "an object implementing the interface Foo ".

The term DOM is used to refer to the API set made available to scripts in Web applications, and does not necessarily imply the existence of an actual Document object or of any other Node objects as defined in the DOM Core specifications. [DOM Level 3 Core]

A DOM attribute is said to be getting when its value is being retrieved (such as by author script), and is said to be setting when a new value is assigned to it.

The term "JavaScript" is used to refer to ECMA262, rather than the official term ECMAScript, since the term JavaScript is more widely known. [ECMA262]

4 User Timing

4.1 Introduction

This section is non-normative

The User Timing PerformanceMark interface gives and PerformanceMeasure interfaces, and extensions to the Performance interface, give web developers access to a high precision, monotonically increasing timestamp so they can better measure the performance characteristics of their applications.

Throughout this work, the term "timestamp" refers to the number of milliseconds since midnight of January 1, 1970 (UTC).

4.2 The Extensions to the UserTiming Performance Interface 

  partial interface  {
    const unsigned short PERF_DEVELOPER_MARK = 2;
    const unsigned short PERF_DEVELOPER_MEASURE = 3;

    const string  = "fullyLoaded";
    const string  = "fullyVisible";
    const string  = "aboveTheFold";
    const string  = "timeToUserAction";

    void  markName);
    Array  markName);
    void  markName);

  partial interface Performance {
    void mark(DOMString markName);
    Array getMarks(optional DOMString markName);
    void clearMarks(optional  DOMString markName);


    void  endMark);
    Array  measureName);
    void  measureName);

    void measure(DOMString measureName, optional DOMString startMark, optional DOMString endMark);
    Array getMeasures(optional DOMString measureName);
    void clearMeasures(optional DOMString measureName);

  };

mark method

This method stores a timestamp with the associated name (a "mark").

Parameters

in name type of DOMString

The name associated with the timestamp.

Mark names may be re-used within the same document. Each call to the mark() method stores a new timestamp under the specified mark name.

The mark name cannot be the same name as any of the attributes in the PerformanceTiming interface [Navigation Timing] .

Standard Recommended Mark Names

The mark name may be one of Developers are encouraged to use the following Standard Mark Names. When using a Standard Recommended Mark Name, the Names to mark common interactions. The user agent is responsible for storing a new timestamp under the specified mark name for Recommended Mark Names, just like any user specified mark name. The user agent does not validate that the usage of the Standard Recommended Mark Name is appropriate or consistent with its description.

MARK_FULLY_LOADED "mark_fully_loaded"

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

MARK_FULLY_VISIBLE "mark_fully_visible"

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

MARK_ABOVE_THE_FOLD "mark_above_the_fold"

The time when all of the content in the visible viewport has been presented to the end-user as marked by the developer in their application.

MARK_TIME_TO_USER_ACTION "mark_time_to_user_action"

The time of the first user interaction with the page during or after a navigation, such as scroll or click, as marked by the developer in their application.

No Return Value

Exceptions

Throws a SYNTAX_ERR exception if the markName argument is the same name as an attribute in the PerformanceTiming interface.

getMarks method

If the markName argument is not specified, this method must return all of the marks and their associated timestamps. DOMHighResTimeStamp time values.

If the markName argument is specified, this method must return all of the timestamps DOMHighResTimeStamp time values for the specified mark name.

If the markName argument is specified but it does not exist, this method must return an empty array.

If this method is invoked from a cross-origin script and the Timing-Allow-Origin HTTP response header rules are not met, this method must return an empty array.

Parameters

in markName type of DOMString

[optional] The name of the mark. If not specified, all marks are returned.

Return Value

Array

If the markName argument is not specified, the method returns an associative Array. Each key in the Array is a mark name. The value associated with the mark name is an Array of timestamps DOMHighResTimeStamp time values for that mark. In JSON notation, the data structure will look similar to this: { "mark1": [0, 1, 3], [0.750, 1.125, 3.333], "mark2": [2] [2.125] } .

If the markName argument is specified, and the mark name exists, the method returns an Array of timestamps. DOMHighResTimeStamp time values. In JSON notation, the data structure will look similar to this: [0, 1, 3] [0.500, 1.125, 3.750] .

If the markName argument is specified, and the mark name does not exist, the method returns an empty Array. In JSON notation, the data structure will look similar to this: [] .

Timestamps will be listed in the order that the mark() method was called.

The returned Array is a copy of data at the time that the getMarks() method was called.

If this method is invoked from a cross-origin script and the Timing-Allow-Origin HTTP response header rules are not met, this method must return an empty array.

No Exceptions

clearMarks method

If the markName argument is not specified, this method removes all marks and their associated timestamps. DOMHighResTimeStamp time values.

If the markName argument is specified, this method removes all timestamps DOMHighResTimeStamp time values for the given mark name.

If the markName argument is specified but the specified markName does not exist, this method will do nothing.

Parameters

in markName type of DOMString

[optional] The name of the mark whose timestamps DOMHighResTimeStamp time values should be cleared. If not specified, all marks will be cleared.

No Return Value

No Exceptions

measure method

This method stores the DOMHighResTimeStamp duration between two marks (measured in milliseconds) along with the associated name (a "measure").

The behavior of this method depends on which arguments are specified:

The startMark and endMark arguments may be the name of one of the attributes in the PerformanceTiming interface [Navigation Timing] . In this case, the value of that attribute is used as the timestamp. DOMHighResTimeStamp time value.

Parameters

in name type of DOMString

The name associated with the measure.

Measure names may be re-used within the same document. Each call to the measure() method stores a new duration under the specified measure name.

Measure names live independently from mark names.

in startMark type of DOMString

[optional] The name of the start mark.

If specified, the most recent timestamp DOMHighResTimeStamp time value of the start mark is used.

If not specified, fetchStart navigationStart is used.

May be the name of one of the attributes in the PerformanceTiming interface [Navigation Timing] . In this case, the value of that attribute is used as the start timestamp. DOMHighResTimeStamp time value.

in endMark type of DOMString

[optional] The name of the end mark.

If specified, the most recent timestamp DOMHighResTimeStamp time value of the end mark is used.

If not specified, the current time as a DOMHighResTimeStamp is used.

May be the name of one of the attributes in the PerformanceTiming interface [Navigation Timing] . In this case, the value of that attribute is used as the end timestamp. DOMHighResTimeStamp time value.

No Return Value

Exceptions

Throws a SYNTAX_ERR exception if the start mark or end mark does not exist.

Throws a SYNTAX_ERR exception if the duration (the end mark timestamp minus the start mark timestamp) is negative. Throws a an SYNTAX_ERR INVALID_ACCESS_ERR exception if either startMark or endMark argument, or both, have the same name as a PerformanceTiming attribute with a timestamp time value of 0 [Navigation Timing] . 0.

getMeasures method

If the measureName argument is not specified, this method must return all of the measures and their associated durations. durations for the specified measure name.

If the measureName argument is not specified, this method must return all of the durations for the specified measure name. measures and their associated DOMHighResTimeStamp durations.

If the measureName argument is specified but it does not exist, this method must return an empty array.

If this method is invoked from a cross-origin script and the Timing-Allow-Origin HTTP response header rules are not met, this method must return an empty array.

Parameters

in measureName type of DOMString

[optional] The name of the measure to return. If not specified, all measures are returned.

Return Value

Array

If the measureName argument is not specified, the method returns an associative Array. Each key in the Array is a measure name. The value associated with the measure name is an Array of DOMHighResTimeStamp durations for that measure. In JSON notation, the data structure will look similar to this: { "measure1": [0, 5, 1], [0.525, 5.125, 1.125], "measure2": [3] [3.251] } .

If the measureName argument is specified, and the measure name exists, the method returns an Array of DOMHighResTimeStamp durations. In JSON notation, the data structure will look similar to this: [0, 5, 1] [0.250, 5.125, 1.750].

If the measureName argument is specified, and the measure name does not exist, the method returns an empty Array. In JSON notation, the data structure will look similar to this: [] .

Durations will be listed in the order that the measure() method was called.

The returned Array is a copy of data at the time that the getMeasures() method was called.

If this method is invoked from a cross-origin script and the Timing-Allow-Origin HTTP response header rules are not met, this method must return an empty array.

No Exceptions

clearMeasures method

If the measureName argument is not specified, this method removes all measures and their associated DOMHighResTimeStamp durations.

If the measureName argument is specified, this method removes all DOMHighResTimeStamp durations for the given measure name.

If the measureName argument is specified but the specified measureName does not exist, this method will do nothing.

Parameters

in measureName type of DOMString

[optional] The name of the measure whose DOMHighResTimeStamp durations should be cleared. If not specified, all measures will be cleared.

No Return Value

No Exceptions

4.3 The PerformanceMark Interface 

  interface PerformanceMark :  {
  }

  interface PerformanceMark : PerformanceEntry {
  };

The PerformanceMark interface also exposes marks created via the mark() method to the Performance Timeline . 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 PERF_DEVELOPER_MARK mark .

The startTime attribute will return a DOMHighResTimeStamp with the the mark's timestamp. time value. If a cross-origin script gets this attribute and the Timing-Allow-Origin HTTP response header rules are not met, this attribute must be set to zero.

The duration attribute will return a DOMHighResTimeStamp of value 0.

4.4 The PerformanceMeasure Interface 

  interface PerformanceMeasure :  {
  }

  interface PerformanceMeasure : PerformanceEntry {
  };

The PerformanceMeasure interface also exposes measures created via the measure() method to the Performance Timeline . 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 PERF_DEVELOPER_MEASURE measure .

The startTime attribute will return the timestamp of a DOMHighResTimeStamp with the measure's start mark. If a cross-origin script gets this attribute and the Timing-Allow-Origin HTTP response header rules are not met, this attribute must be set to zero.

The duration attribute will return a DOMHighResTimeStamp with the duration of the measure. If a cross-origin script gets this attribute and the Timing-Allow-Origin HTTP response header rules are not met, this attribute must be set to zero.

4.5 Vendor Prefixes

Vendor-specific proprietary user agent extensions to this specification are strongly discouraged. If such extensions are needed, e.g. for experimental purposes, vendors must use the following extension mechanisms:

If the extension to be added is a Standard Mark Name , the Standard Mark Name must:

5 Monotonic Clock

The timestamps time values stored within the interface must monotonically increase to ensure they are not affected by adjustments to the system clock. The difference between any two chronologically recorded timestamps time values must never be negative. The user agent must record the system clock at the beginning of the navigation and define subsequent timestamps time values in terms of a monotonic clock measuring time elapsed from the beginning of the navigation.

<h2 id="priv

6 Privacy and Security

The PerformanceMark and PerformanceMeasure interfaces, and extensions to the Performance interface expose high precision timing information of the performance characteristics of application scripts. To limit access to these interfaces, the same origin policy is enforced by default with the getMarks and getMeasures methods returning empty Arrays when invoked from cross-origin scripts and the startTime and duration attributes of the PerformanceMark and PerformanceMeasure interfaces being set to zero when the attributes are queried from cross-origin scripts.

Developers can explicitly allow timing information to be accessed from cross-origin scripts by adding the Timing-Allow-Origin HTTP response header, which specifies the domains that are allowed to access the timing information.

The terms origin and same origin are defined by The HTTP Origin Header. [IETF RFC 6454]

The term cross-origin is used to mean non same origin .

Server-side applications may return the Timing-Allow-Origin HTTP response header to allow the User Agent to fully expose, to the document origin(s) specified, the values of attributes that would have been set to zero and return values of methods that would have been empty Arrays due to the cross-origin restrictions previously specified in this section.

Timing-Allow-Origin Response Header

The Timing-Allow-Origin header indicates whether a resource's timing can be shared based by returning the value of the Origin request header in the response. ABNF: 


Timing-Allow-Origin
=
"Timing-Allow-Origin"
":"
origin-list-or-null
|
"*"

origin-list-or-null is defined by The HTTP Origin Header. [IETF RFC 6454]

Acknowledgements

Thanks to Karen Anderson, Tony Gentilcore, Nic Jansma, James Simonsen, Steve Souders, Sigbjorn Vik, and Jason Weber for their useful comments that led to changes to this specification and their contributions to this work.

References

[IETF RFC 2119]
Key words for use in RFCs to Indicate Requirement Levels , Scott Bradner, Author. Internet Engineering Task Force, March 1997. Avail