Abstract

This specification defines an interface for web applications to access the complete timing information for navigation of 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 is a work in progress and may change without any notices.

Navigation Timing 2 replaces the first version of [NAVIGATION-TIMING] and includes the following changes:

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. If you wish to make comments regarding this document, please send them to public-web-perf@w3.org (subscribe, archives) with [NavigationTiming] 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.

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 document is governed by the 1 September 2015 W3C Process Document.

Table of Contents

1. Introduction

This section is non-normative.

Accurately measuring performance characteristics of web applications is an important aspect of making web applications faster. While JavaScript-based mechanisms, such as the one described in [JSMEASURE], can provide comprehensive instrumentation for user latency measurements within an application, in many cases, they are unable to provide a complete or detailed end-to-end latency picture. For example, the following JavaScript shows a naive attempt to measure the time it takes to fully load a page:

Example 1
<html>
<head>
<script type="text/javascript">
var start = new Date().getTime();
function onLoad() {
  var now = new Date().getTime();
  var latency = now - start;
  alert("page loading time: " + latency);
}
</script>
</head>
<body onload="onLoad()">
<!- Main page body goes from here. -->
</body>
</html>

The above script calculates the time it takes to load the page after the first bit of JavaScript in the head is executed, but it does not give any information about the time it takes to get the page from the server, or the initialization lifecycle of the page.

This specification defines the PerformanceNavigationTiming interface which participates in the [PERFORMANCE-TIMELINE-2] to store and retrieve high resolution performance metric data related to the navigation of a document. As the PerformanceNavigationTiming interface uses [HR-TIME-2], all time values are measured from the start of the navigation. For example, if we know that the response end occurs 100ms after the start of navigation, we MAY find data that the PerformanceNavigationTiming data looks like so:

Example 2
startTime:           0.000  // start time of the navigation request
responseEnd:       100.000  // high resolution time of last received byte

The following script shows how a developer can use the PerformanceNavigationTiming interface to obtain accurate timing data related to the navigation of the document:

Example 3
<!doctype html>
<html>
<head>
</head>
<body onload="init()">
<script>
function init() {
  var navigationTiming = performance.getEntriesByType("navigation")[0];
  if (window.console) {
    console.log("Name: "       + navigationTiming.name      + "\n" +
                "Entry Type: " + navigationTiming.entryType + "\n" +
                "Start Time: " + navigationTiming.startTime + "\n" +
                "Duration: "   + navigationTiming.duration  + "\n" +
                "Unload: "     + (navigationTiming.unloadEventEnd -
                                  navigationTiming.unloadEventStart)  + "\n" +
                "Redirect: "   + (navigationTiming.redirectEnd -
                                  navigationTiming.redirectStart)     + "\n" +
                "App Cache: "  + (navigationTiming.domainLookupStart -
                                  navigationTiming.fetchStart)        + "\n" +
                "DNS: "        + (navigationTiming.domainLookupEnd -
                                  navigationTiming.domainLookupStart) + "\n" +
                "TCP: "        + (navigationTiming.connectEnd -
                                  navigationTiming.connectStart)      + "\n" +
                "Request: "    + (navigationTiming.responseStart -
                                  navigationTiming.requestStart)      + "\n" +
                "Response: "   + (navigationTiming.responseEnd -
                                  navigationTiming.responseStart)     + "\n" +
                "Processing: " + (navigationTiming.loadEventStart -
                                  navigationTiming.responseEnd)       + "\n" +
                "Onload: "     + (navigationTiming.loadEventEnd -
                                  navigationTiming.loadEventStart)    + "\n");
  }
}
</script>
</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 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 "navigation" refers to the act of navigating.

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]

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 [HR-TIME-2] specification.

4. Navigation Timing

4.1 The PerformanceNavigationTiming interface

The PerformanceNavigationTiming interface participates in the [PERFORMANCE-TIMELINE-2] and extends the following attributes of the PerformanceEntry interface:

