资源计时

本节是非规范性的。

PerformanceResourceTiming 接口有助于对获取的 http(s) 资源进行计时测量。例如，此接口可用于 XMLHttpRequest 对象 [XHR]、HTML 元素 [HTML]（例如 iframe、 img、 script、 object、 embed 和链接类型为 stylesheet 的 link）、SVG 元素 [SVG11] （例如 svg）以及 EventSource。

本节是非规范性的。

由非 null 客户端获取的资源请求会作为 PerformanceResourceTiming 对象包含在客户端的全局对象的性能时间轴中，除非在获取过程中被排除在时间轴之外。从 HTTP 缓存中检索的资源会作为 PerformanceResourceTiming 对象包含在性能时间轴中。已启动获取但稍后中止（例如由于网络错误）的资源会作为PerformanceResourceTiming 对象包含在性能时间轴中，并带有其开始和结束计时。

示例：

如果将相同的规范 URL 用作两个 HTML IMG 元素的 src 属性，则由第一个 HTML IMG 元素启动的资源的获取将作为 PerformanceResourceTiming 对象包含在性能时间轴中。用户代理可能不会为第二个 HTML IMG 元素重新请求该 URL，而是使用它为第一个 HTML IMG 元素启动的现有下载。在这种情况下，第一个 IMG 元素对资源的获取将是性能时间轴中的唯一一次出现。
如果通过脚本更改 HTML IMG 元素的 src 属性，则原始资源的获取以及新 URL 的获取都将作为 PerformanceResourceTiming 对象包含在性能时间轴中。
如果通过标记添加 HTML IFRAME 元素而未指定 src 属性，则用户代理可能会为该 IFRAME 加载 about:blank 文档。如果稍后通过脚本动态更改 src 属性，则用户代理可能会为该 IFRAME 获取新的 URL 资源。在这种情况下，只有新 URL 的获取才会作为 PerformanceResourceTiming 对象包含在性能时间轴中。
如果为相同的规范 URL 生成两次 XMLHttpRequest，则资源的两次获取都将作为 PerformanceResourceTiming 对象包含在性能时间轴中。这是因为第二个 XMLHttpRequest 对资源的获取无法重用为第一个 XMLHttpRequest 发出的下载。
如果在页面上包含 HTML IFRAME 元素，则只有由 IFRAME src 属性请求的资源才会作为 PerformanceResourceTiming 对象包含在性能时间轴中。由 IFRAME 文档请求的子资源将包含在 IFRAME 文档的性能时间轴中，而不是父文档的性能时间轴中。
如果 HTML IMG 元素的源是 data: URI [RFC2397]，则此资源不会作为 PerformanceResourceTiming 对象包含在性能时间轴中。PerformanceResourceTiming 条目仅针对 http(s) 资源报告。
如果由于网络错误（例如 DNS、TCP 或 TLS 错误）而中止了资源获取，则该获取将作为 PerformanceResourceTiming 对象包含在性能时间轴中，并且仅设置 startTime、fetchStart、duration 和 responseEnd。
如果由于未能满足获取前提条件（例如混合内容、CORS 限制、CSP 策略等）而中止了资源获取，则此资源不会作为 PerformanceResourceTiming 对象包含在性能时间轴中。

WebIDL[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 DOMHighResTimeStamp workerRouterEvaluationStart;
    readonly attribute DOMHighResTimeStamp workerCacheLookupStart;
    readonly attribute DOMString workerMatchedRouterSource;
    readonly attribute DOMString workerFinalRouterSource;
    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();
};

一个 PerformanceResourceTiming 关联有一个 DOMString initiator type。

一个 PerformanceResourceTiming 关联有一个 DOMString delivery type。

一个 PerformanceResourceTiming 关联有一个 DOMString requested URL。

一个 PerformanceResourceTiming 关联有一个 DOMString cache mode （空字符串、“local”或 “validated”）。

一个 PerformanceResourceTiming 有一个关联的获取计时信息计时信息。

一个 PerformanceResourceTiming 有一个关联的响应体信息资源信息。

一个 PerformanceResourceTiming 具有一个关联的状态响应状态。

