Resources Included in the PerformanceResourceTiming Interface

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 relevant application caches or local resources 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:

• If the same canonical URL is used as the 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.
• If the src attribute of a HTML IMG element is changed via script, both the [=fetch=] of the original resource as well as the [=fetch=] of the new URL would be included as PerformanceResourceTiming objects in the Performance Timeline.
• If an HTML 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.
• If an 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.
• If an HTML 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.
• If an HTML 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. By definition data: URI contains embedded data and does not require a [=fetch=].
• If a resource fetch was aborted due to a networking error (e.g. DNS, TCP, or TLS error), then the fetch will be included as a PerformanceResourceTiming object in the Performance Timeline with only the `startTime`, `fetchStart`, `duration` and `responseEnd` set.
• If a resource fetch is aborted because it failed a fetch precondition (e.g. mixed content, CORS restriction, CSP policy, etc), then this resource will not be included as a PerformanceResourceTiming object in the Performance Timeline.

The PerformanceResourceTiming Interface

          [Exposed=(Window,Worker)]
          interface PerformanceResourceTiming : PerformanceEntry {
              readonly attribute DOMString initiatorType;
              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 responseStart;
              readonly attribute DOMHighResTimeStamp responseEnd;
              readonly attribute unsigned long long  transferSize;
              readonly attribute unsigned long long  encodedBodySize;
              readonly attribute unsigned long long  decodedBodySize;
              [Default] object toJSON();
          };
        

A PerformanceResourceTiming has an associated DOMString initiator 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.

The PerformanceResourceTiming interface participates in the Performance Timeline and extends the following attributes of the PerformanceEntry interface:

name

The name getter steps are to return this's requested URL.

entryType

The entryType getter steps are to return the DOMString "resource".

startTime

The startTime getter steps are to convert fetch timestamp for this's timing info's [=fetch timing info/start time=] and this's relevant global object.

`startTime` is measured right at the start of the [=fetch=], before any redirects. See fetching.

duration

The duration getter steps are to return this's timing info's [=fetch timing info/end time=] minus this's timing info's [=fetch timing info/start time=].

When toJSON is called, run [[WEBIDL]]'s default toJSON operation.

initiatorType getter steps are to return the initiator type for this.

The setting of `initiatorType` is done at the different places where a resource timing entry is reported, such as the [=fetch=] standard.

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.

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 responseStart 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 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 timing info's [=fetch timing info/encoded body size=].

The decodedBodySize getter steps are to return this's timing info's [=fetch timing info/decoded body size=].

The transferSize getter steps are to perform the following steps:

1. If this's cache mode is "local", then return 0.

2. If this's cache mode is "validated", then return 300.

3. Return this's timing info's [=fetch timing info/encoded body 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.

A user agent implementing PerformanceResourceTiming would need to include "resource" in {{PerformanceObserver/supportedEntryTypes}}. This allows developers to detect support for Resource Timing.

Extensions to the 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:

• A resource timing buffer size limit which should initially be 250 or greater.
• A resource timing buffer current size which is initially 0.
• A resource timing buffer full event pending flag which is initially false.
• A resource timing secondary buffer current size which is initially 0.
• A resource timing secondary buffer to store PerformanceResourceTiming objects that is initially empty.

partial interface Performance {
          undefined clearResourceTimings ();
          undefined setResourceTimingBufferSize (unsigned long maxSize);
          attribute EventHandler onresourcetimingbufferfull;
        };
        

The Performance interface is defined in [[HR-TIME-2]].

The method clearResourceTimings runs the following steps:

1. Remove all PerformanceResourceTiming objects in the performance entry buffer.
2. Set resource timing buffer current size to 0.

The setResourceTimingBufferSize method runs the following steps:

1. Set resource timing buffer size limit to the maxSize parameter. If the maxSize parameter is less than resource timing buffer current size, no PerformanceResourceTiming objects are to be removed from the performance entry buffer.

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:

1. If resource timing buffer current size is smaller than resource timing buffer size limit, return true.
2. Return false.

To add a PerformanceResourceTiming entry into the performance entry buffer, run the following steps:

1. Let new entry be the input PerformanceEntry to be added.
2. If can add resource timing entry returns true and resource timing buffer full event pending flag is false, run the following substeps:
   1. Add new entry to the performance entry buffer.
   2. Increase resource timing buffer current size by 1.
   3. Return.
3. If resource timing buffer full event pending flag is false, run the following substeps:
   1. Set resource timing buffer full event pending flag to true.
   2. Queue a task on the performance timeline task source to run fire a buffer full event.
4. Add new entry to the resource timing secondary buffer.
5. Increase resource timing secondary buffer current size by 1.

To copy secondary buffer, run the following steps:

1. While resource timing secondary buffer is not empty and can add resource timing entry returns true, run the following substeps:
   1. Let entry be the oldest PerformanceResourceTiming in resource timing secondary buffer.
   2. Add entry to the end of performance entry buffer.
   3. Increment resource timing buffer current size by 1.
   4. Remove entry from resource timing secondary buffer.
   5. Decrement resource timing secondary buffer current size by 1.

To fire a buffer full event, run the following steps:

1. While resource timing secondary buffer is not empty, run the following substeps:
   1. Let number of excess entries before be resource timing secondary buffer current size.
   2. If can add resource timing entry returns false, then [=fire an event=] named resourcetimingbufferfull at the {{Performance}} object.
   3. Run copy secondary buffer.
   4. Let number of excess entries after be resource timing secondary buffer current size.
   5. If number of excess entries before is lower than or equals number of excess entries after, then remove all entries from resource timing secondary buffer, set resource timing secondary buffer current size to 0, and abort these steps.
2. Set resource timing buffer full event pending flag to false.

   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).

Cross-origin Resources

As detailed in [=Fetch=], requests for cross-origin resources are included as PerformanceResourceTiming objects in the Performance Timeline. If the timing allow check algorithm fails for a cross-origin 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-origin 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/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 origin(s) specified, the values of attributes that would have been zero due to those cross-origin restrictions.

Resource Timing Attributes

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-origin resources. User agents may perform internal processing in between timings, which allow for non-normative intervals between timings.

Creating a resource timing entry

To mark resource timing given a [=/fetch timing info=] |timingInfo|, a DOMString |requestedURL|, a DOMString |initiatorType| a global object |global|, and a string |cacheMode|, perform the following steps:

1. Create a PerformanceResourceTiming object |entry| in |global|'s [=global object/realm=].
2. Setup the resource timing entry for |entry|, given |initiatorType|, |requestedURL|, |timingInfo|, and |cacheMode|.
3. Queue |entry|.
4. [=Add a PerformanceResourceTiming entry|Add=] |entry| to |global|'s performance entry buffer.

To setup the resource timing entry for PerformanceResourceTiming |entry| given DOMString |initiatorType|, DOMString |requestedURL|, [=/fetch timing info=] |timingInfo|, and a DOMString |cacheMode|, perform the following steps:

1. Assert that |cacheMode| is the empty string or "local".
2. Set |entry|'s initiator type to |initiatorType|.
3. Set |entry|'s requested URL to |requestedURL|.
4. Set |entry|'s timing info to |timingInfo|.
5. Set |entry|'s cache mode to |cacheMode|.

To convert fetch timestamp given {{DOMHighResTimeStamp}} |ts| and global object |global|, do the following:

1. If |ts| is zero, return zero.
2. Otherwise, return the [=relative high resolution coarse time=] given |ts| and |global|.