服务器计时

2. Server-Timing 头字段

Server-Timing 头字段 用于在给定的请求‑响应周期中传递一个或多个度量及其描述。[RFC5234] 中的 ABNF（增强巴克斯‑诺尔形式）语法如下：

Server-Timing             = #server-timing-metric
server-timing-metric      = metric-name *( OWS ";" OWS server-timing-param )
metric-name               = token
server-timing-param       = server-timing-param-name OWS "=" OWS server-timing-param-value
server-timing-param-name  = token
server-timing-param-value = token / quoted-string

有关 #、*、OWS、token 与 quoted-string 的定义，请参见 [RFC7230]。

响应可以包含多个拥有相同 metric-name 的 server-timing-metric 条目，用户代理 **必须** 处理并公开所有这些条目。

用户代理 **可以** 以任意顺序呈现提供的度量——即 HTTP 头字段中度量的顺序并不重要。

此头字段采用可扩展的语法，以便将来添加参数。若用户代理未识别响应中 Server-Timing 头字段的特定 server-timing-param-name，则 **必须** 忽略这些令牌并继续处理，而不是报告错误。

为避免任何可能的歧义，单个 server-timing-param-name **不应** 在同一 server-timing-metric 中出现多次。如果同一参数名出现多次，只应使用第一次出现的值，即使该 server-timing-param 不完整或无效。所有后续出现 **必须** 被忽略，且不产生错误或改变对 server-timing-metric 的处理方式。这是唯一一次参数顺序被视为重要的情况。

用户代理 **必须** 忽略位于 server-timing-param-value 之后、下一个 server-timing-param 之前以及当前 server-timing-metric 结束之前的多余字符。

用户代理 **必须** 忽略位于 metric-name 之后、首个 server-timing-param 之前以及下一个 server-timing-metric 之前的多余字符。

本规范为服务器‑计时参数定义了参数名 “dur”（对应 duration）和 “desc”（对应 description），两者均为可选。

要 解析 server-timing 头字段，给定字符串 field

1. 设 position 为一个位置变量，最初指向 field 的开头。

2. 设 name 为从 field 中收集一系列码点的结果，收集过程在遇到 U+003B (;) 前停止，起始位置为 position。

3. 去除 name 两端的 ASCII 空白字符。

4. 如果 name 为空字符串，返回 null。

5. 创建一个新的 PerformanceServerTiming 实例 metric，其度量名称为 name。

6. 设 params 为一个空的有序映射。

7. 当 position 未到达 field 末尾时

   1. 将 position 前移 1。

   2. 设 paramName 为从 field 中收集一系列码点的结果，收集过程在遇到 U+003D (=) 前停止，起始位置为 position。

   3. 去除 paramName 两端的 ASCII 空白字符。

   4. 如果 paramName 为空字符串或 params[paramName] 已存在，继续下一次循环。

   5. 将 position 前移 1。

   6. 设 paramValue 为空字符串。

   7. 跳过 field 中位于 position 的 ASCII 空白字符。

   8. 如果 position 位置的码点 为 U+0022 (")，则

      1. 将 paramValue 设为从 field 在 position 处 extract-value 标志 打开的收集 HTTP 引号字符串 的结果。

      2. 收集一系列码点，直到遇到 U+003B (;) 为止，起始位置为 position。收集结果不予使用。

   9. 否则

      1. 设 rawParamValue 为从 field 中收集、直至遇到 U+003B (;) 为止的码点序列的结果，起始位置为 position。

      2. 设 paramValue 为对 rawParamValue 进行去除空白后的结果。

8. 设置 metric 的params 为 params。

9. 返回 metric。

3. PerformanceServerTiming 接口

[Exposed=(Window,Worker)]
interface PerformanceServerTiming {
  readonly attribute DOMString name;
  readonly attribute DOMHighResTimeStamp duration;
  readonly attribute DOMString description;
  [Default] object toJSON();
};

当调用 toJSON 时，执行 [WEBIDL] 中的默认 toJSON 步骤。

3.1. name 属性

name 的 getter 步骤返回 this 的度量名称。

3.2. duration 属性

duration 的 getter 步骤如下：

1. 如果 this 的params["dur"] 不存在，返回 0。

2. 设 dur 为对 this 的params["dur"] 使用浮点数值解析规则进行解析的结果。

3. 如果 dur 为错误，返回 0；否则返回 dur。

由于 duration 是一个 DOMHighResTimeStamp，它通常表示以毫秒为单位的持续时间。由于在实践中难以强制执行此约定，duration 可以使用任意时间单位，而推荐使用毫秒作为单位。

3.3. description 属性

description 的 getter 步骤返回 this 的params["desc"]（若 存在），否则返回空字符串。

一个 PerformanceServerTiming 关联有一个字符串 度量名称，初始为空字符串。

一个 PerformanceServerTiming 关联有一个有序映射 params，初始为空。

3.4. 对 PerformanceResourceTiming 接口的扩展

PerformanceResourceTiming 接口（本规范对其作部分扩展）定义于 [RESOURCE-TIMING]。

[Exposed=(Window,Worker)]
partial interface PerformanceResourceTiming {
  readonly attribute FrozenArray<PerformanceServerTiming> serverTiming;
};

3.5. serverTiming 属性

serverTiming 的 getter 步骤如下：

1. 设 entries 为一个新的列表。

2. 遍历 field 于 this 的时序信息 的server‑timing 头部集合 中的每个 field

   1. 设 metric 为 解析 field 的结果。

   2. 如果 metric 不为 null，将其追加到 entries。

3. 返回 entries。

5. IANA 考量

应当使用以下登记（[RFC3864]）更新永久消息头字段注册表：

5.1. Server-Timing 头字段

头字段名称

Server-Timing

适用协议

http

状态

标准

作者/变更控制者

W3C

规范文档

本规范（参见 Server-Timing 头字段）

> GET /resource HTTP/1.1
> Host: example.com

< HTTP/1.1 200 OK
< Server-Timing: miss, db;dur=53, app;dur=47.2
< Server-Timing: customView, dc;desc=atl
< Server-Timing: cache;desc="Cache Read";dur=23.2
< Trailer: Server-Timing
< (... snip response body ...)
< Server-Timing: total;dur=123.4

// serverTiming entries can live on 'navigation' and 'resource' entries
for (const entryType of ['navigation', 'resource']) {
  for (const {name: url, serverTiming} of performance.getEntriesByType(entryType)) {
    // iterate over the serverTiming array
    for (const {name, duration, description} of serverTiming) {
      // we only care about "slow" ones
      if (duration > 200) {
        console.info('Slow server-timing entry =',
          JSON.stringify({url, entryType, name, duration, description}, null, 2))
      }
    }
  }
}