This specification defines an interface for web applications to access the complete timing information for navigation of a document.
Navigation Timing 2 replaces the first version of [[NAVIGATION-TIMING]] and includes the following changes:
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 pageafter 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 [=environment settings object/time origin=] of the entry's [=relevant settings 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 "aFoo object", whereFoo is actually an interface, is sometimes used instead of the more accurate "an object implementing the interfaceFoo.
The termcurrent document refers to the document associated with theWindow 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 termcurrent 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.
{{PerformanceNavigationTiming}} interface extends the following attributes of {{PerformanceEntry}} interface:
entryType getter step is to return the {{DOMString}} "navigation". A user agent implementing {{PerformanceNavigationTiming}} would need to include"navigation" insupportedEntryTypes forWindow contexts. This allows developers to detect support for Navigation Timing.
PerformanceResourceTiming interface {{PerformanceNavigationTiming}} interface extends the following attributes of thePerformanceResourceTiming interface:
Though `redirectStart` and `redirectEnd` are exposed inPerformanceResourceTiming, they have a different meaning in Navigation Timing, where they return zero for navigations with cross-origin redirects.
Though `workerStart` is exposed inPerformanceResourceTiming, it has a different meaning in Navigation Timing, as unlike subresources, a navigation may trigger the activation or running of a service worker. In the context of Navigation Timing, `workerStart` returns the timestamp measured just before the worker has been activated or started. See [[service-workers]] for a precise definition.
When a [=service worker=] is used as part of the navigation, The `fetchStart` overload holds a different meaning than the meaning inPerformanceResourceTiming. It returns the timestamp measured right before the {{FetchEvent}} is dispatched for the [=service worker=]. The time difference between `workerStart` and `fetchStart` in the document's navigation timing entry can be used to determine roughly how long it took for the worker to be initialized or activated. See [[service-workers]] for a precise definition.
Only thecurrent document resource is included in the performance timeline; there is only one {{PerformanceNavigationTiming}} object in the performance timeline.
Each [=document=] has an associatednavigation timing entry, initially unset.
Tocreate the navigation timing entry for {{Document}} |document|, given a [=fetch timing info=] |fetchTiming|, a number |redirectCount|, a {{NavigationTimingType}} |navigationType|, a null or [=service worker timing info=] |serviceWorkerTiming|, a DOMString |cacheMode|, a {{DOMHighResTimeStamp}} |criticalCHRestart|, and a [=response body info=] |bodyInfo|, do the following:
navigation", |document|'s {{Document/URL}}, |fetchTiming|, |cacheMode|, and |bodyInfo|.Toqueue the navigation timing entry for {{Document}} |document|,queue |document|'s [=navigation timing entry=].
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 inthe HTML spec.
Therelaxed 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.
The {{PerformanceNavigationTiming}} interface exposes timing information about the previous document to thecurrent document. To limit the access to {{PerformanceNavigationTiming}} attributes which include information on the previous document, theprevious document unloading algorithm enforces thesame origin policy and attributes related to the previous document are set to zero.
In case a proxy is deployed between the user agent and the web server, the time interval between theconnectStart and theconnectEnd 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 arestrongly advised to use the new {{PerformanceNavigationTiming}} interface—seesummary of changes and improvements.
[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();};All time values defined in this section are measured in milliseconds since midnight of.
This attribute must return the time immediately after the user agent finishesprompting to unload the previous document. If there is no previous document, this attribute must return the time the current document is created.
This attribute is not defined for {{PerformanceNavigationTiming}}. Instead, authors can use {{Performance/timeOrigin}} to obtain an equivalent timestamp.
If the previous document and the current document have the sameorigin, this attribute must return the time immediately before the user agent starts theunload event of the previous document. If there is no previous document or the previous document has a differentorigin than the current document, this attribute must return zero.
If the previous document and the current document have the samesame origin, this attribute must return the time immediately after the user agent finishes theunload event of the previous document. If there is no previous document or the previous document has a differentorigin than the current document or the unload is not yet completed, this attribute must return zero.
If there areHTTP redirects when navigating and not all the redirects are from the sameorigin, both {{PerformanceTiming.unloadEventStart}} and {{PerformanceTiming.unloadEventEnd}} must return zero.
If there areHTTP redirects when navigating and if all the redirects are from the sameorigin, this attribute must return thestarting time of the fetch that initiates the redirect. Otherwise, this attribute must return zero.
If there areHTTP redirects when navigating and all redirects are from the sameorigin, 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.
If the new resource is to befetched using a "GET"request method, fetchStart must return the time immediately before the user agent starts checking the [[RFC7234|HTTP cache]]. Otherwise, it must return the time when the user agent startsfetching the resource.
This attribute must return the time immediately before the user agent starts the domain name lookup for the current document. If apersistent connection [[RFC2616]] is used or the current document is retrieved from the [[RFC7234|HTTP cache]] or local resources, this attribute must return the same value as {{PerformanceTiming.fetchStart}}.
This attribute must return the time immediately after the user agent finishes the domain name lookup for the current document. If apersistent connection [[RFC2616]] is used or the current document is retrieved from the [[RFC7234|HTTP cache]] or local resources, this attribute must return the same value as {{PerformanceTiming.fetchStart}}.
Checking and retrieving contents from the HTTP cache [[RFC2616]] is part of thefetching process. It's covered by the {{PerformanceTiming.requestStart}}, {{PerformanceTiming.responseStart}} and {{PerformanceTiming.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.
This attribute must return the time immediately before the user agent start establishing the connection to the server to retrieve the document. If apersistent connection [[RFC2616]] is used or the current document is retrieved from the [[RFC7234|HTTP cache]] or local resources, this attribute must return value of {{PerformanceTiming.domainLookupEnd}}.
This attribute must return the time immediately after the user agent finishes establishing the connection to the server to retrieve the current document. If apersistent connection [[RFC2616]] is used or the current document is retrieved from the [[RFC7234|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.
This attribute is optional. User agents that don't have this attribute available must set it as undefined. When this attribute is available, if thescheme [[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.
This attribute must return the time immediately before the user agent starts requesting the current document from the server, or from the [[RFC7234|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.
This interface does not include an attribute to represent the completion of sending the request, e.g., requestEnd.
This attribute must return the time immediately after the user agent receives the first byte of the response from the server, or from the [[RFC7234|HTTP cache]] or from local resources.
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 [[RFC7234|HTTP cache]] or from local resources.
This attribute must return the time immediately before the user agent sets thecurrent document readiness to"loading".
Due to differences in when a Document object is created in existing user agents, the value returned by thedomLoading is implementation specific and should not be used in meaningful metrics.
This attribute must return the time immediately before the user agent sets thecurrent document readiness to"interactive".
This attribute must return the time immediately before the user agent firesthe DOMContentLoaded event at theDocument.
This attribute must return the time immediately after the document'sDOMContentLoaded event completes.
This attribute must return the time immediately before the user agent sets thecurrent document readiness to"complete".
If thecurrent 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 correspondingdocument readiness change.
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.
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.
[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();};Navigation where thehistory handling behavior is set to"default" or"replace".
Navigation where thehistory handling behavior is set to"reload".
Navigation where thehistory handling behavior is set to"entry update".
Any navigation types not defined by values above.
This attribute must return the type of the last non-redirectnavigation. It must have one of the followingnavigation type values.
Client-side redirects, such as those usingthe Refresh pragma directive, are not consideredHTTP redirects by this spec. In those cases, thetype attribute should return appropriate value, such asTYPE_RELOAD if reloading the current page, orTYPE_NAVIGATE if navigating to a new URL.
This attribute must return the number of redirects since the last non-redirect navigation. If there is no redirect or there is any redirect that is not from thesame origin as the destination document, this attribute must return zero.
Performance interface [Exposed=Window] partial interface Performance { [SameObject] readonly attribute PerformanceTiming timing; [SameObject] readonly attribute PerformanceNavigation navigation; };ThePerformance interface is defined in [[PERFORMANCE-TIMELINE-2]].
Thetiming attribute represents the timing information since the last non-redirect navigation. This attribute is defined by thePerformanceTiming interface.
Thenavigation attribute is defined by thePerformanceNavigation interface.
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.