サーバタイミング

2. Server-Timingヘッダー・フィールド

Server-Timingヘッダーフィールド は、指定されたリクエスト応答サイクルに関する1つまたは複数の指標と説明の伝達に使われます。 [RFC5234] に基づく Server-Timingヘッダーフィールド の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

[RFC7230] の #, *, OWS, token, quoted-string の定義も参照してください。

レスポンスには同じ metric-name を持つ server-timing-metric が複数含まれる可能性があり、ユーザーエージェントは全てのエントリを処理・公開しなければなりません。

ユーザーエージェントは、提供された指標を任意の順序で表示してもよく、HTTPヘッダーフィールド内の指標順序は重要ではありません。

このヘッダーフィールドは、将来的なパラメータ追加に対応できる拡張可能な構文として定義されています。レスポンスのServer-Timingヘッダーフィールド内で特定の server-timing-param-name をユーザーエージェントが認識しない場合は、そのトークンを無視して処理を継続し、エラー通知は行いません。

曖昧さを避けるため、各 server-timing-param-name は server-timing-metric 内で複数回出現しないようにするべきです。複数回指定された場合、最初のもののみ考慮され、たとえ server-timing-param が不完全・不正でも次以降は一切無視し、エラー通知や処理変更もしません。パラメータ順序が重要となる唯一のケースです。

ユーザーエージェントは server-timing-param-value の後、次の server-timing-param や server-timing-metric の前までに現れる不要な文字を無視しなければなりません。

ユーザーエージェントは metric-name の後、初めの server-timing-param の前や次の server-timing-metric の前までに現れる不要な文字を無視しなければなりません。

本仕様は server-timing-param-name で "dur" を duration, "desc" を description として定義します。どちらもオプションです。

Server-Timingヘッダーフィールドを解析する 手順：文字列 field を受け取る。

1. position を 位置変数として field の先頭を指す。

2. name を コードポイント列収集で field から U+003B(;) でないものを position指定で取得する。

3. 先頭と末尾のASCII空白除去を name に実行。

4. name が空文字列なら null を返す。

5. metric を新しい PerformanceServerTiming として生成し、その metric name は name である。

6. params を空の 順序付きマップにする。

7. position が field の末尾でない間:

   1. position を1進める。

   2. paramName を コードポイント列収集で field から U+003D(=)でないものを position指定で取得。

   3. 先頭と末尾のASCII空白除去を paramName に実行。

   4. paramName が空文字列または params[paramName] が 存在する場合、continue。

   5. position を1進める。

   6. paramValue を空文字列にする。

   7. ASCII空白スキップを field と position で実行。

   8. position の field 内の コードポイント が U+0022(") なら：

      1. paramValue を HTTP引用文字列収集(field, position, extract-valueフラグ指定)の結果にする。

      2. コードポイント列収集で field から U+003B(;)でないものを position指定で取得。結果は使わない。

   9. それ以外の場合:

      1. rawParamValue を コードポイント列収集で field から U+003B(;)でないものを position指定で取得。

      2. paramValue を rawParamValue の先頭末尾ASCII空白除去の結果にする。

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] の default toJSON steps を実行する。

3.1. name 属性

name のゲッター手順は、this の メトリック名 を返すことです。

3.2. duration 属性

duration のゲッター手順は、次の処理を行います：

1. this の params["dur"] が 存在しない場合は、0 を返します。

2. dur を、this の params["dur"] を 浮動小数点数値の解析ルールに従って解析した結果とします。

3. dur がエラーの場合、0 を返し、そうでなければ dur を返します。

duration は DOMHighResTimeStamp なので、通常はミリ秒単位の 継続時間 を表します。 実際には強制力はありませんが、duration は任意の時間単位を表すことができ、ミリ秒単位の 継続時間 を推奨します。

3.3. description 属性

description のゲッター手順は、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 のゲッター手順は次の通りです：

1. entries を新しい リストとします。

2. 各 field を this の timing info の server-timing headers に対して：

   1. metric を サーバタイミングヘッダーフィールドの解析 の結果とします。

   2. metric が null でなければ、追加 metric を 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 のエントリは '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))
      }
    }
  }
}