name
This attribute MUST return the DOMString "document".
entryType
This attribute MUST return the DOMString "navigation".
startTime
This attribute MUST return a DOMHighResTimeStamp with a time value of 0. [HR-TIME-2]
duration
This attribute MUST return a DOMHighResTimeStamp equal to the difference between loadEventEnd and startTime, respectively.
interface PerformanceNavigationTiming : PerformanceEntry {
    readonly    attribute DOMHighResTimeStamp unloadEventStart;
    readonly    attribute DOMHighResTimeStamp unloadEventEnd;
    readonly    attribute DOMHighResTimeStamp workerStart;
    readonly    attribute DOMHighResTimeStamp redirectStart;
    readonly    attribute DOMHighResTimeStamp redirectEnd;
    readonly    attribute DOMHighResTimeStamp fetchStart;
    readonly    attribute DOMHighResTimeStamp domainLookupStart;
    readonly    attribute DOMHighResTimeStamp domainLookupEnd;
    readonly    attribute DOMHighResTimeStamp connectStart;
    readonly    attribute DOMHighResTimeStamp connectEnd;
    readonly    attribute DOMHighResTimeStamp secureConnectionStart;
    readonly    attribute DOMHighResTimeStamp requestStart;
    readonly    attribute DOMHighResTimeStamp responseStart;
    readonly    attribute DOMHighResTimeStamp responseEnd;
    readonly    attribute DOMHighResTimeStamp domLoading;
    readonly    attribute DOMHighResTimeStamp domInteractive;
    readonly    attribute DOMHighResTimeStamp domContentLoadedEventStart;
    readonly    attribute DOMHighResTimeStamp domContentLoadedEventEnd;
    readonly    attribute DOMHighResTimeStamp domComplete;
    readonly    attribute DOMHighResTimeStamp loadEventStart;
    readonly    attribute DOMHighResTimeStamp loadEventEnd;
    readonly    attribute DOMHighResTimeStamp prerenderSwitch;
    readonly    attribute NavigationType      type;
    readonly    attribute DOMString           nextHopProtocol;
    readonly    attribute unsigned short      redirectCount;
    readonly    attribute unsigned short      transferSize;
    readonly    attribute unsigned short      encodedBodySize;
    readonly    attribute unsigned short      decodedBodySize;
    serializer = {inherit, attribute};
};

4.1.1 Attributes

connectEnd of type DOMHighResTimeStamp, readonly

This attribute MUST return a DOMHighResTimeStamp with a time value equal to the time immediately after the user agent finishes establishing the connection to the server to retrieve the current document. If a persistent connection [RFC7230] is used or the current document is retrieved from relevant application caches [HTML5] or local resources, this attribute MUST return the value of domainLookupEnd

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 as well as other time interval such as SSL handshake and SOCKS authentication.

connectStart of type DOMHighResTimeStamp, readonly

This attribute MUST return a DOMHighResTimeStamp with a time value equal to the time immediately before the user agent start establishing the connection to the server to retrieve the document. If a persistent connection [RFC7230] is used or the current document is retrieved from relevant application caches or local resources, this attribute MUST return value of domainLookupEnd.

decodedBodySize of type unsigned short, readonly

This attribute MUST return the size, in octets received by the client, of the message body [RFC7230], after removing any applied content-codings [RFC7231].

domComplete of type DOMHighResTimeStamp, readonly

This attribute MUST return a DOMHighResTimeStamp with a time value equal to the time immediately before the user agent sets the current document readiness to "complete" [HTML5].

If the current document readiness changes to the same state multiple times, domLoading, domInteractive, domContentLoadedEventStart, domContentLoadedEventEnd and domComplete MUST return a DOMHighResTimeStamp with a time value equal to the time of the first occurrence of the corresponding document readiness change [HTML5].

domContentLoadedEventEnd of type DOMHighResTimeStamp, readonly

This attribute MUST return a DOMHighResTimeStamp with a time value equal to the time immediately after the document's DOMContentLoaded event completes.

domContentLoadedEventStart of type DOMHighResTimeStamp, readonly

This attribute MUST return a DOMHighResTimeStamp with a time value equal to the time immediately before the user agent fires the DOMContentLoaded event at the Document.

domInteractive of type DOMHighResTimeStamp, readonly

This attribute MUST return a DOMHighResTimeStamp with a time value equal to the time immediately before the user agent sets the current document readiness to "interactive" [HTML5].

domLoading of type DOMHighResTimeStamp, readonly

This attribute MUST return a DOMHighResTimeStamp with a time value equal to the time immediately before the user agent sets the current document readiness to "loading" [HTML5].

Warning

The domLoading attribute is deprecated and may be removed in future versions of this specification. Due to differences in when a Document object is created in existing user agents, the value returned by the domLoading is implementation specific and should not be used in meaningful metrics.

domainLookupEnd of type DOMHighResTimeStamp, readonly

This attribute MUST return a DOMHighResTimeStamp with a time value equal to the time immediately after the user agent finishes the domain name lookup for the current document. If a persistent connection [RFC7230] is used or the current document is retrieved from relevant application caches or local resources, this attribute MUST return the same value as fetchStart.