一个 PerformanceResourceTiming 具有一个关联的 RenderBlockingStatusType 渲染阻塞状态。

当调用 toJSON 时，为 PerformanceResourceTiming 运行默认 toJSON 步骤。

initiatorType getter 步骤是为 this 返回发起者类型。

注意

initiatorType 会返回以下值之一：

"navigation"，如果该请求是导航请求；
"body"，如果该请求是处理 body 元素的 background 属性（该属性已废弃）时产生的。
"css"，如果该请求是由于处理 CSS url() 指令（如 @import url() 或 background: url()）所产生的； [CSS-VALUES]

注：通过 CSS 中 @font-face 指定的字体资源请求，也是由处理 CSS 指令产生的。因此，该字体资源的 initiatorType 为 "css"。
"script"，如果该请求是加载任意脚本（包括经典 script、模块脚本或 Worker）时产生的。
"xmlhttprequest"，如果该请求是处理 XMLHttpRequest 时产生的；
"font"，如果该请求是处理字体时产生的。例如字体请求后续资源时产生，如使用增量字体传输时。
"fetch"，如果该请求是处理 fetch() 方法时产生的；
"beacon"，如果该请求是处理 sendBeacon() 方法时产生的；[BEACON]
"video"，如果该请求是处理 video 元素的 poster 或 src 时产生的。
"audio"，如果该请求是处理 audio 元素的 src 时产生的。
"track"，如果该请求是处理 track 元素的 src 时产生的。
"img"，如果该请求是处理 img 元素的 src 或 srcset 时产生的。
"image"，如果该请求是处理 image 元素时产生的。[SVG2]
"input"，如果该请求是处理 input 元素，且 type 属性为 image 时产生的。
"ping"，如果该请求是处理 a 元素的 ping 属性时产生的。
"iframe"，如果该请求是处理 iframe 元素的 src 时产生的。
"frame"，如果该请求是加载 frame 时产生的。
"embed"，如果该请求是处理 embed 元素的 src 时产生的。
"link"，如果该请求是处理 link 元素时产生的。
"object"，如果该请求是处理 object 元素时产生的。
"early-hints"，如果该请求是处理 Early hints 响应时产生的。
"other"，如果以上条件都不匹配。

注意

initiatorType 的设置是在报告资源计时条目的不同位置完成的，例如 fetch 标准。

deliveryType getter 步骤是为 this 返回交付类型。

注意

deliveryType 返回以下值之一：

"cache"，如果缓存模式不是空字符串。
空字符串 ""，如果不匹配上述任何条件。

预计未来的规范更新将扩展此内容，例如描述如何消费预加载资源和预取导航请求。

workerStart getter 步骤是为 this 的计时信息的最终 service worker 启动时间和 this 的相关全局对象转换获取时间戳。更多信息请参见 HTTP 获取。

redirectStart getter 步骤是为 this 的计时信息的重定向开始时间和 this 的相关全局对象转换获取时间戳。更多信息请参见 HTTP 重定向获取。

redirectEnd getter 步骤是为 this 的计时信息的重定向结束时间和 this 的相关全局对象转换获取时间戳。更多信息请参见 HTTP 重定向获取。

fetchStart getter 步骤是为 this 的计时信息的重定向后开始时间和 this 的相关全局对象转换获取时间戳。更多信息请参见 HTTP 获取。

domainLookupStart getter 步骤是为 this 的计时信息的最终连接计时信息的域名查找开始时间和 this 的相关全局对象转换获取时间戳。更多信息请参见记录连接计时信息。

domainLookupEnd getter 步骤是为 this 的计时信息的最终连接计时信息的域名查找结束时间和 this 的相关全局对象转换获取时间戳。更多信息请参见记录连接计时信息。

connectStart getter 步骤是为 this 的计时信息的最终连接计时信息的连接开始时间和 this 的相关全局对象转换获取时间戳。更多信息请参见记录连接计时信息。

connectEnd getter 步骤是为 this 的计时信息的最终连接计时信息的连接结束时间和 this 的相关全局对象转换获取时间戳。更多信息请参见记录连接计时信息。

