服务器计时

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]。

响应 MAY（可）包含多个 metric-name 相同的 server-timing-metric 项，用户代理 MUST（必须）处理并公开所有相关项。

用户代理 MAY 可以以任何顺序呈现给定的指标——即 HTTP 头字段中指标的顺序没有实际意义。

该头字段定义为可扩展语法，以便未来增加参数。用户代理对响应 Server-Timing 头字段中无法识别的 server-timing-param-name，MUST 忽略这些标记并继续处理，不得报错。

为避免产生歧义，单独的 server-timing-param-name 在 server-timing-metric 内 SHOULD NOT（不应）出现多次。如果某个 server-timing-param-name 被指定多次，只考虑第一次出现（即使 server-timing-param 不完整或无效），后续全部 MUST 忽略，不报错也不影响 server-timing-metric 处理。仅此场景下参数顺序才有重要意义。

用户代理 MUST 忽略 server-timing-param-value 后到下一个 server-timing-param 和当前 server-timing-metric 末尾之间的多余字符。

用户代理 MUST 忽略 metric-name 后到第一个 server-timing-param 和下一个 server-timing-metric 之间的多余字符。

本规范定义 "dur"（对应 duration）和 "desc"（对应 description）参数名的 server-timing-params，均为可选项。

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

1. 令 position 为 位置变量，初始指向 field开头。

2. 令 name 为 收集一串码点的结果，条件是 field 中码点不等于 U+003B（;），以 position 为起点。

3. 去除 name 前后 ASCII 空白符。

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

5. 令 metric 为新的 PerformanceServerTiming 实例，metric name 设为 name。

6. 令 params 为空 有序 map。

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中的 ASCII 空白符，以 position 为起点。

   8. 若 position所指码点为 U+0022（"），则：

      1. paramValue 设为 收集 HTTP 引号字符串的结果（field、position，extract-value 标志打开）。

      2. 收集码点串，条件是 field 中码点不等于 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，在 此对象的 timing info 的 server-timing headers 中：

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

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

3. 返回 entries。

5. IANA 注意事项

永久消息头字段注册表应更新如下条目（[RFC3864]）：

5.1. Server-Timing 头字段

头字段名

Server-Timing

适用协议

http

状态

标准

作者/变更管控

W3C

规范文档

本规范（见 Server-Timing Header Field）

> 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 条目可存在于 'navigation' 和 'resource' 条目上
for (const entryType of ['navigation', 'resource']) {
  for (const {name: url, serverTiming} of performance.getEntriesByType(entryType)) {
    // 遍历 serverTiming 数组
    for (const {name, duration, description} of serverTiming) {
      // 这里只关心慢的项
      if (duration > 200) {
        console.info('慢的 server-timing 条目 =',
          JSON.stringify({url, entryType, name, duration, description}, null, 2))
      }
    }
  }
}