Note

Checking and retrieving contents from the HTTP cache [RFC7234] is part of the fetching process. It's covered by the requestStart, responseStart and responseEnd attributes.

Note

In case where the user agent already has the domain information in cache, domainLookupStart and domainLookupEnd represent the times when the user agent starts and ends the domain data retrieval from the cache.

domainLookupStart of type DOMHighResTimeStamp, readonly

This attribute MUST return a DOMHighResTimeStamp with a time value equal to the time immediately before the user agent starts the domain name lookup for the current document. If a persistent connection [RFC7230] is used or the current document is retrieved from relevant application caches or local resources, this attribute MUST return the same value as fetchStart.

encodedBodySize of type unsigned short, readonly

This attribute MUST return the size, in octets received by the client, of the payload body [RFC7230], prior to removing any applied content-codings [RFC7231].

fetchStart of type DOMHighResTimeStamp, readonly

If the new resource is to be fetched using HTTP GET or equivalent, fetchStart MUST return a DOMHighResTimeStamp with a time value equal to the time immediately before the user agent starts checking any relevant application caches. Otherwise, it MUST return a DOMHighResTimeStamp with a time value equal to the time when the user agent starts fetching the resource.

loadEventEnd of type DOMHighResTimeStamp, readonly

This attribute MUST return a DOMHighResTimeStamp with a time value equal to the time when the load event of the current document is completed. It MUST return a DOMHighResTimeStamp with a time value equal to zero when the load event is not fired or is not completed.

loadEventStart of type DOMHighResTimeStamp, readonly

This attribute MUST return a DOMHighResTimeStamp with a time value equal to the time immediately before the load event of the current document is fired. It MUST return a DOMHighResTimeStamp with a time value equal to zero when the load event is not fired yet.

nextHopProtocol of type DOMString, readonly

This attribute MUST return 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 this 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.

prerenderSwitch of type DOMHighResTimeStamp, readonly

This attribute MUST return a DOMHighResTimeStamp with a time value equal to the time immediately after the User Agent changes the visibilityState from prerender to visible [Page-Visibility]. If the document has not been prerendered by the User Agent [prerender], this attribute MUST return a DOMHighResTimeStamp with a time value equal to zero.

redirectCount of type unsigned short, readonly

This attribute MUST return the number of redirects since the last non-redirect navigation under the current browsing context. If there is no redirect or there is any redirect that is not from the same origin [RFC6454] as the destination document, this attribute MUST return zero.

redirectEnd of type DOMHighResTimeStamp, readonly

If there are HTTP redirects or equivalent when navigating and all redirects and equivalents are from the same origin, this attribute MUST return a DOMHighResTimeStamp with a time value equal to the time immediately after receiving the last byte of the response of the last redirect. Otherwise, this attribute MUST return a DOMHighResTimeStamp with a time value equal to zero.

redirectStart of type DOMHighResTimeStamp, readonly

If there are HTTP redirects or equivalent when navigating and if all the redirects or equivalent are from the same origin, this attribute MUST return a DOMHighResTimeStamp with a time value equal to the starting time of the fetch that initiates the redirect. Otherwise, this attribute MUST return a DOMHighResTimeStamp with a time value equal to zero.

requestStart of type DOMHighResTimeStamp, readonly

This attribute MUST return a DOMHighResTimeStamp with a time value equal to the time immediately before the user agent starts requesting the current document from the server, or from relevant application caches or from local resources.

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

Note

This interface does not include an attribute to represent the completion of sending the request, e.g., requestEnd.

  • Completion of sending the request from the user agent does not always indicate the corresponding completion time in the network transport, which brings most of the benefit of having such an attribute.
  • Some user agents have high cost to determine the actual completion time of sending the request due to the HTTP layer encapsulation.
responseEnd of type DOMHighResTimeStamp, readonly

This attribute MUST return a DOMHighResTimeStamp with a time value equal to the time immediately after the user agent receives the last byte of the current document or immediately before the transport connection is closed, whichever comes first. The document here can be received either from the server, relevant application caches or from local resources.

responseStart of type DOMHighResTimeStamp, readonly

This attribute MUST return a DOMHighResTimeStamp with a time value equal to 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.

secureConnectionStart of type DOMHighResTimeStamp, readonly

When a secure transport is used, this attribute MUST return the time immediately before the user agent starts the handshake process to secure the current connection. If a secure transport is not used, this attribute MUST return zero.

transferSize of type unsigned short, readonly

