Navigation Timing Level 2

W3C Working Draft

More details about this document
This version:
https://www.w3.org/TR/2022/WD-navigation-timing-2-20220310/
Latest published version:
https://www.w3.org/TR/navigation-timing-2/
Latest editor's draft:
https://w3c.github.io/navigation-timing/
History:
https://www.w3.org/standards/history/navigation-timing-2
Commit history
Test suite:
https://wpt.fyi/navigation-timing/
Editors:
Yoav Weiss (Google)
(Invited Expert)
Former editors:
Ilya Grigorik (Google)
(Microsoft Corp.) - Until
(Microsoft Corp.) - Until
(Google Inc.) - Until
Feedback:
GitHub w3c/navigation-timing (pull requests, new issue, open issues)
public-web-perf@w3.org with subject line [NavigationTiming] (archives)
Browser support (caniuse.com):
  • 13–101
  • 6–12
  • 4–5
  • 7–98
  • 2–6
  • 8–15.4
  • 3.1–7.1
  • 12–98
More info

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

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

This document was published by the Web Performance Working Group as a Working Draft using the Recommendation track.

Publication as a Working Draft does not imply endorsement by W3C and its Members.

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.

This document is governed by the 2 November 2021 W3C Process Document.

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:

<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], all time values are measured with respect to the time origin of the Window object.

For example, if we know that the response end occurs 100ms after the start of navigation, the PerformanceNavigationTiming data could look like so:

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:

<script>
function showNavigationDetails() {
  // Get the first entry
  const [entry] = performance.getEntriesByType("navigation");
  // Show it in a nice table in the developer console
  console.table(entry.toJSON());
}
</script>
<body onload="showNavigationDetails()">

2. 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 current document refers to the document associated with the Window object's newest Document object.

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] specification.

3. Navigation Timing

3.1 Relation to the PerformanceEntry interface

PerformanceNavigationTiming interface extends the following attributes of PerformanceEntry interface:

Note

A user agent implementing PerformanceNavigationTiming would need to include "navigation" in supportedEntryTypes for Window contexts. This allows developers to detect support for Navigation Timing.

3.2 Relation to the PerformanceResourceTiming interface

PerformanceNavigationTiming interface extends the following attributes of the PerformanceResourceTiming interface:

Note

Only the current document resource is included in the performance timeline; there is only one PerformanceNavigationTiming object in the performance timeline.

3.3 The PerformanceNavigationTiming interface

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.

WebIDL[Exposed=Window]
interface PerformanceNavigationTiming : PerformanceResourceTiming {
    readonly        attribute DOMHighResTimeStamp  unloadEventStart;
    readonly        attribute DOMHighResTimeStamp  unloadEventEnd;
    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 NavigationTimingType type;
    readonly        attribute unsigned short       redirectCount;
    [Default] object toJSON();
};

A PerformanceNavigationTiming has an associated document load timing info document load timing.

A PerformanceNavigationTiming has an associated document unload timing info previous document unload timing.

A PerformanceNavigationTiming has an associated number redirect count.

A PerformanceNavigationTiming has an associated NavigationTimingType navigation type.

A PerformanceNavigationTiming has an associated null or service worker timing info service worker timing.

The unloadEventStart getter steps are to return this's previous document unload timing's unload event start time.

Note

If the previous document and the current document have the same origin, this timestamp is measured 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 will return zero.

The unloadEventEnd getter steps are to return this's previous document unload timing's unload event end time.

Note

If the previous document and the current document have the same origin, this timestamp is measured immediately after the user agent handles 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 will return zero.

The domInteractive getter steps are to return this's document load timing's DOM interactive time.

Note

This timestamp is measured before the user agent sets the current document readiness to "interactive".

The domContentLoadedEventStart getter steps are to return this's document load timing's DOM content loaded event start time.

Note

This timestamp is measured before the user agent dispatches the DOMContentLoaded event.

The domContentLoadedEventEnd getter steps are to return this's document load timing's DOM content loaded event end time.

Note

This timestamp is measured after the user agent completes handling of the DOMContentLoaded event.

The domComplete getter steps are to return this's document load timing's DOM complete time.

Note

This timestamp is measured before the user agent sets the current document readiness to "complete". See document readiness for a precise definition.

The loadEventStart getter steps are to return this's document load timing's load event start time.

Note

This timestamp is measured before the user agent dispatches the load event for the document.

The loadEventEnd getter steps are to return this's document load timing's load event end time.

Note

This timestamp is measured after the user agent completes handling the load event for the document.

The type getter steps are to run the this's navigation type.

Note

Client-side redirects, such as those using the Refresh pragma directive, are not considered HTTP redirects 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.

The redirectCount getter steps are to return this's redirect count.

