Copyright © 2012 W3C® (MIT, ERCIM, Keio), All Rights Reserved. W3C liability, trademark and document use 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 http://www.w3.org/TR/.
W3C publishes a
Candidate
Recommendation to indicate that the document is believed to be
stable and to encourage implementation by the ThissecondLastCallWorkingdeveloper community.
Draft
The entrance criteria for this document to enter the Proposed
Recommendation stage is to have a minimum of "UserTiming".Ittakesintotwo independent and
interoperable user agents that implementation all the accountHighResolutionfeatures of
this specification, which will be determined by passing the user
agent tests defined in the test suite developed by the Working Group.
Time
The Working Group does not expect to advance to Proposed
Recommendation prior to . A preliminary
implementation report is available and removesstringwill be updated during the
Candidate Recommendation period. This is a work in progress and may
change without any notices.
constants.
The Working Group intends to gain implementation experience before recommending that implementations remove their vendor prefixes.
Please send comments to public-web-perf@w3.org (archived) with [UserTiming] at the start of the subject line by .
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 WorkingCandidate Recommendation 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.Draft
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.
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 timestamp to developers so they can better measure the performance 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.
<!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"); forperformance.getEntries("marks");(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>(i
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]
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 DOMisusedtorefertotheAPIsetmadeavailabletoscriptsinWebapplications,anddoesnotnecessarilyimplytheexistenceofanactualDocumentobjectorofanyotherNodeobjectsasdefinedintheDOMCorespecifications.[DOMLevel3Core]ADOMattributeissaidtobegettingwhenitsvalueisbeingretrieved(suchasbyauthorscript),andissaidtobesettingwhenanewvalueisassignedtoit.The"JavaScript" is used to refer to termECMAScript [ECMA262], rather than the
official term ECMAScript, since the term JavaScript is more widely known.
ECMA262,
This section is non-normative
The PerformanceMark
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.
Performance
Interfacepartial interface Performance { void mark(DOMString markName);ArraygetMarks(optionalDOMStringvoid clearMarks(optional DOMString markName); void measure(DOMString measureName, optional DOMString startMark, optional DOMString endMark);markName);ArraygetMeasures(optionalDOMStringvoid clearMeasures(optional DOMString measureName); };measureName);
mark
methodThis method stores a timestamp with the associated name (a "mark").
Parameters
in
type of markNamenameDOMString
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].
Recommended Mark Names
Developers are encouraged to use the following Recommended Mark 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 Recommended Mark Name is appropriate or consistent with its description.
"mark_fully_loaded"
The time when the page is considered fully loaded as marked by the developer in their application.
"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"
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"
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.
getMarksclearMarks
methodIf the markName argument is not specified, this method mustremoves all returnofmarks and their associated theDOMHighResTimeStamp
time values.
If the markName argument is specified, this method mustremoves all return
time values for the ofDOMHighResTimeStampthegiven mark name.specified
If the markName argument is specified but the specified markName does not exist, this method itmustreturnanemptywill do nothing.array.
Parameters
in markName
type of DOMString
[optional] The name of the mark whose mark.DOMHighResTimeStamp
time values should be cleared.
If not specified, all marks arewill be cleared.returned.
No Return Value
ArrayIfthemarkNameargumentisnotspecified,No Exceptionsthe
measure
method returnsanassociativeArray.EachkeyThis method stores the in
duration between two marks
along with the Arrayisamarkname.ThevalueDOMHighResTimeStampassociatedassociated name markisanArrayofDOMHighResTimeStamptimevaluesforthatmark.InJSONnotation,thedatastructurewilllooksimilartothis:{"mark1":[0.750,1.125,3.333],"mark2":[2.125]}.IfthemarkNameargumentisspecified,andthemarknameexists,themethodreturnsanArrayofDOMHighResTimeStamptimevalues.InJSONnotation,thedatastructurewilllooksimilartothis:[0.500,1.125,3.750].IfthemarkNameargumentisspecified,andthemarknamedoesnotexist,themethodreturnsanemptyArray.InJSONnotation,thedatastructurewilllooksimilartothis:[].Timestampswillbelistedintheorderthatthemark()methodwascalled.ThereturnedArrayisacopyofdataatthetimethatthegetMarks()methodwascalled.NoExceptionsclearMarksmethodIfthemarkNameargumentisnotspecified,thismethodremovesallmarksandtheirassociatedDOMHighResTimeStamptimevalues.IfthemarkNameargumentisspecified,thismethodremovesallDOMHighResTimeStamptimevaluesforthegivenmarkname.IfthemarkNameargumentisspecifiedbutthespecifiedmarkNamedoesnotexist,thismethodwilldonothing.ParametersinmarkNametypeofDOMString[optional]ThenameofthemarkwhoseDOMHighResTimeStamptimevaluesshouldbecleared.Ifnotspecified,allmarkswillbecleared.NoReturnValueNoExceptionsmeasuremethodThismethodstorestheDOMHighResTimeStampdurationbetweentwomarksalongwiththeassociatedname(a"measure").The(a "measure").behavior
The behavior of this method depends on which arguments are specified:
measure()
will store the duration as a DOMHighResTimeStamp
from
navigationStart
to the current time.measure()
will store the duration as a DOMHighResTimeStamp
from the most recent occurrence of the start mark to the current time.measure()
will store the duration as a DOMHighResTimeStamp
from the most recent occurrence of the start mark to the most recent occurrence of the end mark.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 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 DOMHighResTimeStamp
time value of the start mark is used.
If not specified, 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 DOMHighResTimeStamp
time value.
in endMark
type of DOMString
[optional] The name of the end mark.
If specified, the most recent 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 DOMHighResTimeStamp
time value.
No Return Value
Exceptions
Throws a SYNTAX_ERR
exception if the start mark or end mark does not exist.
Throws an INVALID_ACCESS_ERR
exception if either startMark
or endMark
argument, or both, have the same name as a
PerformanceTiming
attribute with a time value of 0.
getMeasures method If the measureName argument is specified, this method must return all of the durations for the specified measure name. If the measureName argument is not specified, this method must return all of the measures and their associated DOMHighResTimeStamp durations. If the measureName argument is specified but it does not exist, 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.525, 5.125, 1.125], "measure2": [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.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. No ExceptionsclearMeasures
methodIf 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
PerformanceMark
Interfaceinterface PerformanceMark : PerformanceEntry { };
The PerformanceMark interface also
exposes marks created via the mark()
method to the
Performance Timeline [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
mark
.
The startTime
attribute will return a DOMHighResTimeStamp
with the mark's time thevalue [High Resolution Time].
value.
The duration
attribute will return a DOMHighResTimeStamp
of value 0.
PerformanceMeasure
Interfaceinterface PerformanceMeasure : PerformanceEntry { };
The PerformanceMeasure interface also
exposes measures created via the measure()
method to the Performance Timeline [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
measure
.
The startTime
attribute will return a DOMHighResTimeStamp
with the measure's start mark [High Resolution Time].mark.
The duration
attribute will return a DOMHighResTimeStamp
with the duration of the measure.
Vendor-specific proprietary user agent extensions are 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:
The 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 time values must never be negative. The user agent must record the system clock at the beginning of the navigation and define subsequent time values in terms of a monotonic clock measuring time elapsed from the beginning of the navigation.
This section is non-normative.
The interfaces defined in this specification expose potentially sensitive timing information on specific JavaScript activity of a page. However, unlike other interfaces defined in the Performance Timeline, the interfaces defined in this specification do not have any restrictions on sharing timing information through script. This is 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 that page regardless of the origin of the script.
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.