This attribute MUST return the size, in octets received by the client, consumed by the response header fields and the response payload body [RFC7230].

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 or TCP). If there are HTTP redirects or equivalent when navigating and if all the redirects or equivalent are from the same origin, this attribute SHOULD include the HTTP overhead of incurred redirects.

type of type NavigationType, readonly

This attribute MUST return a DOMString describing the type of the last non-redirect navigation in the current browsing context. It MUST have one of the NavigationType values.

Note

Client-side redirects, such as those using the Refresh pragma directive, are not considered HTTP redirects or equivalent by this spec. In those cases, the type attribute SHOULD return appropriate value, such as reload if reloading the current page, or navigate if navigating to a new URL.

unloadEventEnd of type DOMHighResTimeStamp, readonly

If the previous document and the current document have the same origin, this attribute MUST return a DOMHighResTimeStamp with a time value equal to the time immediately after the user agent finishes the unload event of the previous document. If there is no previous document or the previous document has a different origin than the current document or the unload is not yet completed, this attribute MUST return a DOMHighResTimeStamp with a time value equal to zero.

If there are HTTP redirects or equivalent when navigating and not all the redirects or equivalent are from the same origin, both unloadEventStart and unloadEventEnd MUST return a DOMHighResTimeStamp with a time value equal to zero.

unloadEventStart of type DOMHighResTimeStamp, readonly

If the previous document and the current document have the same origin [RFC6454], this attribute MUST return a DOMHighResTimeStamp with a time value equal to the time immediately before the user agent starts the unload event of the previous document. If there is no previous document or the previous document has a different origin than the current document, this attribute MUST return a DOMHighResTimeStamp with a time value equal to zero.

workerStart of type DOMHighResTimeStamp, readonly
If the current document has an active service worker registration ([SERVICE-WORKERS]), this attribute MUST return the time immediately before the user agent ran the worker required to service the request, or if the worker was already available, the time immediately before the user agent fired an event named `fetch` at the active worker. Otherwise, if there is no active worker this attribute MUST return zero.

4.1.2 Serializer

Instances of this interface are serialized as a map with entries from the closest inherited interface and with entries for each of the serializable attributes.

4.1.3 Navigation types

enum NavigationType {
    "navigate",
    "reload",
    "back_forward",
    "prerender"
};
Enumeration description
navigate

Navigation started by clicking on a link, or entering the URL in the user agent's address bar, or form submission, or initializing through a script operation other than the ones used by reload and back_forward as listed below.

reload

Navigation through the reload operation or the location.reload() method.

back_forward

Navigation through a history traversal operation.

prerender

Navigation initiated by a prerender hint.

5. Process

5.1 Processing Model

