This specification defines a unified interface to store and retrieve high resolution performance metric data
related to the 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 document is the First Public Working Draft of the Navigation Timing 2 specification.
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.
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 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.
To address the need for complete and detailed information on the navigation of the
document, the Navigation Timing
specification defines the PerformanceTiming
interface. This interface allows JavaScript mechanisms to provide complete client-side latency
measurements within applications.
However, the PerformanceTiming
interface was not defined to provide data in sub-millisecond resolution, which can be useful for analysis purposes.
Further, the PerformanceTiming interface
does not participate in the
Performance Timeline, a unifying
interface to access and retrieve performance metrics from the performance timeline of a web application.
Additionally, the PerformanceTiming
interface measures the time of its attributes from January 01 1970, leading to very large numbers representing the time values.
For example, if we know that the response end occurs 100ms after the start of navigation, we may find data that the
the PerformanceTiming data looks like so:
For example, if we know that the response end occurs 100ms after the start of navigation, we may find data that the
the PerformanceNavigationTiming data looks like so:
navigationStart: 0.000
responseEnd: 100.000
The following script shows how a developer can use the PerformanceNavigationTiming interface
to obtain accurate timing data related to the navigation of the document.
All diagrams, examples, and notes in this specification are non-normative,
as are all sections explicitly marked non-normative. Everything else in this
specification is normative.
The key words "MUST", "MUST NOT", "REQUIRED", "SHOULD", "SHOULD NOT",
"RECOMMENDED", "MAY", and "OPTIONAL" in the normative parts of this document
are to be interpreted as described in RFC 2119.
For readability, these words do not appear in all uppercase letters in this specification.
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. [Web IDL]
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
ECMA-262,
rather than the official term ECMAScript, since the term JavaScript is more widely known.
4 Navigation Timing
4.1 Introduction
This section is non-normative.
This specification defines the PerformanceNavigationTiming interface
to store and retrieve high resolution performance metric data related to the navigation of a document.
This attribute MUST return a DOMHighResTimeStamp
with a time value equal to 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 same value as fetchStart.
unloadEventStart attribute
If the previous document and the current document have the same
origin
[IETF RFC 6454],
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.
unloadEventEnd attribute
If the previous document and the current document have the
same 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.
This attribute is optional. User agents that don't have this attribute
available MUST set it as undefined. If the network interface is not immediately available and must be powered on, or cycled, before a network connection can be made, this attribute MUST return a DOMHighResTimeStamp
with a time value equal to the time immediately before starting that process. If the network interface is immediately available, this attribute MUST return the same value as navigationStart.
linkNegotiationEnd attribute
This attribute is optional. User agents that don't have this attribute
available MUST set it as undefined. If the network interface is not immediately available and must be powered on, or cycled, before a network connection can be made, this attribute MUST return a DOMHighResTimeStamp
with a time value equal to the time immediately after the network interface becomes available. If the network interface is immediately available, this attribute MUST return the same value as navigationStart.
redirectStart attribute
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.
redirectEnd attribute
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.
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 [RFC 2616] 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 attribute
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 [RFC 2616] is used or the current document
is retrieved from relevant
application caches or local resources,
this attribute MUST return the same value as fetchStart.
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 attribute
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 [RFC 2616] is used or the current document is retrieved from relevant
application caches or local resources,
this attribute MUST return value of domainLookupEnd.
connectEnd attribute
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 [RFC 2616] 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 attribute
This attribute is optional. User agents that don't have this attribute
available MUST set it as undefined. When this attribute is available, if the
scheme of the
current page is HTTPS, this
attribute MUST return a DOMHighResTimeStamp
with a time value equal to 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 attribute
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.
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 attribute
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.
responseEnd attribute
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.
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.
loadEventEnd attribute
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.
type attribute
This attribute MUST return the a DOMString describing the type of the last non-redirect navigation
in the current browsing context. It MUST have one of the following DOMString navigation type values.
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.
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.
redirectCount attribute
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.
5 Process
5.1 Processing Model
Illustration
This illustration is non-normative.
The following graph illustrates the timing attributes defined by the
PerformanceNavigationTiming interface
with or without redirect, respectively. Attributes underlined 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.
If the navigation is aborted for any of the following reasons, abort
these steps.
Record the current navigation type in type
if it has not been set:
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.
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.
If the navigation was started as a result of
history traversal,
let the navigation type be the DOMString back_forward.
If the current document and the previous document are from different
origins,
set both unloadEventStart and
unloadEventEnd to 0 then go to step
10. Otherwise, record unloadEventStart
as the time immediately before the unload event.
Immediately after the unload event is completed,
record the current time as unloadEventEnd.
If the navigation requires the network interface to be powered on or cycled, record the time immediately before doing that as linkNegotiationStart, and record the time immediately after the network interface becomes available as linkNegotiationEnd. If the network interface was immediately available, let linkNegotiationStart and linkNegotiationEnd be the same value as navigationStart.
If no domain lookup is required, go to step 16. Otherwise, immediately before a user
agent starts the domain name lookup, record the time as
domainLookupStart.
Record the time as domainLookupEnd
immediately after the domain name lookup is successfully done. A user
agent may need multiple retries before that. If the domain lookup fails,
abort the rest of the steps.
If a persistent transport connection is used to
fetch the resource, let connectStart and
connectEnd be the same value of
domainLookupEnd.
Otherwise, record the time as connectStart immediately before initiating
the connection to the server and record the time as
connectEnd immediately
after the connection to the server or the proxy is established. A user agent may
need multiple retries before this time. If a connection can not be
established, abort the rest of the steps.
In step 16, a user agent should also
carry out these additional steps if it supports the
secureConnectionStart attribute:
If the scheme of the current document is HTTPS, the user agent must
record the time as secureConnectionStart
immediately before the handshake process to secure the connection.
If the scheme of the current document is not HTTPS, the user agent must
set the value of secureConnectionStart to 0.
Immediately before a user agent starts sending
request for the document, record the current time as requestStart.
Record the time as
responseStart immediately after the user agent receives the first byte
of the response.
Record the time as responseEnd immediately after receiving the
last byte of the response.
Return to step 16 if the user agent
fails to send the request or receive the entire response, and needs to
reopen the connection.
Example
When persistent
connection [RFC 2616] 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.
If the fetched resource results in an HTTP redirect
or equivalent,
then
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. Also note that the while the graph above suggests that link negotiation happens before handling a redirect or checking the local caches, in some situations, it may happen after those steps. For example, if the current navigation results in a redirect which is present in the local cache, but the target of the redirect is not present in the local cache, the user agent may turn on the network interface after processing the redirect and just before it starts to fetch the redirect target from the network.
5.3 Vendor Prefixes
Vendor-specific proprietary user agent extensions are discouraged. If such extensions are needed,
e.g., for experimental purposes, vendors MUST use the following extension mechanisms:
If the extension to be added is an navigation type, the new type MUST
return a DOMString in the following naming convention: [vendorprefix]_[type], where [vendorprefix] is a name
that identifies the vendor.
If the extension is a new timing attribute, it MUST
follow the naming convention: [vendorprefix]TimeAttribute, where [vendorprefix] identifies
the vendor name and TimeAttribute identifies the name of the timing attribute.
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.
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.
High Resolution Time, Jatinder Mann, Editor. World Wide Web Consortium, December 2012. This version of the High Resolution Time Recommendation is available from http://www.w3.org/TR/2012/REC-hr-time-20121217/. The latest version of High Resolution Time is available at http://www.w3.org/TR/hr-time/.
Performance Timeline, Jatinder Mann, et al, Editors. World Wide Web Consortium, July 2012. This version of the Performance Timeline specification is available from http://www.w3.org/TR/2012/CR-performance-timeline-20120726/. The latest version of Performance Timeline is available at http://www.w3.org/TR/performance-timeline/.
Web IDL, Cameron McCormack, Editor. World Wide Web Consortium, April 2012. This version of the Web IDL specification is available from http://www.w3.org/TR/2012/CR-WebIDL-20120419/. The latest version of Web IDL is available at http://www.w3.org/TR/WebIDL/.
Navigation Timing, Zhiheng Wang, Editor. World Wide Web Consortium, December 2012. This edition of the Navigation Timing Recommendation is available from http://www.w3.org/TR/2012/REC-navigation-timing-20121217/. The latest version of Navigation Timing is available at http://www.w3.org/TR/navigation-timing/.
Acknowledgements
We would like to offer my sincere thanks to James Simonsen, Tony Gentilcore, Zhiheng Wang, Karen Anderson and Jason Weber for all their contributions to this work.