Movatterモバイル変換

Resources Included in thePerformanceResourceTiming Interface

This section is non-normative.

Resource [=Request=]s [=fetch=]ed by a non-null [=request/client=] are included asPerformanceResourceTiming objects in the [=request/client=]'s [=environment settings object/global object=]'sPerformance Timeline, unless excluded from the timeline as part of the [=fetch|fetching process=]. Resources that are retrieved from HTTP cache are included asPerformanceResourceTiming objects in thePerformance Timeline. Resources for which the [=fetch=] was initiated, but was later aborted (e.g. due to a network error) are included asPerformanceResourceTiming objects in thePerformance Timeline, with their start and end timing.

Examples:

• If the same canonical URL is used as thesrc attribute of two HTMLIMG elements, the [=fetch=] of the resource initiated by the first HTMLIMG element would be included as aPerformanceResourceTiming object in thePerformance Timeline. The user agent might not re-request the URL for the second HTMLIMG element, instead using the existing download it initiated for the first HTMLIMG element. In this case, the [=fetch=] of the resource by the firstIMG element would be the only occurrence in thePerformance Timeline.
• If thesrc attribute of a HTMLIMG element is changed via script, both the [=fetch=] of the original resource as well as the [=fetch=] of the new URL would be included asPerformanceResourceTiming objects in thePerformance Timeline.
• If an HTMLIFRAME element is added via markup without specifying asrc attribute, the user agent may load theabout:blank document for theIFRAME. If at a later time thesrc attribute is changed dynamically via script, the user agent may [=fetch=] the new URL resource for theIFRAME. In this case, only the [=fetch=] of the new URL would be included as aPerformanceResourceTiming object in thePerformance Timeline.
• If anXMLHttpRequest is generated twice for the same canonical URL, both [=fetches=] of the resource would be included as aPerformanceResourceTiming object in thePerformance Timeline. This is because the [=fetch=] of the resource for the secondXMLHttpRequest cannot reuse the download issued for the firstXMLHttpRequest.
• If an HTMLIFRAME element is included on the page, then only the resource requested byIFRAMEsrc attribute is included as aPerformanceResourceTiming object in thePerformance Timeline. Sub-resources requested by theIFRAME document will be included in theIFRAME document'sPerformance Timeline and not the parent document'sPerformance Timeline.
• If an HTMLIMG element has adata: URI as its source [[RFC2397]], then this resource will not be included as a PerformanceResourceTiming object in thePerformance Timeline.PerformanceResourceTiming entries are only reported for [=http(s) scheme|http(s)=] resources.
• If a resourcefetch was aborted due to a networking error (e.g. DNS, TCP, or TLS error), then the fetch will be included as aPerformanceResourceTiming object in thePerformance Timeline with only the `startTime`, `fetchStart`, `duration` and `responseEnd` set.
• If a resourcefetch 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 aPerformanceResourceTiming object in thePerformance Timeline.

ThePerformanceResourceTiming Interface

          [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;              readonly attribute DOMString contentEncoding;              [Default] object toJSON();          };

APerformanceResourceTiming has an associated DOMStringinitiator type.

APerformanceResourceTiming has an associated DOMStringdelivery type.

APerformanceResourceTiming has an associated DOMStringrequested URL.

APerformanceResourceTiming has an associated DOMStringcache mode (the empty string, "local", or "validated").

APerformanceResourceTiming has an associated [=fetch timing info=]timing info.

APerformanceResourceTiming has an associated [=response body info=]resource info.

APerformanceResourceTiming has an associatedstatusresponse status.

APerformanceResourceTiming has an associated {{RenderBlockingStatusType}}render-blocking status.

WhentoJSON is called, run the [=default toJSON steps=] for {{PerformanceResourceTiming}}.

initiatorType getter steps are to return theinitiator type forthis.

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 thedelivery type forthis.

TheworkerStart getter steps are toconvert fetch timestamp forthis'stiming info's [=fetch timing info/final service worker start time=] and therelevant global object forthis. See [=/HTTP fetch=] for more info.

TheredirectStart getter steps are toconvert fetch timestamp forthis'stiming info's [=fetch timing info/redirect start time=] and therelevant global object forthis. See [=/HTTP-redirect fetch=] for more info.

TheredirectEnd getter steps are toconvert fetch timestamp forthis'stiming info's [=fetch timing info/redirect end time=] and therelevant global object forthis. See [=/HTTP-redirect fetch=] for more info.