Fig. 1 This figure illustrates the timing attributes defined by the PerformanceNavigationTiming interface. Attributes in parenthesis may not be available in navigation involving documents from different origins. User agents may perform internal processing in between timings, which allow for non-normative intervals between timings.
Promptforunload redirect Appcache DNS TCP Request Response Processing load DOMContentLoaded unload startTime redirectStart fetchStart redirectEnd domainLookupStart domainLookupEnd connectStart secureConnectionStart connectEnd requestStart responseStart responseEnd domComplete loadEventEnd loadEventStart domLoading domInteractive domContentLoadedEventStart domContentLoadedEventEnd unloadEventStart unloadEventEnd
  1. If the navigation is aborted for any of the following reasons, abort these steps.
    1. The navigation is aborted due to the sandboxed navigation browsing context flag or the sandboxed top-level navigation browsing context flag, or a preexist attempt to navigate the browsing context.
    2. The navigation is caused by fragment identifiers within the page.
    3. The new resource is to be handled by some sort of inline content.
    4. The new resource is to be handled using a mechanism that does not affect the browsing context.
    5. The user refuses to allow the document to be unloaded.
  2. Create a new PerformanceNavigationTiming object.
  3. Set name to the DOMString "document".
  4. Set entryType to the DOMString "navigation".
  5. Set startTime to a DOMHighResTimeStamp with a time value of zero, and nextHopProtocol to the empty DOMString.
  6. Record the current navigation type in type if it has not been set:
    1. If the navigation was started by clicking on a link, or entering the URL in the user agent's address bar, or form submission, or initializing through a script operation other than the location.reload() method, let the navigation type be the DOMString "navigate".
    2. If the navigation was started either as a result of a meta refresh, or the location.reload() method, or other equivalent actions, let the navigation type be the DOMString "reload".
    3. If the navigation was started as a result of history traversal, let the navigation type be the DOMString "back_forward".
  7. If the current document and the previous document are from different origins, set both unloadEventStart and unloadEventEnd to 0 then go to step 9. Otherwise, record unloadEventStart as the time immediately before the unload event.
  8. Immediately after the unload event is completed, record the current time as unloadEventEnd. If the navigation URL has an active worker registration, immediately before the user agent runs the worker record the time as workerStart, or if the worker is available, record the time before the event named `fetch` is fired at the active worker. Otherwise, if the navigation URL has no matching service worker registration, set workerStart value to zero.
  9. If the new resource is to be fetched using HTTP GET or equivalent, immediately before a user agent checks with the relevant application caches, record the current time as fetchStart. Otherwise, immediately before a user agent starts the fetching process, record the current time as fetchStart.
  10. Let domainLookupStart, domainLookupEnd, connectStart and connectEnd be the same value as fetchStart.
  11. If the resource is fetched from the relevant application cache or local resources, including the HTTP cache [RFC7234], go to step 16.
  12. If no domain lookup is required, go to step 14. Otherwise, immediately before a user agent starts the domain name lookup, record the time as domainLookupStart.
  13. 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 rest of the steps.
  14. 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 rest of the steps.
  15. A user agent MUST also set the secureConnectionStart attribute as follows:
    1. When a secure transport is used, the user agent MUST record the time as secureConnectionStart immediately before the handshake process to secure the connection.
    2. When a secure transport is not used, the user agent MUST set the value of secureConnectionStart to 0.
  16. Immediately before a user agent starts sending request for the document, record the current time as requestStart.
  17. Record the time as responseStart immediately after the user agent receives the first byte of the response.
  18. Record the time as responseEnd immediately after receiving the last byte of the response.
    1. Return to step 14 if the user agent fails to send the request or receive the entire response, and needs to reopen the connection.
      Note

      When persistent connection [RFC7230] is enabled, a user agent MAY first try to re-use an open connect to send the request while the connection can be asynchronously closed. In such case, connectStart, connectEnd and requestStart SHOULD represent timing information collected over the re-open connection.

    2. Set the value of transferSize, encodedBodySize, decodedBodySize to corresponding values.
  19. If the fetched resource results in an HTTP redirect or equivalent, then
    1. if the current document and the document that is redirected to are not from the same origin, set redirectStart, redirectEnd, unloadEventStart, unloadEventEnd and redirectCount to 0. Then, return to step 9 with the new resource.
    2. if there is previous redirect involving documents that are not from the same origin, set redirectStart, redirectEnd, unloadEventStart, unloadEventStart and redirectCount to 0. Then, return to step 9 with the new resource.
    3. Increment redirectCount by 1.
    4. If the value of redirectStart is 0, let it be the value of fetchStart.
    5. Let redirectEnd be the value of responseEnd.
    6. Set all of the attributes in the PerformanceNavigationTiming object to 0 except startTime, redirectStart, redirectEnd, redirectCount, type, nextHopProtocol, unloadEventStart and unloadEventEnd. Set nextHopProtocol to the empty DOMString.
    7. Return to step 9 with the new resource.
  20. Record the time as domLoading immediately before the user agent sets the current document readiness to "loading".
  21. Record the time as domInteractive immediately before the user agent sets the current document readiness to "interactive".
  22. Record the time as domContentLoadedEventStart immediately before the user agent fires the DOMContentLoaded event at the document.
  23. Record the time as domContentLoadedEventEnd immediately after the DOMContentLoaded event completes.
  24. Record the time as domComplete immediately before the user agent sets the current document readiness to "complete".
  25. Record the time as loadEventStart immediately before the user agent fires the load event.
  26. Record the time as loadEventEnd immediately after the user agent completes the load event.
  27. Record the time as prerenderSwitch immediately after the user agent changes the visibilityState from prerender to visible. Otherwise, set this attribute to 0.
  28. Set the duration to a DOMHighResTimeStamp equal to the difference between loadEventEnd and startTime, respectively.

Some user agents maintain the DOM structure of the document in memory during navigation operations such as forward and backward. In those cases, the PerformanceNavigationTiming object MUST NOT be altered during the navigation.

6. Privacy

This section is non-normative.

6.1 Information disclosure

There is the potential for disclosing an end-user's browsing and activity history by using carefully crafted timing attacks. For instance, the unloading time reveals how long the previous page takes to execute its unload handler, which could be used to infer the user's login status. These attacks have been mitigated by enforcing the same origin policy when timing information involving the previous navigation is accessed. [RFC6454]