secureConnectionStart getter 步骤是为 this 的计时信息的最终连接计时信息的安全连接开始时间和 this 的相关全局对象转换获取时间戳。更多信息请参见记录连接计时信息。

nextHopProtocol getter 步骤是同构解码 this 的计时信息的最终连接计时信息的 ALPN 协商协议。更多信息请参见记录连接计时信息。

注意

问题 221 建议移除对 nextHopProtocol 的支持，因为它可能会泄露用户网络配置的详细信息。

requestStart getter 步骤是为 this 的计时信息的最终网络请求开始时间和 this 的相关全局对象转换获取时间戳。更多信息请参见 HTTP 获取。

firstInterimResponseStart getter 步骤是为 this 的计时信息的第一个临时网络响应开始时间和 this 的相关全局对象转换获取时间戳。更多信息请参见 HTTP 获取。

finalResponseHeadersStart getter 步骤是为 this 的计时信息的最终网络响应开始时间和 this 的相关全局对象转换获取时间戳。更多信息请参见 HTTP 获取。

responseStart getter 步骤是返回 this 的 firstInterimResponseStart（如果不为 0）；否则返回 this 的 finalResponseHeadersStart。

responseEnd getter 步骤是为 this 的计时信息的结束时间和 this 的相关全局对象转换获取时间戳。更多信息请参见获取。

encodedBodySize getter 步骤是返回 this 的资源信息的编码大小。

decodedBodySize getter 步骤是返回 this 的资源信息的解码大小。

transferSize getter 的步骤是：

如果 this 的缓存模式是“local”，则返回 0。
如果 this 的缓存模式是“validated”，则返回 300。
返回 this 的响应体信息的编码大小加 300。

注意

添加到 transferSize 的常量数字取代了公开 HTTP 标头的总字节大小，因为这可能会暴露某些 cookie 的存在。请参见此问题。

responseStatus getter 步骤是返回 this 的响应状态。

注意

responseStatus 在获取中确定。对于跨域 no-cors 请求，它将为 0，因为响应将是不透明的过滤响应。

contentType getter 步骤是返回 this 的资源信息的内容类型。

contentEncoding getter 的步骤是返回此对象的资源信息的内容编码。

renderBlockingStatus getter 步骤是如果 this 的计时信息的渲染阻塞为 true，则返回 blocking；否则返回 non-blocking。

workerRouterEvaluationStart 的 getter 步骤为：返回 this 的 timing info 的 service worker timing info 的 worker router evaluation start。

workerCacheLookupStart 的 getter 步骤为：返回 this 的 timing info 的 service worker timing info 的 worker cache lookup start。

workerMatchedRouterSource 的 getter 步骤为：返回 this 的 timing info 的 service worker timing info 的 worker matched router source。

workerFinalRouterSource 的 getter 步骤为：返回 this 的 timing info 的 service worker timing info 的 worker final router source。

注意

实现 PerformanceResourceTiming 的用户代理需要在 supportedEntryTypes 中包含 "resource"。这允许开发人员检测对资源计时的支持。

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

这些值的定义如下：

blocking: 资源可能会阻止渲染。
non-blocking: 资源不会阻止渲染。

用户代理可以限制多少资源作为 PerformanceResourceTiming 对象包含在性能时间线中 [PERFORMANCE-TIMELINE-2]。此部分扩展了 Performance 接口，以允许控制存储的 PerformanceResourceTiming 对象的数量。

推荐的 PerformanceResourceTiming 对象的最小数量是 250，尽管此数量可能会由用户代理更改。可以调用 setResourceTimingBufferSize 来请求更改此限制。

每个 ECMAScript 全局环境都有：

一个资源计时缓冲区大小限制，最初应为 250 或更大。
一个资源计时缓冲区当前大小，最初为 0。
一个资源计时缓冲区已满事件挂起标志，最初为 false。
一个资源计时次要缓冲区当前大小，最初为 0。
一个资源计时次要缓冲区，用于存储最初为空的 PerformanceResourceTiming 对象。

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

Performance 接口定义在 [HR-TIME] 中。

clearResourceTimings 方法运行以下步骤：

