Abstract

This specification defines an interface for web applications to access
timing information related to HTML elements.

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

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.

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.

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. While Navigation Timing [NavigationTiming] address
part of the problem by providing timing information associated with a
navigation, this document introduces the ResourceTiming
interface to allow Javascript mechanisms to collect complete timing
information related to resources on a document.

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 http://w3c-test.org.
One could further measure the amount of time it takes in every phase of fetching a resource
with the PerformanceResourceTiming interface.

2 Conformance
requirements

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

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 Core specifications. [DOM3CORE]

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

Throughout this work, time is measured in milliseconds since midnight of January 1, 1970 (UTC).

The PerformanceResourceTiming
interface must include all resources fetched from the networking layer by the current browsing context. Resources that are
retrieved from the user agent's networking layer cache must be included in the
PerformanceResourceTiming
interface.

The rest of this section is non-normative.

Examples:

If the same canonical URL is used as the src attribute of two IMG elements,
the fetch of the resource initiated by the first IMG element should be included in the
PerformanceResourceTiming interface. The user agent might not re-request the
URL from the networking layer for the second IMG element, instead using an in-memory browser cache.
In this case, there is only a single request sent to the networking layer for retrieval, so the fetch of the resource by the first
IMG element would be the only occurrence in the PerformanceResourceTiming
interface.

If the src attribute of an 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 in the PerformanceResourceTiming interface.

If a XMLHttpRequest is generated twice for the same canonical URL, both fetches of the resource would be
included in the PerformanceResourceTiming interface. This is because the user agent must validate
both requests from the networking layer, even if the resource is in a disk cache from the first request.

If an IMG element has a data: URI as its source, then this resource will not
be included in the PerformanceResourceTiming interface. By definition data: URI
contains embedded data and does not require access to the networking layer.

The user agent may choose to limit how many resources are included in the
PerformanceResourceTiming
interface. The recommended maximum number of resources is 150, though this may be changed by the user agent.
setResourceTimingBufferSize
can be called to request a change to this limit.

type attribute

This attribute must return the type of object that initiated the request for the resource:

INITIATOR_OTHER: the initiator is not of any type listed below.

INITIATOR_LINK: the initiator is a LINK element.

INITIATOR_CSS: the initiator is a CSS.

INITIATOR_SCRIPT: the initiator is SCRIPT element.

INITIATOR_IMAGE: the initiator is an IMG element.

INITIATOR_OBJECT: the initiator is an OBJECT element.

INITIATOR_FRAME: the initiator is a FRAME element.

INITIATOR_SUBDOCUMENT: the initiator is an IFRAME element.

INITIATOR_XMLHTTPREQUEST: the initiator is a XMLHttpRequest object.

INITIATOR_EMBED: the initiator is an EMBED element.

INITIATOR_AUDIO: the initiator is an AUDIO element.

INITIATOR_VIDEO: the initiator is a VIDEO element.

INITIATOR_SVG: the initiator is a SVG element.

INITIATOR_RESERVED: this is reserved for future use.

url attribute

This attribute must return the resolved URL of the
requested resource. The attribute must not change even if the fetch redirected to a different URL.

resourceStart attribute

This attribute must return 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, this attribute must return the same value as redirectStart. Otherwise, this attribute must
return the same value as fetchStart.

If there are HTTP redirects or equivalent
when fetching the resource and if any of the redirects are not from the same origin as the current document,
and the Timing-Allow-Origin HTTP response header rules are met, this attribute must
return the starting time of the fetch that initiates the redirect.
Otherwise, this attribute must return zero.

redirectEnd attribute

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,
this attribute must return 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 if any of the redirects are not from the same origin as the current document,
and the Timing-Allow-Origin HTTP response header rules are met, this attribute must return the
time immediately after receiving the last byte of the response of the last redirect.
Otherwise, this attribute must return zero.

fetchStart attribute

This attribute must return the time immediately before the user agent starts to fetch the
resource.

