Copyright © 2017 W3C® (MIT, ERCIM, Keio, Beihang). W3C liability, trademark and permissive document license rules apply.
This specification defines an interface for web applications to access the complete timing information for navigation of a document.
This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at https://www.w3.org/TR/.
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.
This document is intended to become a W3C Recommendation.
Comments regarding this document are welcome. Please send them to
public-web-perf@w3.org
(subscribe,
archives)
with [NavigationTiming]
at the start of your email's subject.
Publication as a Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.
This document was produced by a group operating under the W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.
This document is governed by the 1 March 2017 W3C Process Document.
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-2], 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()">
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 current document refers to the document associated with the Window object's newest Document object.
The term JavaScript is used to refer to ECMA262, rather than the official term ECMAScript, since the term JavaScript is more widely known. [ECMASCRIPT]
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.
PerformanceNavigationTiming
object and add it to the
performance entry buffer.
name
to the DOMString
"document
".
entryType
and initiatorType to the
DOMString
"navigation
".
startTime
to a DOMHighResTimeStamp
with a time value of zero, and
nextHopProtocol
to the empty
DOMString
.
type
if it has not been set:
DOMString
"navigate
".
DOMString
"reload
".
DOMString
"back_forward
".
unloadEventStart
and
unloadEventEnd
to
0 then go to fetch-start-step.
Otherwise, record unloadEventStart
as the time
immediately before the unload event.
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.
fetchStart
. Otherwise, immediately before a user
agent starts the fetching process, record the current time as
fetchStart
.
domainLookupStart
,
domainLookupEnd
,
connectStart
and
connectEnd
be the same value as
fetchStart
.
name
to a DOMString
value of the
address of
the current document.
domainLookupStart
.
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.
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.
secureConnectionStart
attribute as follows:
secureConnectionStart
immediately before the
handshake process to secure the connection.
secureConnectionStart
to 0.
requestStart
.
responseStart
immediately after the user agent
receives the first byte of the response.
responseEnd
immediately after receiving the last
byte of the response.
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.
transferSize
,
encodedBodySize
,
decodedBodySize
to corresponding values.
redirectStart
,
redirectEnd
, unloadEventStart
,
unloadEventEnd
and
redirectCount
to 0. Then,
return to fetch-start-step with
the new resource.
redirectCount
by 1.
redirectStart
is 0, let it be the value of
fetchStart
.
redirectEnd
be the value of
responseEnd
.
PerformanceNavigationTiming
object to 0 except
startTime
,
redirectStart
,
redirectEnd
, redirectCount
,
type
,
nextHopProtocol
, unloadEventStart
and
unloadEventEnd
. Set
nextHopProtocol
to the empty
DOMString
.
domInteractive
immediately before
the user agent sets the current document
readiness to "interactive".
domContentLoadedEventStart
immediately before the user agent fires the DOMContentLoaded event at the
document.
domContentLoadedEventEnd
immediately after the DOMContentLoaded event completes.
domComplete
immediately before the
user agent sets the current document
readiness to "complete".
loadEventStart
immediately before
the user agent fires the load event.
loadEventEnd
immediately after the
user agent completes the load event.
duration
to a DOMHighResTimeStamp
equal to the difference between loadEventEnd
and startTime
,
respectively.
PerformanceNavigationTiming
object.
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.
This section is non-normative.
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 timing allow check algorithm when timing information involving the previous navigation is accessed. [RESOURCE-TIMING-2]
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.
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.
This section is non-normative.
The PerformanceNavigationTiming
interface exposes timing information for the current document to
any resource loaded by the document, such as a web page or a worker. To
limit the access to the PerformanceNavigationTiming
interface, the timing
allow check algorithm is enforced and certain attributes are set to
zero, as described in 4.5 Cross-origin Resources [RESOURCE-TIMING].
Resource providers can explicitly allow all timing information to be
collected for a current document by adding the
Timing-Allow-Origin
HTTP response header, which specifies
the domains that are allowed to access the timing information.
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.
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.
PerformanceTiming
interface
[Exposed=Window]
interface PerformanceTiming
{
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();
};
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.
unloadEventStart
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.
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 or equivalent when navigating and not all the redirects or equivalent are from the same origin, both unloadEventStart and unloadEventEnd must return the zero.
redirectStart
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.
redirectEnd
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.
fetchStart
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.
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 relevant application caches or local resources, this attribute must return the same value as 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 relevant application caches or local resources, this attribute must return the same value as fetchStart.
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.
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 relevant application caches or local resources, this attribute must return value of 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 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.
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 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.
This interface does not include an attribute to represent the completion of sending the request, e.g., requestEnd.
responseStart
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.
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, relevant application caches or from local resources.
domLoading
This attribute must return the time immediately before the user agent sets the current document readiness to "loading".
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, domLoading, domInteractive, domContentLoadedEventStart, domContentLoadedEventEnd and 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()
Performance
interface
[Exposed=Window]
partial interface Performance
{
[SameObject]
readonly attribute PerformanceTiming
timing
;
};
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.
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, and SHOULD are to be interpreted as described in [RFC2119].
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.