The relaxed same origin policy doesn't provide sufficient protection against unauthorized visits across documents. In shared hosting, an untrusted third party is able to host an HTTP server at the same IP address but on a different port.

6.2 Cross-directory access

Different pages sharing one host name, for example contents from different authors hosted on sites with user generated content are considered from the same origin because there is no feature to restrict the access by pathname. Navigating between these pages allows a latter page to access timing information of the previous one, such as timing regarding redirection and unload event.

7. Security

This section is non-normative.

7.1 Detecting proxy servers

In case a proxy is deployed between the user agent and the web server, the time interval between the connectStart and the connectEnd attributes indicates the delay between the user agent and the proxy instead of the web server. With that, web server can potentially infer the existence of the proxy. For SOCKS proxy, this time interval includes the proxy authentication time and time the proxy takes to connect to the web server, which obfuscate the proxy detection. In case of an HTTP proxy, the user agent might not have any knowledge about the proxy server at all so it's not always feasible to mitigate this attack.

A. Historical

This section defines attributes and interfaces previously introduced in [NAVIGATION-TIMING] and are kept here for legacy purposes. Authors are advised to use the PerformanceNavigationTiming interface instead.

All time values defined in this appendix are measured in milliseconds since midnight of .

A.1 The PerformanceTiming interface

[Exposed=Window]
interface PerformanceTiming {
    readonly    attribute unsigned long long navigationStart;
    readonly    attribute unsigned long long unloadEventStart;
    readonly    attribute unsigned long long unloadEventEnd;
    readonly    attribute unsigned long long redirectStart;
    readonly    attribute unsigned long long redirectEnd;
    readonly    attribute unsigned long long fetchStart;
    readonly    attribute unsigned long long domainLookupStart;
    readonly    attribute unsigned long long domainLookupEnd;
    readonly    attribute unsigned long long connectStart;
    readonly    attribute unsigned long long connectEnd;
    readonly    attribute unsigned long long secureConnectionStart;
    readonly    attribute unsigned long long requestStart;
    readonly    attribute unsigned long long responseStart;
    readonly    attribute unsigned long long responseEnd;
    readonly    attribute unsigned long long domLoading;
    readonly    attribute unsigned long long domInteractive;
    readonly    attribute unsigned long long domContentLoadedEventStart;
    readonly    attribute unsigned long long domContentLoadedEventEnd;
    readonly    attribute unsigned long long domComplete;
    readonly    attribute unsigned long long loadEventStart;
    readonly    attribute unsigned long long loadEventEnd;
    serializer = {attribute};
};

A.1.1 Attributes

connectEnd of type unsigned long long, readonly

This attribute must return the time immediately after the user agent finishes establishing the connection to the server to retrieve the current document. If a persistent connection [RFC2616] is used or the current document is retrieved from relevant application caches or local resources, this attribute must return the value of domainLookupEnd

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 as well as other time interval such as SSL handshake and SOCKS authentication.

connectStart of type unsigned long long, readonly

This attribute must return the time immediately before the user agent start establishing the connection to the server to retrieve the document. If a persistent connection [RFC2616] is used or the current document is retrieved from relevant application caches or local resources, this attribute must return value of domainLookupEnd.

domComplete of type unsigned long long, readonly

This attribute must return the time immediately before the user agent sets the current document readiness to "complete".

If the current document readiness changes to the same state multiple times, domLoading, domInteractive, domContentLoadedEventStart, domContentLoadedEventEnd and domComplete must return the time of the first occurrence of the corresponding document readiness change.

domContentLoadedEventEnd of type unsigned long long, readonly

This attribute must return the time immediately after the document's DOMContentLoaded event completes.

domContentLoadedEventStart of type unsigned long long, readonly

This attribute must return the time immediately before the user agent fires the DOMContentLoaded event at the Document.

domInteractive of type unsigned long long, readonly

This attribute must return the time immediately before the user agent sets the current document readiness to "interactive".

domLoading of type unsigned long long, readonly

This attribute must return the time immediately before the user agent sets the current document readiness to "loading".

domainLookupEnd of type unsigned long long, readonly

This attribute must return the time immediately after the user agent finishes the domain name lookup for the current document. If a persistent connection [RFC2616] is used or the current document is retrieved from relevant application caches or local resources, this attribute must return the same value as fetchStart.

This section is non-normative.

Checking and retrieving contents from the HTTP cache [RFC2616] is part of the fetching process. It's covered by the requestStart, responseStart and responseEnd attributes.

Example

In case where the user agent already has the domain information in cache, domainLookupStart and domainLookupEnd represent the times when the user agent starts and ends the domain data retrieval from the cache.

