Abstract

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 http://www.w3.org/TR/.

This specification is ready for wide review, with the following features at risk for the first release:

This document was published by the Web Performance Working Group as a Working Draft.
This document is intended to become a W3C Recommendation.
If you wish to make comments regarding this document, please send them to
public-web-perf@w3.org
(subscribe,
archives)
with [ResourceTiming] at the start of your email's subject.
All comments are welcome.

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.

1. Introduction

This section is non-normative.

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:

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.

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 Web IDL
specification. [WebIDL]

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. [DOM]

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. [ECMA-262]

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 [[XMLHttpRequest], HTML elements [HTML5] such as iframe, img, script, object, embed, and link with the link type of stylesheet, and SVG elements [SVG11] such as svg.

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],
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 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 a resource fetch was aborted due to a networking error (e.g. DNS, TCP, or TLS error), then the fetch would 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.

4.3 The PerformanceResourceTiming Interface

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.

"css", if the initiator is a CSS resource downloaded by the url() syntax [CSS-SYNTAX-3], such as @import url() or background: url().

"xmlhttprequest", if the initiator is an XMLHttpRequest object [XMLHttpRequest].

On getting, the attribute nextHopProtocol returns the network protocol used to fetch the resource, as identified by the ALPN Protocol ID [RFC7301]. 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.

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.

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.

The time immediately after 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.

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.

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, or from local resources or from the server if the last non-redirected fetch of the resource passes the timing allow check algorithm.

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).

Note

It is possible for transferSize value to be lower than encodedBodySize: when a cached response is successfully revalidated the transferSize reports the size of the response HTTP headers incurred during the revalidation, and encodedBodySize reports the size of the previously retrieved payload body.

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 header indicates whether a resource's timing can be
shared based by returning the value of the Origin request header in the
response.

The above algorithm also functions when the
ASCII serialization of an origin is
the string "null". Typically, this is the case when there are multiple redirects and the initiator is an XMLHttpRequest object.

Note

In practice the
origin-list-or-null production is
more constrained. Rather than allowing a space-separated list of
origins, it is either a
single origin or the string
"null".

5. Process

5.1 Processing Model

The following graph illustrates the timing attributes defined by the PerformanceResourceTiming interface. Attributes underlined 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.

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 1

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.

If no domain lookup is required, go to step 13. 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 lookup fails, abort the remaining steps.

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, abort the remaining steps.

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.