删除 PerformanceResourceTiming 对象在性能条目缓冲区中的所有实例。
将资源计时缓冲区当前大小设置为 0。

setResourceTimingBufferSize 方法运行以下步骤：

将资源计时缓冲区大小限制设置为 maxSize 参数。如果 maxSize 参数小于资源计时缓冲区当前大小，则不从性能条目缓冲区中删除任何 PerformanceResourceTiming 对象。

onresourcetimingbufferfull 是 resourcetimingbufferfull 事件的事件处理程序，描述如下。

要检查是否可以添加资源计时条目，请执行以下步骤：

如果资源计时缓冲区当前大小小于资源计时缓冲区大小限制，则返回 true。
返回 false。

要添加 PerformanceResourceTiming 条目 new entry 到性能条目缓冲区中，请执行以下步骤：

如果是否可以添加资源计时条目返回 true 且资源计时缓冲区已满事件挂起标志为 false，请执行以下子步骤：
1. 将 new entry 添加到性能条目缓冲区。
2. 将资源计时缓冲区当前大小增加 1。
3. 返回。
如果资源计时缓冲区已满事件挂起标志为 false，请执行以下子步骤：
1. 将资源计时缓冲区已满事件挂起标志设置为 true。
2. 排队任务到性能时间线任务源，运行触发缓冲区已满事件。
将 new entry 添加到资源计时次要缓冲区中。
将资源计时次要缓冲区当前大小增加 1。

要复制次要缓冲区，请执行以下步骤：

当资源计时次要缓冲区非空时，并且是否可以添加资源计时条目返回 true，请运行以下子步骤：
1. 将 entry 设置为最旧的 PerformanceResourceTiming 在资源计时次要缓冲区中。
2. 将 entry 添加到性能条目缓冲区的末尾。
3. 将资源计时缓冲区当前大小增加 1。
4. 将 entry 从资源计时次要缓冲区中移除。
5. 将资源计时次要缓冲区当前大小减少 1。

要触发缓冲区已满事件，请执行以下步骤：

当资源计时次要缓冲区非空时，请运行以下子步骤：
1. 将 number of excess entries before 设置为资源计时次要缓冲区当前大小。
2. 如果可以添加资源计时条目返回 false，则在 Performance 对象上触发一个名为 resourcetimingbufferfull 的事件。
3. 运行复制次要缓冲区。
4. 将 number of excess entries after 设置为资源计时次要缓冲区当前大小。
5. 如果 number of excess entries before 小于等于 number of excess entries after，则从资源计时次要缓冲区中移除所有条目，将资源计时次要缓冲区当前大小设置为 0，并中止这些步骤。
将资源计时缓冲区已满事件挂起标志设置为 false。

注

这意味着，如果 resourcetimingbufferfull 事件处理程序没有比它向缓冲区添加的资源腾出更多空间，则多余的条目将从缓冲区中丢弃。开发者应该确保 resourcetimingbufferfull 事件处理程序调用 clearResourceTimings 或足够扩展缓冲区（通过调用 setResourceTimingBufferSize）。

本节为非规范性内容。

如同在 Fetch 中详细说明的那样，对跨源资源的请求会作为 PerformanceResourceTiming 对象包含在性能时间线中。

如果针对跨源资源的计时允许检查算法失败，则该条目将是一个不透明条目。此类条目会屏蔽其大部分属性，以防止泄露原本未暴露的跨源数据。因此，对于一个不透明条目，下列属性将始终返回 0 或空字符串： redirectStart, redirectEnd, workerStart, domainLookupStart, domainLookupEnd, connectStart, connectEnd, requestStart, firstInterimResponseStart, finalResponseHeadersStart, responseStart, secureConnectionStart, 以及 nextHopProtocol。

某些属性，例如 contentType、 encodedBodySize、以及 decodedBodySize 在响应为 CORS-cross-origin 时会被设为 0 （对 contentType 而言则为空字符串）。 transferSize 同时会受到计时允许检查与 CORS-cross-origin 状态的影响。

对于由服务工作线程使用 respondWith() 处理的请求，所报告的计时数据反映的是客户端与服务工作线程之间的交互，而不是服务工作线程自身内部的网络活动。例如，服务工作线程可能会对同源请求返回跨源响应，反之亦然，或者对任一情况返回缓存的或合成的响应。鉴于此，由服务工作线程转发的资源并不能完整反映获取该资源的全过程，并且不会经过计时允许检查。要获取关于这些 fetch 的完整信息，可以检查服务工作线程自身的性能时间线。[SERVICE-WORKERS]

更多细节请参见 HTTP Fetch #4 —— 仅当服务工作线程没有返回响应时，才会执行计时允许检查。此外，在 respondWith() 算法中克隆的响应不会携带内部 fetch 的 fetch 计时信息，因为该信息是附着在一次 fetch 上，而不是附着在一个响应上。

服务器端应用可以返回 Timing-Allow-Origin HTTP 响应标头，以允许用户代理将原本会因跨源限制而为零的属性值，对所指定的文档源（origin）完整暴露出来。

Timing-Allow-Origin HTTP 响应标头字段可用于传达一项策略，指示哪些源（origin）可以被允许查看那些因跨源限制而本应为零的属性值。该标头的值由下列 ABNF [RFC5234] 表示（使用列表扩展，[RFC9110）：

Timing-Allow-Origin = 1#( origin-or-null / wildcard )

发送方 MAY 生成多个 Timing-Allow-Origin 标头字段。接收方 MAY 通过将每个后续字段值按顺序附加到合并后的字段值末尾来合并多个 Timing-Allow-Origin 标头字段，并以逗号分隔。

即使存在 Timing-Allow-Origin HTTP 响应标头字段，用户代理仍 MAY 执行跨源限制，并将 transferSize、encodedBodySize 和 decodedBodySize 属性设为 0。若如此，它也 MAY 将 deliveryType 设为 ""。

Timing-Allow-Origin 标头会在 FETCH 中被处理，以便相应计算这些属性。

注

Timing-Allow-Origin 标头可能作为缓存响应的一部分到达。在缓存重新验证的情况下，根据 RFC 7234，该标头的值可能来自重新验证响应；若其中不存在，则来自原始缓存资源。

注

议题 222 与 223 建议从 Timing-Allow-Origin 中移除通配符支持，以限制其使用。

本节将 Timing-Allow-Origin 注册为一个临时消息标头。

标头字段名称：

Timing-Allow-Origin

适用协议：

http

状态：

临时

作者/变更控制者：

W3C

规范文档：

4.6 Timing-Allow-Origin 响应标头

资源计时

摘要

本文档状态

1. 引言

2. 一致性

3. 术语

4. 资源计时

4.1 引言

4.2 `PerformanceResourceTiming` 接口中包含的资源

4.3 `PerformanceResourceTiming` 接口

4.3.1 `RenderBlockingStatusType` 枚举

4.4 `Performance` 接口的扩展

4.5 跨源资源

4.5.1 引言

4.6 `Timing-Allow-Origin` 响应标头

4.7 IANA 注意事项

5. 资源计时属性

6. 创建资源计时条目

7. 安全注意事项

8. 隐私注意事项

A. 致谢

B. 参考文献

B.1 规范性参考文献

B.2 信息性参考文献

资源计时

摘要

本文档状态

1. 引言

2. 一致性

3. 术语

4. 资源计时

4.1 引言

4.2 PerformanceResourceTiming 接口中包含的资源

4.3 PerformanceResourceTiming 接口

4.3.1 RenderBlockingStatusType 枚举

4.4 Performance 接口的扩展

4.5 跨源资源

4.5.1 引言

4.6 Timing-Allow-Origin 响应标头

4.7 IANA 注意事项

5. 资源计时属性

6. 创建资源计时条目

7. 安全注意事项

8. 隐私注意事项

A. 致谢

B. 参考文献

B.1 规范性参考文献

B.2 信息性参考文献

4.2 `PerformanceResourceTiming` 接口中包含的资源

4.3 `PerformanceResourceTiming` 接口

4.3.1 `RenderBlockingStatusType` 枚举

4.4 `Performance` 接口的扩展

4.6 `Timing-Allow-Origin` 响应标头