domainLookupStart of type unsigned long long, readonly

This attribute must return the time immediately before the user agent starts the domain name lookup for the current document. If a persistent connection [RFC2616] is used or the current document is retrieved from relevant application caches or local resources, this attribute must return the same value as fetchStart.

fetchStart of type unsigned long long, readonly

If the new resource is to be fetched using HTTP GET or equivalent, fetchStart must return the time immediately before the user agent starts checking any relevant application caches. Otherwise, it must return the time when the user agent starts fetching the resource.

loadEventEnd of type unsigned long long, readonly

This attribute must return the time when the load event of the current document is completed. It must return zero when the load event is not fired or is not completed.

loadEventStart of type unsigned long long, readonly

This attribute must return the time immediately before the load event of the current document is fired. It must return zero when the load event is not fired yet.

navigationStart of type unsigned long long, readonly

This attribute must return the time immediately after the user agent finishes prompting to unload the previous document. If there is no previous document, this attribute must return the time the current document is created.

redirectEnd of type unsigned long long, readonly

If there are HTTP redirects or equivalent when navigating and all redirects and equivalents are from the same origin, 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.

redirectStart of type unsigned long long, readonly

If there are HTTP redirects or equivalent when navigating and if all the redirects or equivalent are from the same origin, this attribute must return the starting time of the fetch that initiates the redirect. Otherwise, this attribute must return zero.

requestStart of type unsigned long long, readonly

This attribute must return the time immediately before the user agent starts requesting the current document from the server, or from relevant application caches or from local resources.

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

Note

This interface does not include an attribute to represent the completion of sending the request, e.g., requestEnd.

  • Completion of sending the request from the user agent does not always indicate the corresponding completion time in the network transport, which brings most of the benefit of having such an attribute.
  • Some user agents have high cost to determine the actual completion time of sending the request due to the HTTP layer encapsulation.
responseEnd of type unsigned long long, readonly

This attribute must return the time immediately after the user agent receives the last byte of the current document or immediately before the transport connection is closed, whichever comes first. The document here can be received either from the server, relevant application caches or from local resources.

responseStart of type unsigned long long, readonly

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.

secureConnectionStart of type unsigned long long, readonly

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 this attribute is available but HTTPS is not used, this attribute must return zero.

unloadEventEnd of type unsigned long long, readonly

If the previous document and the current document have the same same origin, this attribute must return the time immediately after the user agent finishes the unload event of the previous document. If there is no previous document or the previous document has a different origin than the current document or the unload is not yet completed, this attribute must return zero.

If there are HTTP redirects or equivalent when navigating and not all the redirects or equivalent are from the same origin, both unloadEventStart and unloadEventEnd must return the zero.

unloadEventStart of type unsigned long long, readonly

If the previous document and the current document have the same origin [RFC6454], this attribute must return the time immediately before the user agent starts the unload event of the previous document. If there is no previous document or the previous document has a different origin than the current document, this attribute must return zero.

A.1.2 Serializer

Instances of this interface are serialized as a map with entries for each of the serializable attributes.

A.2 The PerformanceNavigation interface

[Exposed=Window]
interface PerformanceNavigation {
    const unsigned short TYPE_NAVIGATE = 0;
    const unsigned short TYPE_RELOAD = 1;
    const unsigned short TYPE_BACK_FORWARD = 2;
    const unsigned short TYPE_RESERVED = 255;
    readonly    attribute unsigned short type;
    readonly    attribute unsigned short redirectCount;
    serializer = {attribute};
};

A.2.1 Attributes

redirectCount of type unsigned short, readonly

This attribute must return the number of redirects since the last non-redirect navigation under the current browsing context. If there is no redirect or there is any redirect that is not from the same origin as the destination document, this attribute must return zero.

type of type unsigned short, readonly

This attribute must return the type of the last non-redirect navigation in the current browsing context. It must have one of the following navigation type values.

Note

Client-side redirects, such as those using the Refresh pragma directive, are not considered HTTP redirects or equivalent by this spec. In those cases, the type attribute should return appropriate value, such as TYPE_RELOAD if reloading the current page, or TYPE_NAVIGATE if navigating to a new URL.

A.2.2 Constants

TYPE_BACK_FORWARD of type unsigned short

Navigation through a history traversal operation.

TYPE_NAVIGATE of type unsigned short

Navigation started by clicking on a link, or entering the URL in the user agent's address bar, or form submission, or initializing through a script operation other than the ones used by TYPE_RELOAD and TYPE_BACK_FORWARD as listed below.