ThefetchStart getter steps are toconvert fetch timestamp forthis'stiming info's [=fetch timing info/post-redirect start time=] and therelevant global object forthis. See [=/HTTP fetch=] for more info.

ThedomainLookupStart getter steps are toconvert fetch timestamp forthis'stiming info's [=fetch timing info/final connection timing info=]'s [=connection timing info/domain lookup start time=] and therelevant global object forthis. SeeRecording connection timing info for more info.

ThedomainLookupEnd getter steps are toconvert fetch timestamp forthis'stiming info's [=fetch timing info/final connection timing info=]'s [=connection timing info/domain lookup end time=] and therelevant global object forthis. SeeRecording connection timing info for more info.

TheconnectStart getter steps are toconvert fetch timestamp forthis'stiming info's [=fetch timing info/final connection timing info=]'s [=connection timing info/connection start time=] and therelevant global object forthis. SeeRecording connection timing info for more info.

TheconnectEnd getter steps are toconvert fetch timestamp forthis'stiming info's [=fetch timing info/final connection timing info=]'s [=connection timing info/connection end time=] and therelevant global object forthis. SeeRecording connection timing info for more info.

ThesecureConnectionStart getter steps are toconvert fetch timestamp forthis'stiming info's [=fetch timing info/final connection timing info=]'s [=connection timing info/secure connection start time=] and therelevant global object forthis. SeeRecording connection timing info for more info.

ThenextHopProtocol 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=]. SeeRecording connection timing info for more info.

Issue221 suggests to remove support for nextHopProtocol, as it can reveal details about the user's network configuration.

TherequestStart getter steps are toconvert fetch timestamp forthis'stiming info's [=fetch timing info/final network-request start time=] and therelevant global object forthis. See [=/HTTP fetch=] for more info.

ThefirstInterimResponseStart getter steps are toconvert fetch timestamp forthis'stiming info's [=fetch timing info/first interim network-response start time=] and therelevant global object forthis. See [=/HTTP fetch=] for more info.

ThefinalResponseHeadersStart getter steps are toconvert fetch timestamp forthis'stiming info's [=fetch timing info/final network-response start time=] and therelevant global object forthis. See [=/HTTP fetch=] for more info.

TheresponseStart getter steps are to returnthis's {{PerformanceResourceTiming/firstInterimResponseStart}} if it is not 0; Otherwisethis's {{PerformanceResourceTiming/finalResponseHeadersStart}}.

TheresponseEnd getter steps are toconvert fetch timestamp forthis'stiming info's [=fetch timing info/end time=] and therelevant global object forthis. See [=/fetch=] for more info.

TheencodedBodySize getter steps are to returnthis'sresource info's [=response body info/encoded size=].

ThedecodedBodySize getter steps are to returnthis'sresource info's [=response body info/decoded size=].

ThetransferSize getter steps are:

1. Ifthis'scache mode is "local", then return 0.

2. Ifthis'scache mode is "validated", then return 300.

3. Returnthis'sresponse 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. Seethis issue.

TheresponseStatus getter steps are to returnthis'sresponse status.

`responseStatus` is determined in [=Fetch=]. For a cross-originno-cors request it would be 0 because the response would be anopaque filtered response.

ThecontentType getter steps are to returnthis'sresource info's [=response body info/content type=].

ThecontentEncoding getter steps are to returnthis'sresource info 's [=response body info/content encoding=].

TherenderBlockingStatus getter steps are to returnblocking ifthis'stiming info's [=fetch timing info/render-blocking=] is true; otherwisenon-blocking.

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

            enum RenderBlockingStatusType {                "blocking",                "non-blocking"            };

Extensions to thePerformance Interface

The user agent MAY choose to limit how many resources are included asPerformanceResourceTiming objects in thePerformance Timeline [[PERFORMANCE-TIMELINE-2]]. This section extends thePerformance interface to allow controls over the number ofPerformanceResourceTiming objects stored.

The recommended minimum number ofPerformanceResourceTiming objects is 250, though this may be changed by the user agent.setResourceTimingBufferSize can be called to request a change to this limit.

EachECMAScript global environment has:

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

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

ThePerformance interface is defined in [[HR-TIME]].

The methodclearResourceTimings runs the following steps:

1. Remove allPerformanceResourceTiming objects in theperformance entry buffer.
2. Setresource timing buffer current size to 0.