If the transport connection fails and the user agent reopens a connection,
connectStart and connectEnd should return the corresponding
values of the new connection.

connectEnd must include the time interval to
establish the transport connection. It must not include other time interval
such as SSL handshake and SOCKS authentication.

If the last non-redirected fetch of the resource is not the same origin as the current document,
connectEnd must return
zero unless the Timing-Allow-Origin HTTP response header rules apply.

secureConnectionStart attribute

This attribute is optional. User agents that don't have this attribute available must set it as undefined.
When this attribute is available, if the scheme
of the current page is HTTPS, this attribute must return the
time immediately before the user agent starts the handshake process to secure the current connection. If the
secureConnectionStart attribute is available but HTTPS is not used, this attribute must return zero.

If the last non-redirected fetch of the resource is not the same origin as the current document,
secureConnectionStart must return
zero unless the Timing-Allow-Origin HTTP response header rules apply.

requestStart attribute

This attribute must return the time immediately before the user agent
starts requesting the resource. It is set prior to checking HTTP cache.

If the transport connection fails after a request is sent and the user
agent reopens a connection and resend the request, requestStart must return the corresponding values
of the new request.

If the last non-redirected fetch of the resource is not the same origin as the current document,
requestStart must return
zero unless the Timing-Allow-Origin HTTP response header rules apply.

responseStart attribute

This attribute must return the time immediately after the user agent receives
the first byte of the response from the server, or from relevant
application caches or from local resources.

If the last non-redirected fetch of the resource is not the same origin as the current document,
responseStart must return
zero unless the Timing-Allow-Origin HTTP response header rules apply.

responseEnd attribute

This attribute must return the time immediately after the user agent finishes
receiving the last byte of the resource from from relevant
application caches or from local resources.

clearResourceTimings is called - The PerformanceResourceTimingList will begin with the
n+1th item if it exists and the first n elements are released, where n is the maximum number of resources allowed in the PerformanceResourceTiming
interface. If the n+1th item does not exist, the buffer is cleared. The max length of the PerformanceResourceTimingList
does not change unless otherwise specified by setResourceTimingBufferSize.

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.

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. ABNF:

5 Process

5.1 Processing Model

Illustration

This section is non-normative.

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.

If no domain lookup is required, go to step 3.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 following 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. If a connection can not be established, abort the following steps.

If the user agent supports the secureConnectionStart attribute,
in step 3.13, a user agent should also carry out these additional steps:

If the scheme of the current resource is HTTPS, the user agent must record the
time as secureConnectionStart
immediately before the handshake process to secure the connection.

If the scheme of the current resource is not HTTPS, 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 3.13 if the user agent fails to send the request
or receive the entire response, and needs to reopen the connection.

If the setResourceTimingBufferSize method is called in the onbufferfull callback,
set the maximum size of the primary buffer to the maxSize parameter. If the maxSize parameter is larger than the previous size of the primary buffer,
append PerformanceResourceTiming objects in the temporary buffer to the primary buffer up to the maxSize parameter.

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 during the navigation. The difference between any two chronologically
recorded timing attributes must never be negative. The user agent must record the system clock at the beginning
of the navigation and define subsequent timing attributes in terms of a monotonic clock measuring time elapsed
from the beginning of the navigation.

6 Privacy

This section is non-normative.

When giving various timing information of how a resource is requested and
process, the ResourceTiming interface potentially
exposes such information to any page that has this resource included. To
limit the access to the ResourceTiming interface, the same origin
policy is enforced by default. Additionally, resource providers can
explicitely allow timing information to be collected over a resource by
adding the allow-timing meta tag to the HTML header, which specifies the
domains that are allowed to access the timing information.

XMLHttpRequest,
Anne van Kesteren, Editor. World Wide Web Consortium, August
2010. This version of the XMLHttpRequest Candidate Recommendation
is
http://www.w3.org/TR/2010/CR-XMLHttpRequest-20100803/. The latest version of
XMLHttpRequest is available at
http://www.w3.org/TR/XMLHttpRequest/.