TYPE_RELOAD of type unsigned short

Navigation through the reload operation or the location.reload() method.

TYPE_RESERVED of type unsigned short

Any navigation types not defined by values above.

A.2.3 Serializer

Instances of this interface are serialized as a map with entries for each of the serializable attributes.

A.3 Extensions to the Performance interface

[Exposed=Window]
partial interface Performance {
    [SameObject]
    readonly    attribute PerformanceTiming     timing;
    [SameObject]
    readonly    attribute PerformanceNavigation navigation;
};

A.3.1 Attributes

navigation of type PerformanceNavigation, readonly

The navigation attribute is defined by the PerformanceNavigation interface.

timing of type PerformanceTiming, readonly

The timing attribute represents the timing information related to the browsing contexts since the last non-redirect navigation. This attribute is defined by the PerformanceTiming interface.

B. Acknowledgments

We would like to offer our sincere thanks to James Simonsen, Tony Gentilcore, Zhiheng Wang, Karen Anderson and Jason Weber for all their contributions to this work.

C. References

C.1 Normative references

[HR-TIME-2]
Ilya Grigorik; James Simonsen; Jatinder Mann. High Resolution Time Level 2. 21 July 2015. W3C Working Draft. URL: http://www.w3.org/TR/hr-time-2/
[HTML5]
Ian Hickson; Robin Berjon; Steve Faulkner; Travis Leithead; Erika Doyle Navara; Edward O'Connor; Silvia Pfeiffer. HTML5. 28 October 2014. W3C Recommendation. URL: http://www.w3.org/TR/html5/
[PERFORMANCE-TIMELINE-2]
Ilya Grigorik. Performance Timeline Level 2. 15 September 2015. W3C Working Draft. URL: http://www.w3.org/TR/performance-timeline-2/
[Page-Visibility]
Jatinder Mann; Arvind Jain. Page Visibility (Second Edition). 29 October 2013. W3C Recommendation. URL: http://www.w3.org/TR/page-visibility/
[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119
[RFC2616]
R. Fielding; J. Gettys; J. Mogul; H. Frystyk; L. Masinter; P. Leach; T. Berners-Lee. Hypertext Transfer Protocol -- HTTP/1.1. June 1999. Draft Standard. URL: https://tools.ietf.org/html/rfc2616
[RFC6454]
A. Barth. The Web Origin Concept. December 2011. Proposed Standard. URL: https://tools.ietf.org/html/rfc6454
[RFC7230]
R. Fielding, Ed.; J. Reschke, Ed.. Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing. June 2014. Proposed Standard. URL: https://tools.ietf.org/html/rfc7230
[RFC7231]
R. Fielding, Ed.; J. Reschke, Ed.. Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content. June 2014. Proposed Standard. URL: https://tools.ietf.org/html/rfc7231
[RFC7301]
S. Friedl; A. Popov; A. Langley; E. Stephan. Transport Layer Security (TLS) Application-Layer Protocol Negotiation Extension. July 2014. Proposed Standard. URL: https://tools.ietf.org/html/rfc7301
[SERVICE-WORKERS]
Alex Russell; Jungkee Song; Jake Archibald. Service Workers. 25 June 2015. W3C Working Draft. URL: http://www.w3.org/TR/service-workers/
[WebIDL]
Cameron McCormack; Boris Zbarsky. WebIDL Level 1. 4 August 2015. W3C Working Draft. URL: http://www.w3.org/TR/WebIDL-1/

C.2 Informative references

[ECMA-262]
Allen Wirfs-Brock. ECMA-262 6th Edition, The ECMAScript 2015 Language Specification. June 2015. Standard. URL: http://www.ecma-international.org/ecma-262/6.0/
[JSMEASURE]
Ramakrishnan Rajamony; Mootaz Elnozahy. Measuring Client-Perceived Response Times on the WWW. March 2001. The Proceedings of the 3rd USENIX Symposium on Internet Technologies and Systems (USITS). URL: http://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.69.7329&rep=rep1&type=pdf
[NAVIGATION-TIMING]
Zhiheng Wang. Navigation Timing. 17 December 2012. W3C Recommendation. URL: http://www.w3.org/TR/navigation-timing/
[RFC7234]
R. Fielding, Ed.; M. Nottingham, Ed.; J. Reschke, Ed.. Hypertext Transfer Protocol (HTTP/1.1): Caching. June 2014. Proposed Standard. URL: https://tools.ietf.org/html/rfc7234
[prerender]
Link type "prerender". URL: http://microformats.org/wiki/rel-prerender