Please refer to the errata for this document, which may include some normative corrections.
See also translations.
Copyright © 2013 W3C® (MIT, ERCIM, Keio, Beihang), All Rights Reserved. W3C liability, trademark and document use rules apply.
This specification defines an unified interface to store and retrieve performance metric data. This specification does not cover individual performance metric interfaces.
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 the W3C Recommendation of "Performance Timeline Specification", produced by the Web Performance Working Group. An implementation report produced in August 2013 is available.
No changes were made since the previous publication.
By publishing this Recommendation, W3C expects that the functionality specified in this Performance Timeline Recommendation will not be affected by changes to Web IDL as this specification proceed to Recommendation.
Please send comments to [email protected] (archived) with [PerformanceTimeline] 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. It is a stable document and may be used as reference material or cited from another document. W3C's role in making the Recommendation is to draw attention to the specification and to promote its widespread deployment. This enhances the functionality and interoperability of the Web.
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.
Accurately measuring performance characteristics of web applications is an important aspect of making web applications faster. [Navigation Timing], [Resource Timing], and [User Timing] are examples of specifications that define timing information related to the navigation of the document, resources on the page, and developer scripts, respectively.
Together these interfaces, and potentially others created in the future, define performance metrics that describe the performance timeline of a web application. This specification provides an unifying interface to access and retrieve these various performance metrics from the performance timeline of a web application.
The following script shows how a developer can use the PerformanceEntry
interface
to obtain timing data related to the navigation of the document, resources on the page and developer scripts.
<!doctype html> <html> <head> </head> <body onload="init()"> <img id="image0" src="http://w3c-test.org/webperf/image0.png" /> <script> function init() { performance.mark("startWork"); // see [User Timing] doWork(); // Some developer code performance.mark("endWork"); measurePerf(); } function measurePerf() { var perfEntries = performance.getEntries(); 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 RFC 2119. For readability, these words do not appear in all uppercase letters in this specification.
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
".
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).
All interfaces that participate in the Performance Timeline, such as the
PerformanceResourceTiming
[Resource Timing],
PerformanceMark
, and
PerformanceMeasure
[User Timing] interfaces,
must adhere to the following rules:
PerformanceEntry
interfacegetEntries
,
getEntriesByType
, and
getEntriesByName
methods
PerformanceEntry
interfaceinterface PerformanceEntry { readonly attribute DOMString name; readonly attribute DOMString entryType; readonly attribute DOMHighResTimeStamp startTime; readonly attribute DOMHighResTimeStamp duration; };
name
attribute
The name
attribute must return the identifier for this PerformanceEntry
object. This
identifier does not have to be unique.
entryType
attribute
The entryType
attribute must return a DOMString
that describes the type of the interface represented by this PerformanceEntry
object.
The Web Performance/entryType wiki page lists all of the known entryType
values.
startTime
attribute
The startTime
attribute must return a DOMHighResTimeStamp
that contains the time value of the first recorded timestamp of this performance metric.
duration
attribute
The duration
attribute must return a DOMHighResTimeStamp
that contains the time value of the duration of the entire event being recorded by this PerformanceEntry
. Typically, this would be the
time difference between the last recorded timestamp and the first recorded timestamp of this PerformanceEntry
. A performance metric may choose
to return a duration
of 0, if the duration concept doesn't apply.
Performance
interfacepartial interface Performance { PerformanceEntryList getEntries(); PerformanceEntryList getEntriesByType(DOMString entryType); PerformanceEntryList getEntriesByName(DOMString name, optional DOMString entryType); }; typedef sequence <PerformanceEntry> PerformanceEntryList;
The window.performance
attribute provides a hosting area for performance measurement related attributes and methods using the Performance
interface [Navigation Timing].
getEntries
methodThe getEntries
method returns a
PerformanceEntryList
object that contains a copy of all PerformanceEntry
objects in chronological order with respect to startTime.
getEntriesByType
methodThe getEntriesByType
method returns a
PerformanceEntryList
object that contains a copy of all PerformanceEntry
objects, in chronological order with respect to startTime,
that have the same value for the entryType
attribute of PerformanceEntry
as the entryType
parameter.
Parameter
DOMString
entryType
A PerformanceEntryList
object that contains a copy of PerformanceEntry
objects
that have the same value for the entryType
attribute of PerformanceEntry
as the entryType
parameter.
If no such PerformanceEntry
objects exist, the PerformanceEntryList
must be empty.
Return value
APerformanceEntryList
object.
No exceptions
getEntriesByName
method
The getEntriesByName
method returns a
PerformanceEntryList
object that contains a copy of PerformanceEntry
objects, in chronological order with respect to startTime,
that have the same value for the name
attribute of PerformanceEntry
as the name
parameter
and, if specified, have the same value for the entryType
attribute of PerformanceEntry
as the entryType
parameter.
Parameter
DOMString
name
The PerformanceEntryList
object that contains a copy of PerformanceEntry
objects
that have the same value for the name
attribute of PerformanceEntry
as the name
parameter.
If no such PerformanceEntry
objects exist, the PerformanceEntryList
must be empty.
DOMString
entryType
The PerformanceEntryList
object that only contains a copy of PerformanceEntry
objects
that have the same value for the entryType
attribute of PerformanceEntry
as the entryType
parameter
and have the same value for the name
attribute of PerformanceEntry
as the name
parameter.
If no such PerformanceEntry
objects exist, the PerformanceEntryList
must be empty.
Return value
APerformanceEntryList
object.
No exceptions
If a vendor-specific proprietary user agent extension is needed to create experimental
PerformanceEntry
objects, on getting the
entryType
IDL attribute, vendors MUST return a DOMString that uses the following convention:
[vendorprefix]-[entrytype]
Where,
[vendorprefix]
is a non-capitalized name that identifies the vendor,
[entrytype]
is a non-capitalized name given to the type of the interface
represented by this PerformanceEntry
object,
We would like to offer our sincere thanks to all the people that we have been in touch with regarding this draft for their reviews and feedback.