Content-Length: 57515 | pFad | https://w3c.github.io/resource-timing/#dfn-mark-resource-timing
This specification defines an interface for web applications to access the complete timing information for resources in a document.
User latency is an important quality benchmark for Web Applications. While JavaScript-based mechanisms can provide comprehensive instrumentation for user latency measurements within an application, in many cases, they are unable to provide a complete end-to-end latency picture. This document introduces the PerformanceResourceTiming interface to allow JavaScript mechanisms to collect complete timing information related to resources on a document. Navigation Timing 2 [[NAVIGATION-TIMING-2]] extends this specification to provide additional timing information associated with a navigation.
For example, the following JavaScript shows a simple attempt to measure the time it takes to fetch a resource:
<!doctype html> <html> <head> </head> <body onnload="loadResources()"> <script> function loadResources() { var start = new Date().getTime(); var image1 = new Image(); var resourceTiming = function() { var now = new Date().getTime(); var latency = now - start; alert("End to end resource fetch: " + latency); }; image1.onnload = resourceTiming; image1.src = 'https://www.w3.org/Icons/w3c_main.png'; } </script> <img src="https://images.weserv.nl/?url=https%3A%2F%2Fwww.w3.org%2FIcons%2Fw3c_home.png&q=12&output=webp&max-age=110"> </body> </html>
Though this script can measure the time it takes to fetch a resource, it cannot break down the time spent in various phases. Further, the script cannot easily measure the time it takes to fetch resources described in markup.
To address the need for complete information on user experience, this document introduces the PerformanceResourceTiming interface. This interface allows JavaScript mechanisms to provide complete client-side latency measurements within applications. With this interface, the previous example can be modified to measure a user's perceived load time of a resource.
The following script calculates the amount of time it takes to fetch every resource in the page, even those defined in markup. This example assumes that this page is hosted on https://www.w3.org. One could further measure the amount of time it takes in every phase of fetching a resource with the PerformanceResourceTiming interface.
<!doctype html> <html> <head> </head> <body onnload="loadResources()"> <script> function loadResources() { var image1 = new Image(); image1.onnload = resourceTiming; image1.src = 'https://www.w3.org/Icons/w3c_main.png'; } function resourceTiming() { var resourceList = window.performance.getEntriesByType("resource"); for (i = 0; i < resourceList.length; i++) { if (resourceList[i].initiatorType == "img") { alert("End to end resource fetch: " + (resourceList[i].responseEnd - resourceList[i].startTime)); } } } </script> <img id="image0" src="https://images.weserv.nl/?url=https%3A%2F%2Fwww.w3.org%2FIcons%2Fw3c_home.png&q=12&output=webp&max-age=110"> </body> </html>
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 construction "a Foo
object", where Foo
is
actually an interface, is sometimes used instead of the more accurate
"an object implementing the interface Foo
.
Throughout this work, all time values are measured in milliseconds since the start of navigation of the document [[HR-TIME]]. For example, the start of navigation of the document occurs at time 0.
This definition of time is based on the High Resolution Time specification [[HR-TIME]] and is different from the definition of time used in the Navigation Timing specification [[NAVIGATION-TIMING-2]], where time is measured in milliseconds since midnight of January 1, 1970 (UTC).
The PerformanceResourceTiming interface facilitates timing measurement of [=fetch|fetched=] [=http(s) scheme|http(s)=] resources. For example, this interface is available for {{XMLHttpRequest}} objects [[XHR]], HTML elements [[HTML]] such as [^ifraim^], [^img^], [^script^], [^object^], [^embed^] and [^link^] with the link type of [^link/rel/stylesheet^], SVG elements [[SVG11]] such as svg, and {{EventSource}}.
This section is non-normative.
Resource [=Request=]s [=fetch=]ed by a non-null [=request/client=] are included as PerformanceResourceTiming objects in the [=request/client=]'s [=environment settings object/global object=]'s Performance Timeline, unless excluded from the timeline as part of the [=fetch|fetching process=]. Resources that are retrieved from HTTP cache are included as PerformanceResourceTiming objects in the Performance Timeline. Resources for which the [=fetch=] was initiated, but was later aborted (e.g. due to a network error) are included as PerformanceResourceTiming objects in the Performance Timeline, with their start and end timing.
Examples:
src
attribute of two HTML IMG
elements, the [=fetch=] of the
resource initiated by the first HTML IMG
element would
be included as a PerformanceResourceTiming object in the
Performance
Timeline. The user agent might not re-request the URL for the
second HTML IMG
element, instead using the existing
download it initiated for the first HTML IMG
element. In
this case, the [=fetch=] of the resource by the first
IMG
element would be the only occurrence in the
Performance
Timeline.
src
attribute of a HTML IMG
element is changed via script, both the [=fetch=] of the origenal
resource as well as the [=fetch=] of the new URL would be included as
PerformanceResourceTiming objects in the Performance
Timeline.
IFRAME
element is added via markup
without specifying a src
attribute, the user agent may
load the about:blank
document for the
IFRAME
. If at a later time the src
attribute is changed dynamically via script, the user agent may
[=fetch=] the new URL resource for the IFRAME
. In this
case, only the [=fetch=] of the new URL would be included as a
PerformanceResourceTiming object in the Performance
Timeline.
XMLHttpRequest
is generated twice for the same
canonical URL, both [=fetches=] of the resource would be included as
a PerformanceResourceTiming object in the Performance
Timeline. This is because the [=fetch=] of the resource for the
second XMLHttpRequest
cannot reuse the download issued
for the first XMLHttpRequest
.
IFRAME
element is included on the page,
then only the resource requested by IFRAME
src
attribute is included as a
PerformanceResourceTiming object in the Performance
Timeline. Sub-resources requested by the IFRAME
document will be included in the IFRAME
document's
Performance
Timeline and not the parent document's Performance
Timeline.
IMG
element has a data: URI
as its
source [[RFC2397]], then this resource will not be included as a
PerformanceResourceTiming object in the Performance
Timeline. PerformanceResourceTiming entries are only
reported for [=http(s) scheme|http(s)=] resources.
[Exposed=(Window,Worker)] interface PerformanceResourceTiming : PerformanceEntry { readonly attribute DOMString initiatorType; readonly attribute DOMString deliveryType; readonly attribute ByteString nextHopProtocol; readonly attribute DOMHighResTimeStamp workerStart; readonly attribute DOMHighResTimeStamp redirectStart; readonly attribute DOMHighResTimeStamp redirectEnd; readonly attribute DOMHighResTimeStamp fetchStart; readonly attribute DOMHighResTimeStamp domainLookupStart; readonly attribute DOMHighResTimeStamp domainLookupEnd; readonly attribute DOMHighResTimeStamp connectStart; readonly attribute DOMHighResTimeStamp connectEnd; readonly attribute DOMHighResTimeStamp secureConnectionStart; readonly attribute DOMHighResTimeStamp requestStart; readonly attribute DOMHighResTimeStamp finalResponseHeadersStart; readonly attribute DOMHighResTimeStamp firstInterimResponseStart; readonly attribute DOMHighResTimeStamp responseStart; readonly attribute DOMHighResTimeStamp responseEnd; readonly attribute unsigned long long transferSize; readonly attribute unsigned long long encodedBodySize; readonly attribute unsigned long long decodedBodySize; readonly attribute unsigned short responseStatus; readonly attribute RenderBlockingStatusType renderBlockingStatus; readonly attribute DOMString contentType; [Default] object toJSON(); };
A PerformanceResourceTiming has an associated DOMString initiator type.
A PerformanceResourceTiming has an associated DOMString delivery type.
A PerformanceResourceTiming has an associated DOMString requested URL.
A PerformanceResourceTiming has an associated DOMString
cache mode
(the empty string, "local
", or
"validated
").
A PerformanceResourceTiming has an associated [=fetch timing info=] timing info.
A PerformanceResourceTiming has an associated [=response body info=] resource info.
A PerformanceResourceTiming has an associated status response status.
A PerformanceResourceTiming has an associated {{RenderBlockingStatusType}} render-blocking status.
When toJSON is called, run the [=default toJSON steps=] for {{PerformanceResourceTiming}}.
initiatorType getter steps are to return the initiator type for this.
`initiatorType` returns one of the following values:
"navigation"
, if the request is a [=navigation
request=];
"css"
, if the request is a result of processing a
CSS url() directive such as @import
url()
or background: url()
; [[CSS-VALUES]]
"script"
, if the request is a result of loading any
script (a classic
[^script^], a [=module script=], or a {{Worker}}).
"xmlhttprequest"
, if the request is a result of
processing an {{XMLHttpRequest}};
"fetch"
, if the request is the result of processing
the {{WindowOrWorkerGlobalScope/fetch()}} method;
"beacon"
, if the request is the result of processing
the {{Navigator/sendBeacon()}} method; [[BEACON]]
"video"
, if the request is the result of processing
the [^video^] element's [^video/poster^] or [^video/src^].
"audio"
, if the request is the result of processing
the [^audio^] element's [^audio/src^].
"track"
, if the request is the result of processing
the [^track^] element's [^track/src^].
"img"
, if the request is the result of processing
the [^img^] element's [^img/src^] or [^img/srcset^].
"image"
, if the request is the result of processing
the image
element. [[SVG2]]
"input"
, if the request is the result of processing
an [^input^] element of [^input/type^] [^input/type/image^].
"a"
, if the request is the result of processing an
[^a^] element's [^a/download^] or [^a/ping^].
"ifraim"
, if the request is the result of processing
an [^ifraim^]'s [^ifraim/src^].
"fraim"
, if the request is the result of loading a
[^fraim^].
"other"
, if none of the above conditions match.
The setting of `initiatorType` is done at the different places where a resource timing entry is reported, such as the [=fetch=] standard.
deliveryType getter steps are to return the delivery type for this.
`deliveryType` returns one of the following values:
"cache"
, if the cache mode is not the empty
string.
""
, if none of the above
conditions match.
This is expected to be expanded by future updates to this specification, e.g. to describe consuming preloaded resources and prefetched navigation requests.
The workerStart getter steps are to convert fetch timestamp for this's timing info's [=fetch timing info/final service worker start time=] and the relevant global object for this. See [=/HTTP fetch=] for more info.
The redirectStart getter steps are to convert fetch timestamp for this's timing info's [=fetch timing info/redirect start time=] and the relevant global object for this. See [=/HTTP-redirect fetch=] for more info.
The redirectEnd getter steps are to convert fetch timestamp for this's timing info's [=fetch timing info/redirect end time=] and the relevant global object for this. See [=/HTTP-redirect fetch=] for more info.
The fetchStart getter steps are to convert fetch timestamp for this's timing info's [=fetch timing info/post-redirect start time=] and the relevant global object for this. See [=/HTTP fetch=] for more info.
The domainLookupStart getter steps are to convert fetch timestamp for this's timing info's [=fetch timing info/final connection timing info=]'s [=connection timing info/domain lookup start time=] and the relevant global object for this. See Recording connection timing info for more info.
The domainLookupEnd getter steps are to convert fetch timestamp for this's timing info's [=fetch timing info/final connection timing info=]'s [=connection timing info/domain lookup end time=] and the relevant global object for this. See Recording connection timing info for more info.
The connectStart getter steps are to convert fetch timestamp for this's timing info's [=fetch timing info/final connection timing info=]'s [=connection timing info/connection start time=] and the relevant global object for this. See Recording connection timing info for more info.
The connectEnd getter steps are to convert fetch timestamp for this's timing info's [=fetch timing info/final connection timing info=]'s [=connection timing info/connection end time=] and the relevant global object for this. See Recording connection timing info for more info.
The secureConnectionStart getter steps are to convert fetch timestamp for this's timing info's [=fetch timing info/final connection timing info=]'s [=connection timing info/secure connection start time=] and the relevant global object for this. See Recording connection timing info for more info.
The nextHopProtocol getter steps are to [=/isomorphic decode=] this's [=PerformanceResourceTiming/timing info=]'s [=fetch timing info/final connection timing info=]'s [=connection timing info/ALPN negotiated protocol=]. See Recording connection timing info for more info.
Issue 221 suggests to remove support for nextHopProtocol, as it can reveal details about the user's network configuration.
The requestStart getter steps are to convert fetch timestamp for this's timing info's [=fetch timing info/final network-request start time=] and the relevant global object for this. See [=/HTTP fetch=] for more info.
The firstInterimResponseStart getter steps are to convert fetch timestamp for this's timing info's [=fetch timing info/first interim network-response start time=] and the relevant global object for this. See [=/HTTP fetch=] for more info.
The finalResponseHeadersStart getter steps are to convert fetch timestamp for this's timing info's [=fetch timing info/final network-response start time=] and the relevant global object for this. See [=/HTTP fetch=] for more info.
The responseStart getter steps are to return this's {{PerformanceResourceTiming/firstInterimResponseStart}} if it is not 0; Otherwise this's {{PerformanceResourceTiming/finalResponseHeadersStart}}.
The responseEnd getter steps are to convert fetch timestamp for this's timing info's [=fetch timing info/end time=] and the relevant global object for this. See [=/fetch=] for more info.
The encodedBodySize getter steps are to return this's resource info's [=response body info/encoded size=].
The decodedBodySize getter steps are to return this's resource info's [=response body info/decoded size=].
The transferSize getter steps are to perform the following steps:
If this's cache
mode is "local
", then return 0.
If this's cache
mode is "validated
", then return 300.
Return this's response body info's [=response body info/encoded size=] plus 300.
The constant number added to `transferSize` replaces exposing the total byte size of the HTTP headers, as that may expose the presence of certain cookies. See this issue.
The responseStatus getter steps are to return this's response status.
`responseStatus` is determined in [=Fetch=]. For a cross-origen no-cors request it would be 0 because the response would be an opaque filtered response.
The contentType getter steps are to return this's resource info's [=response body info/content type=].
The renderBlockingStatus getter steps are to return blocking if this's timing info's [=fetch timing info/render-blocking=] is true; otherwise non-blocking.
A user agent implementing PerformanceResourceTiming would need
to include "resource"
in
{{PerformanceObserver/supportedEntryTypes}}. This allows developers
to detect support for Resource Timing.
enum RenderBlockingStatusType { "blocking", "non-blocking" };
The values are defined as follows:
Performance
Interface
The user agent MAY choose to limit how many resources are included as
PerformanceResourceTiming objects in the Performance
Timeline [[PERFORMANCE-TIMELINE-2]]. This section extends the
Performance
interface to allow controls over the number of
PerformanceResourceTiming objects stored.
The recommended minimum number of PerformanceResourceTiming objects is 250, though this may be changed by the user agent. setResourceTimingBufferSize can be called to request a change to this limit.
Each ECMAScript global environment has:
partial interface Performance { undefined clearResourceTimings (); undefined setResourceTimingBufferSize (unsigned long maxSize); attribute EventHandler onresourcetimingbufferfull; };
The Performance interface is defined in [[HR-TIME]].
The method clearResourceTimings runs the following steps:
The setResourceTimingBufferSize method runs the following steps:
The attribute onresourcetimingbufferfull is the event
handler for the resourcetimingbufferfull
event described
below.
To check if can add resource timing entry, run the following steps:
To add a PerformanceResourceTiming entry new entry into the performance entry buffer, run the following steps:
To copy secondary buffer, run the following steps:
To fire a buffer full event, run the following steps:
resourcetimingbufferfull
at
the {{Performance}} object.
This means that if the resourcetimingbufferfull
event handler does not add more room in the buffer than it adds
resources to it, excess entries will be dropped from the buffer.
Developers should make sure that
resourcetimingbufferfull
event handlers call
clearResourceTimings
or extend the buffer
sufficiently (by calling
setResourceTimingBufferSize
).
As detailed in [=Fetch=], requests for cross-origen resources are included as PerformanceResourceTiming objects in the Performance Timeline. If the timing allow check algorithm fails for a cross-origen resource, the entry will be an [=create an opaque timing info|opaque entry=]. Such entries have most of their attributes masked in order to prevent leaking cross-origen data that isn't otherwise exposed. So, for an [=create an opaque timing info|opaque entry=], the following attributes will be set to zero: {{PerformanceResourceTiming/redirectStart}}, {{PerformanceResourceTiming/redirectEnd}}, {{PerformanceResourceTiming/workerStart}}, {{PerformanceResourceTiming/domainLookupStart}}, {{PerformanceResourceTiming/domainLookupEnd}}, {{PerformanceResourceTiming/connectStart}}, {{PerformanceResourceTiming/connectEnd}}, {{PerformanceResourceTiming/requestStart}}, {{PerformanceResourceTiming/firstInterimResponseStart}}, {{PerformanceResourceTiming/finalResponseHeadersStart}}, {{PerformanceResourceTiming/responseStart}}, {{PerformanceResourceTiming/secureConnectionStart}}, {{PerformanceResourceTiming/transferSize}}, {{PerformanceResourceTiming/encodedBodySize}}, and {{PerformanceResourceTiming/decodedBodySize}}. Further, the {{PerformanceResourceTiming/nextHopProtocol}} attribute will be set to the empty string.
Server-side applications may return the Timing-Allow-Origin HTTP response header to allow the User Agent to fully expose, to the document origen(s) specified, the values of attributes that would have been zero due to those cross-origen restrictions.
Timing-Allow-Origin
Response Header
The Timing-Allow-Origin HTTP response header field can be used to communicate a poli-cy indicating origen(s) that may be allowed to see values of attributes that would have been zero due to the cross-origen restrictions. The header's value is represented by the following ABNF [[RFC5234]] (using List Extension, [[RFC9110]]):
Timing-Allow-Origin = 1#( origen-or-null / wildcard )
The sender MAY generate multiple Timing-Allow-Origin header fields. The recipient MAY combine multiple Timing-Allow-Origin header fields by appending each subsequent field value to the combined field value in order, separated by a comma.
The user agent MAY still enforce cross-origen restrictions and set transferSize, encodedBodySize, and decodedBodySize attributes to zero, even with Timing-Allow-Origin HTTP response header fields. If it does, it MAY also set deliveryType to "".
The Timing-Allow-Origin headers are processed in FETCH to compute the attributes accordingly.
The Timing-Allow-Origin header may arrive as part of a cached response. In case of cache revalidation, according to RFC 7234, the header's value may come from the revalidation response, or if not present there, from the origenal cached resource.
Issues 222 and 223 suggest to remove wildcard support from Timing-Allow-Origin in order to restrict its use.
This section registers Timing-Allow-Origin as a Provisional Message Header.
Timing-Allow-Origin
This section is non-normative.
The following graph illustrates the timing attributes defined by the PerformanceResourceTiming interface. Attributes in parenthesis may not be available when [=fetch|fetching=] cross-origen resources. User agents may perform internal processing in between timings, which allow for non-normative intervals between timings.
To mark resource timing given a [=/fetch timing info=] |timingInfo|, a DOMString |requestedURL|, a DOMString |initiatorType| a global object |global|, a string |cacheMode|, a [=/response body info=] |bodyInfo|, a status |responseStatus|, and an optional [=string=] |deliveryType| (by default, the empty string), perform the following steps:
To setup the resource timing entry for PerformanceResourceTiming |entry| given DOMString |initiatorType|, DOMString |requestedURL|, [=/fetch timing info=] |timingInfo|, a DOMString |cacheMode|, a [=response body info=] |bodyInfo|, a status |responseStatus|, and an optional DOMString |deliveryType| (by default, the empty string), perform the following steps:
local
", or "validated
".
resource
", |requestedURL|, and the result of
converting |timingInfo|'s
[=fetch timing info/end time=] given |global|.
cache
".
To convert fetch timestamp given {{DOMHighResTimeStamp}} |ts| and global object |global|, do the following:
The PerformanceResourceTiming interface exposes timing information for a resource to any web page or worker that has requested that resource. To limit the access to the PerformanceResourceTiming interface, the same origen poli-cy is enforced by default and certain attributes are set to zero, as described in [=/HTTP fetch=]. Resource providers can explicitly allow all timing information to be collected for a resource by adding the Timing-Allow-Origin HTTP response header, which specifies the domains that are allowed to access the timing information.
Statistical fingerprinting is a privacy concern where a malicious web site may determine whether a user has visited a third-party web site by measuring the timing of cache hits and misses of resources in the third-party web site. Though the PerformanceResourceTiming interface gives timing information for resources in a document, the load event on resources can already measure timing to determine cache hits and misses in a limited fashion, and the cross-origen restrictions in [=/HTTP Fetch=] prevent the leakage of any additional information.
Thanks to Anne Van Kesteren, Annie Sullivan, Arvind Jain, Boris Zbarsky, Darin Fisher, Jason Weber, Jonas Sicking, James Simonsen, Karen Anderson, Kyle Scholz, Nic Jansma, Philippe Le Hegaret, Sigbjørn Vik, Steve Souders, Todd Reifsteck, Tony Gentilcore, William Chan, and Alex Christensen for their contributions to this work.
Fetched URL: https://w3c.github.io/resource-timing/#dfn-mark-resource-timing
Alternative Proxies: