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 specification is a Superseded Recommendation.
A newer
specification exists that is recommended for new adoption in place of
this specification.
This "User Timing Level 1" specification was produced by the Web
Performance Working
Group. An implementation
report as of August 2013 is available.
No changes were made since the previous publication.
Please send comments
to public-web-perf@w3.org
(archived)
with [UserTiming] at the start of the subject line.
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.
For purposes of the W3C Patent Policy, this Superseded Recommendation
has the same status as an active Recommendation; it retains licensing
commitments and remains available as a reference for old -- and
possibly still deployed -- implementations, but is not recommended for
future implementation. New implementations should follow the latest version
of the User Timing specification.
Table of Contents
- 1
Introduction
- 2
Conformance requirements
- 3 Terminology
- 4 User Timing
- 4.1 Introduction
- 4.2 Extensions to the
Performance Interface
- 4.3 The
PerformanceMark Interface
- 4.4 The
PerformanceMeasure Interface
- 4.5 Vendor Prefixes
- 5 Monotonic Clock
- 6 Privacy and Security
- 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 [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");
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>
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 "JavaScript" is used to refer to ECMAScript [ECMA262], rather than the
official term ECMAScript, since the term JavaScript is more widely known.
Throughout this work, all time values are measured in milliseconds since the start of
navigation of the document. For example, the start of navigation of the document
occurs at time 0. The term current time refers to the number of milliseconds
since the start of navigation of the document until the current moment in time.
This definition of time is based on the High Resolution Time specification
[High Resolution Time] and is different
from the definition of time used in the Navigation Timing specification
[Navigation Timing],
where time is measured in milliseconds since midnight of January 1, 1970 (UTC).
4 User Timing
4.1 Introduction
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.
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);
};
This method stores a timestamp with the associated name (a "mark").
Parameters
in markName 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].
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.
If the markName argument is not specified, this method removes all marks and their associated DOMHighResTimeStamp time values.
If the markName argument is specified, this method removes all 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 DOMHighResTimeStamp time values should be cleared.
If not specified, all marks will be cleared.
No Return Value
No Exceptions
This method stores the DOMHighResTimeStamp duration between two marks
along with the associated name (a "measure").
The behavior of this method depends on which arguments are specified:
- If neither the startMark nor the endMark argument is specified,
measure() will store the duration as a DOMHighResTimeStamp from
navigationStart
to the current time.
- If the startMark argument is specified, but the endMark argument is not specified,
measure() will store the duration as a DOMHighResTimeStamp
from the most recent occurrence of the start mark to the current time.
- If both the startMark and endMark arguments are specified,
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
in endMark type of DOMString
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.
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
interface 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:
interface 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:
4.5 Vendor Prefixes
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:
- Follow this naming convention: [VENDORPREFIX]_[STANDARD_MARK_NAME], where [VENDORPREFIX] is a name that identifies the vendor and [STANDARD_MARK_NAME] is the name given to the Standard Mark.
5 Monotonic Clock
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.
6 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.
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.
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. Available at http://www.ietf.org/rfc/rfc2119.txt.
- [ECMA-262]
-
ECMAScript Language Specification, 5.1
Edition. ECMA International, Standard
ECMA-262, June 2011. This version of the ECMAScript
Language is available from http://www.ecma-international.org/publications/standards/Ecma-262.htm.
- [Navigation Timing]
- Navigation Timing, Zhiheng Wang, Editor. World Wide Web Consortium, December 2012. This version of the Navigation Timing specification is available from http://www.w3.org/TR/2012/REC-navigation-timing-20121217/. The latest version of Navigation Timing is available at http://www.w3.org/TR/navigation-timing/.
- [Performance Timeline]
- Performance Timeline, Jatinder Mann, et al, Editors. W3C Recommendation, World Wide Web Consortium, December 2013. This version of the Performance Timeline Recommendation is available from http://www.w3.org/TR/2013/REC-performance-timeline-20131212/. The latest version of Performance Timeline is available at http://www.w3.org/TR/performance-timeline/.
- [High Resolution Time]
- High Resolution Time, Jatinder Mann, Editor. W3C Recommendation, World Wide Web Consortium, December 2012. This version of the High Resolution Time specification is available from http://www.w3.org/TR/2012/REC-hr-time-20121217/. The latest version of High Resolution Time is available at http://www.w3.org/TR/hr-time/.
- [Web IDL]
- Web IDL, Cameron McCormack, Editor. World Wide Web Consortium, April 2012. This version of the Web IDL specification is available from http://www.w3.org/TR/2012/CR-WebIDL-20120419/. The latest version of Web IDL is available at http://www.w3.org/TR/WebIDL/.