This specification defines an interface for web applications to
access the complete timing information for resources in a
document.
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/.
Warning
Implementers SHOULD be aware that this document
is not stable. Implementers who are not taking part in the
discussions are likely to find the specification changing out from
under them in incompatible ways. Vendors interested in implementing
this document before it eventually reaches the Candidate
Recommendation stage SHOULD join the aforementioned mailing lists
and take part in the discussions.
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 [ResourceTiming] 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.
User latency is an important quality benchmark for Web
Applications. While JavaScript-based mechanisms can provide
comprehensive instrumentation for user latency measurements within
an application, in many cases, they are unable to provide a
complete end-to-end latency picture. This document introduces the
PerformanceResourceTiming interface to allow JavaScript
mechanisms to collect complete timing information related to
resources on a document. Navigation Timing 2
[NAVIGATION-TIMING-2] extends this specification to provide
additional timing information associated with a navigation.
For example, the following JavaScript shows a simple attempt to
measure the time it takes to fetch a resource:
Example 1
<!doctype html><html><head></head><bodyonload="loadResources()"><script>functionloadResources()
{
var start = newDate().getTime();
var image1 = new Image();
var resourceTiming = function() {
var now = newDate().getTime();
var latency = now - start;
alert("End to end resource fetch: " + latency);
};
image1.onload = resourceTiming;
image1.src = 'https://www.w3.org/Icons/w3c_main.png';
}
</script><imgsrc="https://www.w3.org/Icons/w3c_home.png"></body></html>
Though this script can measure the time it takes to fetch a
resource, it cannot break down the time spent in various phases.
Further, the script cannot easily measure the time it takes to
fetch resources described in markup.
To address the need for complete information on user experience,
this document introduces the PerformanceResourceTiming
interface. This interface allows JavaScript mechanisms to provide
complete client-side latency measurements within applications. With
this interface, the previous example can be modified to measure a
user's perceived load time of a resource.
The following script calculates the amount of time it takes to
fetch every resource in the page, even those defined in markup.
This example assumes that this page is hosted on
https://www.w3.org. One could further measure the amount of time it
takes in every phase of fetching a resource with the
PerformanceResourceTiming interface.
Example 2
<!doctype html><html><head></head><bodyonload="loadResources()"><script>functionloadResources()
{
var image1 = new Image();
image1.onload = resourceTiming;
image1.src = 'https://www.w3.org/Icons/w3c_main.png';
}
functionresourceTiming()
{
var resourceList = window.performance.getEntriesByType("resource");
for (i = 0; i < resourceList.length; i++)
{
if (resourceList[i].initiatorType == "img")
{
alert("End to end resource fetch: " + (resourceList[i].responseEnd - resourceList[i].startTime));
}
}
}
</script><imgid="image0"src="https://www.w3.org/Icons/w3c_home.png"></body></html>
2. Conformance
As well as sections marked as non-normative, all authoring guidelines, diagrams, examples,
and notes in this specification are non-normative. Everything else in this specification is
normative.
The key words MAY, MUST, MUST NOT, SHOULD, and SHOULD NOT are
to be interpreted as described in [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 [WEBIDL-1] specification.
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]
specification.
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. [ECMASCRIPT]
The term resource is used to refer to elements and
any other user-initiated fetches throughout this specification. For
example, a resource could originate from XMLHttpRequest objects
[XHR], HTML elements [HTML] such as iframe, img, script,
object, embed, and link with the link type of stylesheet, and SVG
elements [SVG11] such as svg.
The term cross-origin is used to mean non
same origin.
Throughout this work, all time values are measured in
milliseconds since the start of navigation of the document
[HR-TIME-2]. 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.
Note
This definition of time is based on the High
Resolution Time specification [HR-TIME-2] and is different from
the definition of time used in the Navigation Timing specification
[NAVIGATION-TIMING-2], where time is measured in milliseconds
since midnight of January 1, 1970 (UTC).
If the same canonical URL is used as the src
attribute of two HTML IMG elements, the fetch of the resource initiated by the
first HTML IMG element SHOULD be included as a
PerformanceResourceTiming object in the Performance
Timeline. The user agent might not re-request the URL for the
second HTML IMG element, instead using the existing
download it initiated for the first HTML IMG element.
In this case, the fetch of
the resource by the first IMG element would be the
only occurrence in the Performance
Timeline.
If the src attribute of a HTML IMG
element is changed via script, both the fetch of the original resource as well
as the fetch of the new
URL would be included as PerformanceResourceTiming objects
in the Performance
Timeline.
If an HTML IFRAME element is added via markup
without specifying a src attribute, the user agent may
load the about:blank document for the
IFRAME. If at a later time the src
attribute is changed dynamically via script, the user agent may
fetch the new URL resource
for the IFRAME. In this case, only the fetch of the new URL would be included
as a PerformanceResourceTiming object in the Performance
Timeline.
If an XMLHttpRequest is generated twice for the
same canonical URL, both fetches of the resource would be
included as a PerformanceResourceTiming object in the
Performance
Timeline. This is because the fetch of the resource for the second
XMLHttpRequest cannot reuse the download issued for
the first XMLHttpRequest.
If an HTML IFRAME element is included on the page,
then only the resource requested by IFRAMEsrc attribute is included as a
PerformanceResourceTiming object in the Performance
Timeline. Sub-resources requested by the IFRAME
document will be included in the IFRAME document's
Performance
Timeline and not the parent document's Performance
Timeline.
If a resource fetch
was aborted due to a networking error (e.g. DNS, TCP, or TLS
error), then the fetch MAY be included as a
PerformanceResourceTiming object in the Performance
Timeline with initialized attribute values up to the point of
failure - e.g. a TCP handshake error should report DNS timestamps
for the request, and so on.
If a resource fetch is
aborted because it failed a fetch precondition (e.g. mixed content,
CORS restriction, CSP policy, etc), then this resource SHOULD NOT
not be included as a PerformanceResourceTiming object in the
Performance
Timeline.
This attribute MUST return the resolved URL of the requested resource.
This attribute MUST NOT change even if the fetch redirected to a different
URL.
entryType
The entryType attribute MUST return the DOMString
"resource".
startTime
The startTime attribute MUST return a DOMHighResTimeStamp
[HR-TIME-2] with the time immediately before the user agent
starts to queue the resource for fetching. If there are
HTTP redirects or equivalent when
fetching the resource, and if all the redirects or equivalent are
from the same origin as the
current document or the timing allow check algorithm passes,
this attribute MUST return the same value as redirectStart.
Otherwise, this attribute MUST return the same value as
fetchStart.
On getting, the
attribute nextHopProtocol returns the network protocol
used to fetch the resource, as identified by the ALPN Protocol ID
[RFC7301]; resources retrieved from relevant application caches
or local resources, return an empty string. The registry for
protocol identifiers lists the possible values for the
ALPN Protocol IDs. When a proxy is configured, if a tunnel
connection is established then this attribute MUST return the ALPN
Protocol ID of the tunneled protocol, otherwise it MUST return the
ALPN Protocol ID of the first hop to the proxy. In order to have
precisely one way to represent any ALPN protocol ID, the following
additional constraints apply: octets in the ALPN protocol MUST NOT
be percent-encoded if they are valid token characters except "%",
and when using percent-encoding, uppercase hex digits MUST be
used.
Note that the nextHopProtocol attribute is
intended to identify the network protocol in use for the fetch
regardless of how it was actually negotiated; that is, even if ALPN
is not used to negotiate the network protocol, this attribute still
uses the ALPN Protocol ID's to indicate the protocol in use.
On getting, the
workerStart attribute MUST return as follows:
the time immediately before the user agent runs the worker
required to service the request.
zero, otherwise.
On getting, the
redirectStart attribute MUST return as follows:
The time immediately before the user agent starts to
fetch the resource that
initiates the redirect, if there are HTTP redirects or
equivalent when fetching the resource and
all the redirects or equivalent pass the timing
allow check algorithm.
zero, otherwise.
On getting, the
redirectEnd attribute MUST return as follows:
The time immediately after receiving the last byte of the
response of the last redirect, if there are HTTP redirects or
equivalent when fetching the resource and
all the redirects or equivalent pass the timing
allow check algorithm.
zero, otherwise.
On getting, the
fetchStart attribute MUST return as follows:
The time immediately before the user agent starts to
fetch the final
resource in the redirection, if there are HTTP redirects or
equivalent.
The time immediately before the user agent starts to
fetch the resource
otherwise.
On getting, the
domainLookupStart attribute MUST return as follows:
The time immediately after the user agent before the domain
data retrieval from the domain information cache, if the user agent
has the domain information in cache.
The time immediately before the user agent starts the domain
name lookup for the resource, if the last non-redirected
fetch of the resource
passes the timing allow check algorithm.
zero, otherwise.
On getting, the
domainLookupEnd attribute MUST return as follows:
The time immediately after the user agent ends the domain data
retrieval from the domain information cache, if the user agent has
the domain information in cache.
The time immediately before the user agent finishes the domain
name lookup for the resource, if the last non-redirected
fetch of the resource
passes the timing allow check algorithm.
zero, otherwise.
On getting, the
connectStart attribute MUST return as follows:
The time immediately before the user agent start establishing
the connection to the server to retrieve the resource, if the last
non-redirected fetch of
the resource passes the timing allow check algorithm.
If the transport connection fails and the user agent reopens a
connection, connectStartSHOULD return the
corresponding value of the new connection.
zero, otherwise.
On getting, the
connectEnd attribute MUST return as follows:
The time immediately after the user agent finish establishing
the connection to the server to retrieve the resource, if the last
non-redirected fetch of
the resource passes the timing allow check algorithm.
The returned time MUST include the time interval to establish
the transport connection, as well as other time intervals such as
SSL handshake and SOCKS authentication.
If the transport connection fails and the user agent reopens a
connection, connectEndSHOULD return the
corresponding value of the new connection.
zero, otherwise.
On getting, the
secureConnectionStart attribute MUST return as
follows:
The time immediately before the user agent starts the handshake
process to secure the current connection, if a secure transport is
used and the last non-redirected fetch of the resource passes the
timing allow check algorithm.
zero, otherwise.
On getting, the
requestStart attribute MUST return as follows:
The time immediately before the user agent starts requesting
the resource from the server, or from relevant application caches
or from local resources, if the last non-redirected fetch of the resource passes the
timing allow check algorithm.
If the transport connection fails after a request is sent and
the user agent reopens a connection and resend the request,
requestStartMUST
return the corresponding values of the new request.
zero, otherwise.
Note
On getting, the
responseStart attribute MUST return as follows:
The time immediately after the user agent's HTTP parser
receives the first byte of the response (e.g. frame header bytes
for HTTP/2, or response status line for HTTP/1.x) from
relevant
application caches, or from local resources or from the server
if the last non-redirected fetch of the resource passes the
timing allow check algorithm.
zero, otherwise.
Note
On getting, the
responseEnd attribute MUST return as follows:
The time immediately after the user agent receives the last
byte of the response or immediately before the transport connection
is closed, whichever comes first. The resource here can be received
either from relevant application
caches, local resources, or from the server.
The time immediately before the user agent aborts the fetch due
to a network error.
On getting, the
transferSize attribute MUST return as follows:
If there are HTTP redirects or equivalent when navigating
and if all the redirects or equivalent are from the same
origin [RFC6454], this
attribute SHOULD include the HTTP overhead of incurred
redirects.
This attribute SHOULD include HTTP overhead (such as HTTP/1.1
chunked encoding and whitespace around header fields, including
newlines, and HTTP/2
frame overhead, along with other server-to-client frames on the
same stream), but SHOULD NOT include lower-layer protocol overhead
(such as TLS [RFC5246]or TCP).
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 zero due to the
cross-origin restrictions previously specified in this
section.
4.5.1 Timing-Allow-Origin Response Header
The Timing-Allow-Origin HTTP response header field
can be used to communicate a policy indicating origin(s) that are
allowed to see values of attributes that would have been zero due
to the cross-origin restrictions. The header's value is represented
by the following ABNF [RFC5234] (using List Extension, [RFC7230]):
The sender MAY generate multiple Timing-Allow-Origin
header fields. The recipient MAY combine multiple
Timing-Allow-Origin header fields by appending each
subsequent field value to the combined field value in order,
separated by a comma.
The timing allow check algorithm, which checks
whether a resource's timing information can be shared with the
current document, is as follows:
The following graph illustrates the timing attributes defined by
the PerformanceResourceTiming interface. Attributes in parenthesis may
not be available when fetching resources from different origins. User agents may perform internal
processing in between timings, which allow for non-normative
intervals between timings.
Figure 1This figure illustrates the timing attributes defined
by the PerformanceResourceTiming interface. Attributes in
parenthesis indicate that they may not be available if the resource
does not pass the timing allow check algorithm.
For each resource fetched by the current browsing context, excluding resources
fetched by cross-origin stylesheets fetched with
no-cors policy, perform the following steps:
Issue
Above cross-origin exclusion should be defined via
Fetch registry: CSS needs to be defined in terms of Fetch and set
some kind of "opaque request flag" for no-CORS CSS subresources. In
turn, Resource Timing should interface with Fetch registry to
surface resource fetch events.
Immediately before the user agent starts to queue the resource
for retrieval, record the current time in startTime,
and set nextHopProtocol to the empty DOMString.
Record the initiator of the resource in
initiatorType.
If no domain lookup is required, go to step 12. Otherwise, immediately before a
user agent starts the domain name lookup, record the time as
domainLookupStart.
Record the time as domainLookupEnd immediately after the
domain name lookup is successfully done. A user agent may need
multiple retries before that. If the domain name lookup fails and
resource passes the timing allow check record the time as
domainLookupEnd and go to step 17.
If a persistent transport
connection is used to fetch the resource, let
connectStart and connectEnd be the same value of
domainLookupEnd. Otherwise, record the time as
connectStart immediately before initiating the connection to
the server and record the time as connectEnd immediately
after the connection to the server or the proxy is established. A
user agent may need multiple retries before this time. Once
connection is established set the value of nextHopProtocol
to the ALPN ID used by the connection. If a connection can not be
established, record the time up to the connection failure as
connectEnd and go to step
17.
When a secure transport is used, the user agent MUST record the
time as secureConnectionStart immediately before the
handshake process to secure the connection.
When a secure transport is not used, the user agent MUST set
the value of secureConnectionStart to 0.
Immediately before a user
agent starts sending the request for the resource, record the
current time as requestStart.
Record the time as responseStart immediately after the user agent receives the
first byte of the response.
Record the time as responseEnd immediately after receiving the last byte of
the response.
Return to step 12 if the
user agent fails to send the request or receive the entire
response, and needs to reopen the connection.
This specification does not
specify whether steps 20 and 21 should run before or after the
load event of the resource—see issue 82 for
related discussion.
Background: #55. In #79 we added a note to flag the implementation differences across browsers. Ideally, we should aim to converge on a consistent implementation:
It would be great to get some interop tests to identify where/how existing implementations differ on whether the entry is made available before or after the load event.
Real-world telemetry on how often developers rely on querying entry from within onload would, also, be very helpful.
5.2 Monotonic Clock
The value of the timing attributes MUST monotonically increase
to ensure timing attributes are not skewed by adjustments to the
system clock while fetching the resource. The difference between any two
chronologically recorded timing attributes MUST never be negative.
For all resources, including subdocument resources, the user agent
MUST record the system clock at the beginning of the root document
navigation and define subsequent timing attributes 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 PerformanceResourceTiming interface exposes timing
information for a resource to any web page or worker that has
requested that resource. To limit the access to the
PerformanceResourceTiming interface, the same origin policy is enforced by default
and certain attributes are set to zero, as described in 4.5Cross-origin Resources. Resource providers can
explicitly allow all timing information to be collected for a
resource by adding the Timing-Allow-Origin HTTP response
header, which specifies the domains that are allowed to access the
timing information.
Statistical fingerprinting is a privacy concern where a
malicious web site may determine whether a user has visited a
third-party web site by measuring the timing of cache hits and
misses of resources in the third-party web site. Though the
PerformanceResourceTiming interface gives timing information
for resources in a document, the cross-origin restrictions prevent
making this privacy concern any worse than it is today using the
load event on resources to measure timing to determine cache hits
and misses.
A. Acknowledgments
Thanks to Anne Van Kesteren, Annie Sullivan, Arvind Jain, Boris
Zbarsky, Darin Fisher, Jason Weber, Jonas Sicking, James Simonsen,
Karen Anderson, Kyle Scholz, Nic Jansma, Philippe Le Hegaret,
Sigbjørn Vik, Steve Souders, Todd Reifsteck, Tony Gentilcore and
William Chan for their contributions to this work.