ThesetResourceTimingBufferSize method runs the following steps:

1. Setresource timing buffer size limit to themaxSize parameter. If themaxSize parameter is less thanresource timing buffer current size, noPerformanceResourceTiming objects are to be removed from theperformance entry buffer.

The attributeonresourcetimingbufferfull is the event handler for theresourcetimingbufferfull event described below.

To check ifcan add resource timing entry, run the following steps:

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

Toadd a PerformanceResourceTiming entrynew entry into theperformance entry buffer, run the following steps:

1. Ifcan add resource timing entry returns true andresource timing buffer full event pending flag is false, run the following substeps:
   1. Addnew entry to theperformance entry buffer.
   2. Increaseresource timing buffer current size by 1.
   3. Return.
2. Ifresource timing buffer full event pending flag is false, run the following substeps:
   1. Setresource timing buffer full event pending flag to true.
   2. Queue a task on the performance timeline task source to runfire a buffer full event.
3. Addnew entry to theresource timing secondary buffer.
4. Increaseresource timing secondary buffer current size by 1.

Tocopy secondary buffer, run the following steps:

1. Whileresource timing secondary buffer is not empty andcan add resource timing entry returns true, run the following substeps:
   1. Letentry be the oldestPerformanceResourceTiming inresource timing secondary buffer.
   2. Addentry to the end ofperformance entry buffer.
   3. Incrementresource timing buffer current size by 1.
   4. Removeentry fromresource timing secondary buffer.
   5. Decrementresource timing secondary buffer current size by 1.

Tofire a buffer full event, run the following steps:

1. Whileresource timing secondary buffer is not empty, run the following substeps:
   1. Letnumber of excess entries before beresource timing secondary buffer current size.
   2. Ifcan add resource timing entry returns false, then [=fire an event=] namedresourcetimingbufferfull at the {{Performance}} object.
   3. Runcopy secondary buffer.
   4. Letnumber of excess entries after beresource timing secondary buffer current size.
   5. Ifnumber of excess entries before is lower than or equalsnumber of excess entries after, then remove all entries fromresource timing secondary buffer, setresource timing secondary buffer current size to 0, and abort these steps.
2. Setresource timing buffer full event pending flag to false.

   This means that if theresourcetimingbufferfull 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 thatresourcetimingbufferfull event handlers callclearResourceTimings or extend the buffer sufficiently (by callingsetResourceTimingBufferSize).

Cross-origin Resources

As detailed in [=Fetch=], requests for cross-origin resources are included asPerformanceResourceTiming objects in thePerformance Timeline. If thetiming 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/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 theTiming-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

Tomark resource timing given a [=/fetch timing info=] |timingInfo|, a DOMString |requestedURL|, a DOMString |initiatorType| aglobal object |global|, a string |cacheMode|, a [=/response body info=] |bodyInfo|, astatus |responseStatus|, and an optional [=string=] |deliveryType| (by default, the empty string), perform the following steps:

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

Tosetup the resource timing entry forPerformanceResourceTiming |entry| given DOMString |initiatorType|, DOMString |requestedURL|, [=/fetch timing info=] |timingInfo|, a DOMString |cacheMode|, a [=response body info=] |bodyInfo|, astatus |responseStatus|, and an optional DOMString |deliveryType| (by default, the empty string), perform the following steps:

1. Assert that |cacheMode| is the empty string, "local", or "validated".
2. Let |global| be |entry|'s [=relevant global object=].
3. [=initialize a PerformanceEntry|Initialize=] |entry| given the result ofconverting |timingInfo|'s [=fetch timing info/start time=] given |global|, "resource", |requestedURL|, and the result ofconverting |timingInfo|'s [=fetch timing info/end time=] given |global|.
4. Set |entry|'sinitiator type to |initiatorType|.
5. Set |entry|'srequested URL to |requestedURL|.
6. Set |entry|'stiming info to |timingInfo|.
7. Set |entry|'sresponse body info to |bodyInfo|.
8. Set |entry|'scache mode to |cacheMode|.
9. Set |entry|'sresponse status to |responseStatus|.
10. If |deliveryType| is the empty string and |cacheMode| is not, then set |deliveryType| to "cache".
11. Set |entry|'sdelivery type to |deliveryType|.

Toconvert fetch timestamp given {{DOMHighResTimeStamp}} |ts| andglobal 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|.

Acknowledgments

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.