The toJSON() method runs the default toJSON steps for this.

3.3.1 NavigationTimingType enum

WebIDLenum NavigationTimingType {
    "navigate",
    "reload",
    "back_forward",
    "prerender"
};

The values are defined as follows:

navigate
Navigation where the history handling behavior is set to "default" or "replace" and the navigation was not initiated by a prerender hint [RESOURCE-HINTS].
reload
Navigation where the history handling behavior is set to "reload".
back_forward
Navigation where the history handling behavior is set to "entry update".
prerender
Navigation initiated by a prerender hint [RESOURCE-HINTS].
Note

The format of the above enumeration value is inconsistent with the WebIDL recommendation for formatting of enumeration values. Unfortunately, we are unable to change it due to backwards compatibility issues with shipped implementations. [WebIDL]

4. Process

4.1 Processing Model

Figure 1 This figure illustrates the timing attributes defined by the PerformanceNavigationTiming interface. Attributes in parenthesis indicate that they may not be available for navigations involving documents from different origins.
Navigation Timing attributes

5. Creating a navigation timing entry

Each document has an associated navigation timing entry, initially unset.

To create the navigation timing entry for Document document, given a fetch timing info fetchTiming, a number redirectCount, a NavigationTimingType navigationType, and a null or service worker timing info serviceWorkerTiming, do the following:

  1. Let global be document's relevant global object.
  2. Let navigationTimingEntry be a new PerformanceNavigationTiming object in global's realm.
  3. Setup the resource timing entry for navigationTimingEntry given "navigation", document's address, and fetchTiming.
  4. Set navigationTimingEntry's document load timing to document's load timing info
  5. Set navigationTimingEntry's previous document unload timing to document's previous document unload timing.
  6. Set navigationTimingEntry's redirect count to redirectCount.
  7. Set navigationTimingEntry's navigation type to navigationType.
  8. Set navigationTimingEntry's service worker timing to serviceWorkerTiming.
  9. Set document's navigation timing entry to navigationTimingEntry.
  10. add navigationTimingEntry to global's performance entry buffer.

To queue the navigation timing entry for Document document, queue document's navigation timing entry.

6. Privacy Considerations

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 check algorithm when unloading a document, as detailed in the HTML spec.

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 Considerations

This section is non-normative.

The PerformanceNavigationTiming interface exposes timing information about the previous document to the current document. To limit the access to PerformanceNavigationTiming attributes which include information on the previous document, the previous document unloading algorithm enforces the same origin policy and attributes related to the previous document are set to zero.

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.

8. Obsolete

This section defines attributes and interfaces previously introduced in [NAVIGATION-TIMING] Level 1 and are kept here for backwards compatibility. Authors should not use the following interfaces and are strongly advised to use the new PerformanceNavigationTiming interface—see summary of changes and improvements.

8.1 The PerformanceTiming interface

WebIDL[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;
  [Default] object toJSON();
};
Note

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

navigationStart

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.

Note

This attribute is not defined for PerformanceNavigationTiming. Instead, authors can use timeOrigin to obtain an equivalent timestamp.

unloadEventStart

If the previous document and the current document have the same origin, 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.

unloadEventEnd

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 when navigating and not all the redirects are from the same origin, both PerformanceTiming.unloadEventStart and PerformanceTiming.unloadEventEnd must return zero.

redirectStart

If there are HTTP redirects when navigating and if all the redirects 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.

redirectEnd

If there are HTTP redirects when navigating and all redirects 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.

fetchStart

If the new resource is to be fetched using a "GET" request method, fetchStart must return the time immediately before the user agent starts checking the HTTP cache. Otherwise, it must return the time when the user agent starts fetching the resource.

domainLookupStart

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 the HTTP cache or local resources, this attribute must return the same value as PerformanceTiming.fetchStart.

domainLookupEnd

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 the HTTP cache or local resources, this attribute must return the same value as PerformanceTiming.fetchStart.

Note

Checking and retrieving contents from the HTTP cache [RFC2616] is part of the fetching process. It's covered by the PerformanceTiming.requestStart, PerformanceTiming.responseStart and PerformanceTiming.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.

connectStart

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 the HTTP cache or local resources, this attribute must return value of PerformanceTiming.domainLookupEnd.

connectEnd

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 the HTTP cache or local resources, this attribute must return the value of PerformanceTiming.domainLookupEnd.

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

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

secureConnectionStart

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

requestStart

This attribute must return the time immediately before the user agent starts requesting the current document from the server, or from the HTTP cache 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, PerformanceTiming.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.
responseStart

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

responseEnd

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, the HTTP cache or from local resources.

domLoading

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

Warning

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.

domInteractive

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

domContentLoadedEventStart

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

domContentLoadedEventEnd

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

