577 | Process 578 |
579 |581 | Processing Model 582 |
583 |
594 | 98 | This specification defines an interface for web applications to access 99 | the complete timing information for navigation of a document. 100 |
101 |104 | Navigation Timing 2 replaces the first version of [[NAVIGATION-TIMING]] 105 | and includes the following changes: 106 |
107 |148 | Accurately measuring performance characteristics of web applications is 149 | an important aspect of making web applications faster. While 150 | JavaScript-based mechanisms, such as the one described in 151 | [[JSMEASURE]], can provide comprehensive instrumentation for user 152 | latency measurements within an application, in many cases, they are 153 | unable to provide a complete or detailed end-to-end latency picture. 154 | For example, the following JavaScript shows a naive attempt to measure 155 | the time it takes to fully load a page: 156 |
157 |
158 | <html>
159 | <head>
160 | <script type="text/javascript">
161 | var start = new Date().getTime();
162 | function onLoad() {
163 | var now = new Date().getTime();
164 | var latency = now - start;
165 | alert("page loading time: " + latency);
166 | }
167 | </script>
168 | </head>
169 | <body onload="onLoad()">
170 | <!- Main page body goes from here. -->
171 | </body>
172 | </html>
173 |
174 | 175 | The above script calculates the time it takes to load the page 176 | after the first bit of JavaScript in the head is executed, but 177 | it does not give any information about the time it takes to get the 178 | page from the server, or the initialization lifecycle of the page. 179 |
180 |181 | This specification defines the {{PerformanceNavigationTiming}} 182 | interface which participates in the [[PERFORMANCE-TIMELINE-2]] to store 183 | and retrieve high resolution performance metric data related to the 184 | navigation of a document. As the {{PerformanceNavigationTiming}} 185 | interface uses [[HR-TIME]], all time values are measured with respect 186 | to the [=environment settings object/time origin=] of the entry's 187 | [=relevant settings object=]. 188 |
189 |190 | For example, if we know that the response end occurs 100ms after the 191 | start of navigation, the {{PerformanceNavigationTiming}} data could 192 | look like so: 193 |
194 |195 | startTime: 0.000 // start time of the navigation request 196 | responseEnd: 100.000 // high resolution time of last received byte 197 |198 |
199 | The following script shows how a developer can use the 200 | {{PerformanceNavigationTiming}} interface to obtain accurate timing 201 | data related to the navigation of the document: 202 |
203 |
204 | <script>
205 | function showNavigationDetails() {
206 | // Get the first entry
207 | const [entry] = performance.getEntriesByType("navigation");
208 | // Show it in a nice table in the developer console
209 | console.table(entry.toJSON());
210 | }
211 | </script>
212 | <body onload="showNavigationDetails()">
213 |
214 |
220 | The construction "a Foo object", where Foo is
221 | actually an interface, is sometimes used instead of the more accurate
222 | "an object implementing the interface Foo.
223 |
225 | The term current document refers to the document associated 226 | with the Window object's newest 227 | Document object. 228 |
229 |230 | Throughout this work, all time values are measured in milliseconds 231 | since the start of navigation of the document. For example, the start 232 | of navigation of the document occurs at time 0. The term current 233 | time refers to the number of milliseconds since the start of 234 | navigation of the document until the current moment in time. This 235 | definition of time is based on [[HR-TIME]] specification. 236 |
237 |
594 | 646 | There is the potential for disclosing an end-user's browsing and 647 | activity history by using carefully crafted timing attacks. For 648 | instance, the unloading time reveals how long the previous page takes 649 | to execute its unload handler, which could be used to infer the 650 | user's login status. These attacks have been mitigated by enforcing 651 | the [=same origin=] check algorithm when unloading a document, as detailed in 652 | the HTML spec. 653 |
654 |655 | The relaxed same 657 | origin policy doesn't provide sufficient protection against 658 | unauthorized visits across documents. In shared hosting, an untrusted 659 | third party is able to host an HTTP server at the same IP address but 660 | on a different port. 661 |
662 |668 | Different pages sharing one host name, for example contents from 669 | different authors hosted on sites with user generated content are 670 | considered from the same origin because there is no feature to 671 | restrict the access by pathname. Navigating between these pages 672 | allows a latter page to access timing information of the previous 673 | one, such as timing regarding redirection and unload event. 674 |
675 |682 | The {{PerformanceNavigationTiming}} interface exposes timing 683 | information about the previous document to the current document. 684 | To limit the access to {{PerformanceNavigationTiming}} attributes which 685 | include information on the previous document, the 686 | previous document 687 | unloading algorithm enforces the same origin policy 688 | and attributes related to the previous document are set to zero. 689 |
690 |
695 | In case a proxy is deployed between the user agent and the web
696 | server, the time interval between the connectStart
698 | and the connectEnd
700 | attributes indicates the delay between the user agent and the proxy
701 | instead of the web server. With that, web server can potentially
702 | infer the existence of the proxy. For SOCKS proxy, this time interval
703 | includes the proxy authentication time and time the proxy takes to
704 | connect to the web server, which obfuscate the proxy detection. In
705 | case of an HTTP proxy, the user agent might not have any knowledge
706 | about the proxy server at all so it's not always feasible to mitigate
707 | this attack.
708 |
716 | This section defines attributes and interfaces previously introduced in 717 | [[NAVIGATION-TIMING]] Level 1 and are kept here for backwards 718 | compatibility. Authors should not use the following interfaces and are 719 | strongly advised to use the new 720 | {{PerformanceNavigationTiming}} interface—see summary 721 | of changes and improvements. 722 |
723 |
728 | [Exposed=Window]
729 | interface PerformanceTiming {
730 | readonly attribute unsigned long long navigationStart;
731 | readonly attribute unsigned long long unloadEventStart;
732 | readonly attribute unsigned long long unloadEventEnd;
733 | readonly attribute unsigned long long redirectStart;
734 | readonly attribute unsigned long long redirectEnd;
735 | readonly attribute unsigned long long fetchStart;
736 | readonly attribute unsigned long long domainLookupStart;
737 | readonly attribute unsigned long long domainLookupEnd;
738 | readonly attribute unsigned long long connectStart;
739 | readonly attribute unsigned long long connectEnd;
740 | readonly attribute unsigned long long secureConnectionStart;
741 | readonly attribute unsigned long long requestStart;
742 | readonly attribute unsigned long long responseStart;
743 | readonly attribute unsigned long long responseEnd;
744 | readonly attribute unsigned long long domLoading;
745 | readonly attribute unsigned long long domInteractive;
746 | readonly attribute unsigned long long domContentLoadedEventStart;
747 | readonly attribute unsigned long long domContentLoadedEventEnd;
748 | readonly attribute unsigned long long domComplete;
749 | readonly attribute unsigned long long loadEventStart;
750 | readonly attribute unsigned long long loadEventEnd;
751 | [Default] object toJSON();
752 | };
753 |
754 | 755 | All time values defined in this section are measured in milliseconds 756 | since midnight of . 758 |
759 |765 | This attribute must return the time immediately after the user 766 | agent finishes prompting 768 | to unload the previous document. If there is no previous 769 | document, this attribute must return the time the current 770 | document is created. 771 |
772 |773 | This attribute is not defined for 774 | {{PerformanceNavigationTiming}}. Instead, authors can use 775 | {{Performance/timeOrigin}} to obtain an equivalent timestamp. 776 |
777 |783 | If the previous document and the current document have the same 784 | origin, this attribute 785 | must return the time immediately before the user agent starts the 786 | unload event 788 | of the previous document. If there is no previous document or the 789 | previous document has a different origin than the current document, this 791 | attribute must return zero. 792 |
793 |799 | If the previous document and the current document have the same 800 | same origin, this attribute 801 | must return the time immediately after the user agent finishes 802 | the unload event 804 | of the previous document. If there is no previous document or the 805 | previous document has a different origin than the current document or the 807 | unload is not yet completed, this attribute must return zero. 808 |
809 |810 | If there are HTTP 811 | redirects when navigating and not all the redirects are from 812 | the same origin, both 813 | {{PerformanceTiming.unloadEventStart}} and 814 | {{PerformanceTiming.unloadEventEnd}} must return zero. 815 |
816 |822 | If there are HTTP 823 | redirects when navigating and if all the redirects are from 824 | the same origin, this 825 | attribute must return the starting time of the fetch 827 | that initiates the redirect. Otherwise, this attribute must 828 | return zero. 829 |
830 |836 | If there are HTTP 837 | redirects when navigating and all redirects are from the same 838 | origin, this attribute 839 | must return the time immediately after receiving the last byte of 840 | the response of the last redirect. Otherwise, this attribute must 841 | return zero. 842 |
843 |849 | If the new resource is to be fetched 851 | using a "GET" request 852 | method, fetchStart must return the time immediately before 853 | the user agent starts checking the [[RFC7234|HTTP cache]]. Otherwise, it must 854 | return the time when 855 | the user agent starts fetching the 857 | resource. 858 |
859 |865 | This attribute must return the time immediately before the user 866 | agent starts the domain name lookup for the current document. If 867 | a persistent 869 | connection [[RFC2616]] is used or the current document is 870 | retrieved from the [[RFC7234|HTTP cache]] or local resources, this attribute must 871 | return the same value as {{PerformanceTiming.fetchStart}}. 872 |
873 |879 | This attribute must return the time immediately after the user 880 | agent finishes the domain name lookup for the current document. 881 | If a persistent 883 | connection [[RFC2616]] is used or the current document is 884 | retrieved from the [[RFC7234|HTTP cache]] or local resources, this attribute must 885 | return the same value as {{PerformanceTiming.fetchStart}}. 886 |
887 |889 | Checking and retrieving contents from the 891 | HTTP cache [[RFC2616]] is part of the fetching 893 | process. It's covered by the 894 | {{PerformanceTiming.requestStart}}, 895 | {{PerformanceTiming.responseStart}} and 896 | {{PerformanceTiming.responseEnd}} attributes. 897 |
898 |900 | In case where the user agent already has the domain information 901 | in cache, domainLookupStart and domainLookupEnd represent the 902 | times when the user agent starts and ends the domain data 903 | retrieval from the cache. 904 |
905 |911 | This attribute must return the time immediately before the user 912 | agent start establishing the connection to the server to retrieve 913 | the document. If a persistent 915 | connection [[RFC2616]] is used or the current document is 916 | retrieved from the [[RFC7234|HTTP cache]] or local resources, this attribute must 917 | return value of {{PerformanceTiming.domainLookupEnd}}. 918 |
919 |925 | This attribute must return the time immediately after the user 926 | agent finishes establishing the connection to the server to 927 | retrieve the current document. If a persistent 929 | connection [[RFC2616]] is used or the current document is 930 | retrieved from the [[RFC7234|HTTP cache]] or local resources, this attribute must 931 | return the value of {{PerformanceTiming.domainLookupEnd}}. 932 |
933 |934 | If the transport connection fails and the user agent reopens a 935 | connection, {{PerformanceTiming.connectStart}} and 936 | {{PerformanceTiming.connectEnd}} should return the corresponding 937 | values of the new connection. 938 |
939 |940 | {{PerformanceTiming.connectEnd}} must include the time interval 941 | to establish the transport connection as well as other time 942 | interval such as SSL handshake and SOCKS authentication. 943 |
944 |950 | This attribute is optional. User agents that don't have this 951 | attribute available must set it as undefined. When this attribute 952 | is available, if the scheme [[URL]] of the current page 954 | is "https", this attribute must return the time immediately 955 | before the user agent starts the handshake process to secure the 956 | current connection. If this attribute is available but HTTPS is 957 | not used, this attribute must return zero. 958 |
959 |965 | This attribute must return the time immediately before the user 966 | agent starts requesting the current document from the server, or 967 | from the [[RFC7234|HTTP cache]] or from local resources. 968 |
969 |970 | If the transport connection fails after a request is sent and the 971 | user agent reopens a connection and resend the request, 972 | {{PerformanceTiming.requestStart}} should return the 973 | corresponding values of the new request. 974 |
975 |977 | This interface does not include an attribute to represent the 978 | completion of sending the request, e.g., requestEnd. 979 |
980 |998 | This attribute must return the time immediately after the user 999 | agent receives the first byte of the response from the server, or 1000 | from the [[RFC7234|HTTP cache]] or from local resources. 1001 |
1002 |1008 | This attribute must return the time immediately after the user 1009 | agent receives the last byte of the current document or 1010 | immediately before the transport connection is closed, whichever 1011 | comes first. The document here can be received either from the 1012 | server, the [[RFC7234|HTTP cache]] or from local resources. 1013 |
1014 |1020 | This attribute must return the time immediately before the user 1021 | agent sets the current document 1023 | readiness to "loading". 1025 |
1026 |
1027 | Due to differences in when a Document object is created in
1028 | existing user agents, the value returned by the
1029 | domLoading is implementation specific and should not
1030 | be used in meaningful metrics.
1031 |
1038 | This attribute must return the time immediately before the user 1039 | agent sets the current document 1041 | readiness to "interactive". 1043 |
1044 |
1050 | This attribute must return the time immediately before the user
1051 | agent fires the
1052 | DOMContentLoaded event at the Document.
1054 |
1061 | This attribute must return the time immediately after the 1062 | document's DOMContentLoaded event completes. 1064 |
1065 |1071 | This attribute must return the time immediately before the user 1072 | agent sets the current document 1074 | readiness to "complete". 1076 |
1077 |1078 | If the current document 1080 | readiness changes to the same state multiple times, 1081 | {{PerformanceTiming.domLoading}}, 1082 | {{PerformanceTiming.domInteractive}}, 1083 | {{PerformanceTiming.domContentLoadedEventStart}}, 1084 | {{PerformanceTiming.domContentLoadedEventEnd}} and 1085 | {{PerformanceTiming.domComplete}} must return the time of the 1086 | first occurrence of the corresponding document readiness 1088 | change. 1089 |
1090 |1096 | This attribute must return the time immediately before the load 1097 | event of the current document is fired. It must return zero when 1098 | the load event is not fired yet. 1099 |
1100 |1106 | This attribute must return the time when the load event of the 1107 | current document is completed. It must return zero when the load 1108 | event is not fired or is not completed. 1109 |
1110 |
1124 | [Exposed=Window]
1125 | interface PerformanceNavigation {
1126 | const unsigned short TYPE_NAVIGATE = 0;
1127 | const unsigned short TYPE_RELOAD = 1;
1128 | const unsigned short TYPE_BACK_FORWARD = 2;
1129 | const unsigned short TYPE_RESERVED = 255;
1130 | readonly attribute unsigned short type;
1131 | readonly attribute unsigned short redirectCount;
1132 | [Default] object toJSON();
1133 | };
1134 |
1135 | 1141 | Navigation where the 1142 | history handling behavior 1143 | is set to 1144 | "default" or 1145 | "replace". 1146 |
1147 |1153 | Navigation where the 1154 | history handling behavior 1155 | is set to 1156 | "reload". 1157 |
1158 |1164 | Navigation where the 1165 | history handling behavior 1166 | is set to 1167 | "entry update". 1168 |
1169 |1175 | Any navigation types not defined by values above. 1176 |
1177 |1183 | This attribute must return the type of the last non-redirect 1184 | navigation 1185 | in the current browsing context. It must have one of the 1186 | following navigation type values. 1188 |
1189 |
1190 | Client-side redirects, such as those using the Refresh
1192 | pragma directive, are not considered HTTP redirects by this spec. In those
1194 | cases, the type
1195 | attribute should return appropriate value, such as
1196 | TYPE_RELOAD if reloading the current page, or
1197 | TYPE_NAVIGATE if navigating to a new URL.
1198 |
1205 | This attribute must return the number of redirects since the last 1206 | non-redirect navigation under the current browsing context. If 1207 | there is no redirect or there is any redirect that is not from 1208 | the same origin as the 1209 | destination document, this attribute must return zero. 1210 |
1211 |Performance interface
1223 |
1225 | [Exposed=Window]
1226 | partial interface Performance {
1227 | [SameObject]
1228 | readonly attribute PerformanceTiming timing;
1229 | [SameObject]
1230 | readonly attribute PerformanceNavigation navigation;
1231 | };
1232 |
1233 | 1234 | The Performance interface is defined in 1235 | [[PERFORMANCE-TIMELINE-2]]. 1236 |
1237 |
1243 | The timing attribute represents the timing
1244 | information related to the browsing contexts since the last
1245 | non-redirect navigation. This attribute is defined by the
1246 | PerformanceTiming interface.
1247 |
1254 | The navigation attribute is defined by the
1255 | PerformanceNavigation interface.
1256 |
1267 | Thanks to Anne Van Kesteren, Arvind Jain, Boris Zbarsky, Jason Weber, 1268 | Jonas Sicking, James Simonsen, Karen Anderson, Nic Jansma, Philippe Le 1269 | Hegaret, Steve Souders, Todd Reifsteck, Tony Gentilcore, William Chan 1270 | and Zhiheng Wang for their contributions to this work. 1271 |
1272 |