domComplete

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, PerformanceTiming.domLoading, PerformanceTiming.domInteractive, PerformanceTiming.domContentLoadedEventStart, PerformanceTiming.domContentLoadedEventEnd and PerformanceTiming.domComplete must return the time of the first occurrence of the corresponding document readiness change.

loadEventStart

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.

loadEventEnd

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.

toJSON()
Runs the default toJSON steps for this.

8.2 The PerformanceNavigation interface

WebIDL[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;
  [Default] object toJSON();
};
TYPE_NAVIGATE

Navigation where the history handling behavior is set to "default" or "replace".

TYPE_RELOAD

Navigation where the history handling behavior is set to "reload".

TYPE_BACK_FORWARD

Navigation where the history handling behavior is set to "entry update".

TYPE_RESERVED

Any navigation types not defined by values above.

type

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

redirectCount

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.

toJSON()
Runs the default toJSON steps for this.

8.3 Extensions to the Performance interface

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

The Performance interface is defined in [PERFORMANCE-TIMELINE-2].

timing

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.

navigation

The navigation attribute is defined by the PerformanceNavigation interface.

9. 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 word SHOULD in this document is to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

A. Acknowledgments

Thanks to Anne Van Kesteren, Arvind Jain, Boris Zbarsky, Jason Weber, Jonas Sicking, James Simonsen, Karen Anderson, Nic Jansma, Philippe Le Hegaret, Steve Souders, Todd Reifsteck, Tony Gentilcore, William Chan and Zhiheng Wang for their contributions to this work.

B. References

B.1 Normative references

[dom]
DOM Standard. Anne van Kesteren. WHATWG. Living Standard. URL: https://dom.spec.whatwg.org/
[FETCH]
Fetch Standard. Anne van Kesteren. WHATWG. Living Standard. URL: https://fetch.spec.whatwg.org/
[HR-TIME]
High Resolution Time. Yoav Weiss. W3C. 28 January 2022. W3C Working Draft. URL: https://www.w3.org/TR/hr-time-3/
[HTML]
HTML Standard. Anne van Kesteren; Domenic Denicola; Ian Hickson; Philip Jägenstedt; Simon Pieters. WHATWG. Living Standard. URL: https://html.spec.whatwg.org/multipage/
[NAVIGATION-TIMING]
Navigation Timing. Zhiheng Wang. W3C. 17 December 2012. W3C Recommendation. URL: https://www.w3.org/TR/navigation-timing/
[PERFORMANCE-TIMELINE-2]
Performance Timeline. Nicolas Pena Moreno. W3C. 2 December 2021. W3C Candidate Recommendation. URL: https://www.w3.org/TR/performance-timeline/
[RESOURCE-HINTS]
Resource Hints. Ilya Grigorik. W3C. 5 October 2020. W3C Working Draft. URL: https://www.w3.org/TR/resource-hints/
[RESOURCE-TIMING-2]
Resource Timing Level 2. Yoav Weiss; Noam Rosenthal. W3C. 27 January 2022. W3C Working Draft. URL: https://www.w3.org/TR/resource-timing-2/
[RFC2119]
Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc2119
[RFC2616]
Hypertext Transfer Protocol -- HTTP/1.1. R. Fielding; J. Gettys; J. Mogul; H. Frystyk; L. Masinter; P. Leach; T. Berners-Lee. IETF. June 1999. Draft Standard. URL: https://www.rfc-editor.org/rfc/rfc2616
[RFC7234]
Hypertext Transfer Protocol (HTTP/1.1): Caching. R. Fielding, Ed.; M. Nottingham, Ed.; J. Reschke, Ed.. IETF. June 2014. Proposed Standard. URL: https://httpwg.org/specs/rfc7234.html
[RFC8174]
Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words. B. Leiba. IETF. May 2017. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc8174
[service-workers]
Service Workers 1. Alex Russell; Jungkee Song; Jake Archibald; Marijn Kruisselbrink. W3C. 19 November 2019. W3C Candidate Recommendation. URL: https://www.w3.org/TR/service-workers-1/
[URL]
URL Standard. Anne van Kesteren. WHATWG. Living Standard. URL: https://url.spec.whatwg.org/
[WEBIDL]
Web IDL Standard. Edgar Chen; Timothy Gu. WHATWG. Living Standard. URL: https://webidl.spec.whatwg.org/

B.2 Informative references

[HR-TIME-2]
High Resolution Time Level 2. Ilya Grigorik. W3C. 21 November 2019. W3C Recommendation. URL: https://www.w3.org/TR/hr-time-2/
[JSMEASURE]
Measuring Client-Perceived Response Times on the WWW. Ramakrishnan Rajamony; Mootaz Elnozahy. 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