サーバの計時 — Server Timing

1. 序論

~web~appの処理能~特性を正確aに測定することは、 ~web~appをより速くするための重要な側面を成す。 `NAVIGATION-TIMING$r, `RESOURCE-TIMING$r は、 文書とその資源に対する要請の詳細な計時~情報を供する — それは、［ 要請が起動された時刻から，接続を折衝して応答を受信するまで ］の様々な節目を含む。 しかしながら、 ~UAは，要請の計時~dataは観測できても、 要請から応答までを巡る ある種の段階 — 例：要請はどこを経由し，~server上のどこで時間を費したか, 等々 — については，その内情 — ［ どれだけ／なぜ ］時間がかかったか — を知り得ない。 ◎ Accurately measuring performance characteristics of web applications is an important aspect of making web applications faster. [NAVIGATION-TIMING] and [RESOURCE-TIMING] provide detailed request timing information for the document and its resources, which include time when the request was initiated, and various milestones to negotiate the connection and receive the response. However, while the user agent can observe the timing data of the request it has no insight into how or why certain stages of the request-response cycle have taken as much time as they have - e.g., how the request was routed, where the time was spent on the server, and so on.

この仕様は、 次を導入する： ◎ This specification introduces＼

• `Server-Timing$h ~header【！PerformanceServerTiming interface】 — ~serverが要請から応答までを巡る処理能~計量を~UAへ通信することを可能化する。 ◎ PerformanceServerTiming interface, which enables the server to communicate performance metrics about the request-response cycle to the user agent,＼
• `PerformanceServerTiming$I ~interface — ~appが自身の送達を最適化するために，これらの計量を［ 収集して, 処理して, 動作する ］ことを可能化する。 ◎ and a JavaScript interface to enable applications to collect, process, and act on these metrics to optimize application delivery.

2. 適合性

【 この節の内容は ~W3C日本語訳 共通~page に移譲。 】

3. `Server-Timing^h ~header

`Server-Timing@h ~headerが、 要請から応答までを巡る 1 個~以上の［ 計量, 記述 ］を通信するために利用される。 この~header用の~ABNF `RFC5234$r 構文は、 次に従う： ◎ The Server-Timing header field is used to communicate one or more metrics and descriptions for the given request-response cycle. The ABNF (Augmented Backus-Naur Form) [RFC5234] syntax for the Server-Timing header field is as follows:

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

`#^P, `*^P, `OWS$P, `token$P, `quoted-string$P の定義は `RFC7230$r を見よ。 ◎ See [RFC7230] for definitions of #, *, OWS, token, and quoted-string.

応答には、 同じ `metric-name$P を伴う複数個の `server-timing-metric$P ~entryを伴わせてもヨイ。 ~UAは、 そのような~entryすべてを処理して~APIに公開するモノトスル。 ◎ A response MAY have multiple server-timing-metric entries with the same metric-name, and the user agent MUST process and expose all such entries.

~UAは、 供された各~計量をどの順序で表面化してもヨイ — すなわち，~HTTP~header内の計量どうしの順序は有意でない。 ◎ The user agent MAY surface provided metrics in any order - i.e. the order of metrics in the HTTP header field is not significant.

この~headerは、 将来の~parameterを許容するため，拡張-可能な構文で定義される。 ~UAは、 応答の `Server-Timing^h ~header内の特定0の `server-timing-param-name$P を認識しないならば、 ~errorを通達する代わりに，それらの~tokenを無視して処理を継続するモノトスル。 ◎ This header field is defined with an extensible syntax to allow for future parameters. A user agent that does not recognize particular server-timing-param-name in the Server-Timing header field of a response MUST ignore those tokens and continue processing instead of signaling an error.

多義性を避けるため、 `server-timing-metric$P の中に同じ `server-timing-param-name$P を伴う `server-timing-param$P が複数回~現れるベキでない。 そのような各 `server-timing-param$P に対しては、 最初に現れるものに限り考慮して， 残りはすべて無視するモノトスル — ［ 最初のそれが不完全, または妥当でない ］としても、 また，［ 残りのそれらに対し~errorを通達する ］ことも［ `server-timing-metric$P の処理を改める ］こともなく。 これ以外に、 `server-timing-metric$P の中の~parameterどうしの順序が有意と見なされる事例はない。 ◎ To avoid any possible ambiguity, individual server-timing-param-names SHOULD NOT appear multiple times within a server-timing-metric. If any server-timing-param-name is specified more than once, only the first instance is to be considered, even if the server-timing-param is incomplete or invalid. All subsequent occurrences MUST be ignored without signaling an error or otherwise altering the processing of the server-timing-metric. This is the only case in which the ordering of parameters within a server-timing-metric is considered to be significant.

~UAは、 `Server-Timing$P 内の どの［ `metric-name$P ／ `server-timing-param-name$P ／ `server-timing-param-value$P ］にも含まれない，余計な文字は無視するモノトスル。 ◎ User agents MUST ignore extraneous characters found after a server-timing-param-value but before the next server-timing-param and before the end of the current server-timing-metric. ◎ User agents MUST ignore extraneous characters found after a metric-name but before the first server-timing-param and before the next server-timing-metric.

4. `PerformanceServerTiming^I ~interface

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

各 `PerformanceServerTiming$I には、 次に挙げるものが結付けられる： ◎ ↓

• `計量~名@ ⇒ 文字列 — 初期~時は空~文字列とする。 ◎ A PerformanceServerTiming has an associated string metric name, initially set to the empty string.
• `~parameter群@ ⇒ `有順序~map$ — 初期~時は空とする。 ◎ A PerformanceServerTiming has an associated ordered map params, initially empty.

5. `PerformanceResourceTiming^I ~interfaceに対する拡張

この仕様は、 `PerformanceResourceTiming$I ~interface `RESOURCE-TIMING$r を部分的に拡張する。 ◎ The PerformanceResourceTiming interface, which this specification partially extends, is defined in [RESOURCE-TIMING].

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

6. ~privacyと~security

この仕様に定義した~interfaceは、 敏感になり得る［ ~app／基盤 ］情報を，~server計時~計量を広告する資源を内包する どの~web~pageにも公開する。 この理由から、 `PerformanceServerTiming$I ~interfaceへの~accessは， 既定では`同一-生成元$施策により制約される。 資源~providerは、［ `Timing-Allow-Origin$h ~HTTP応答~header `RESOURCE-TIMING$r を追加して， ~server計量への~accessが許容され得る~domainを指定する ］ことにより，［ ~server計時~情報が可用になることを明示的に許容できる ］が、 その場合でも，~UAは、 `同一-生成元$の制約を保ってもヨイ。 ◎ The interfaces defined in this specification expose potentially sensitive application and infrastructure information to any web page that has included a resource that advertises server timing metrics. For this reason the access to PerformanceServerTiming interface is restricted by the same origin policy by default. Resource providers can explicitly allow server timing information to be available by adding the Timing-Allow-Origin HTTP response header, as defined in [RESOURCE-TIMING], that specifies the domains that may be allowed to access the server metrics, but the user agent MAY keep the same origin policy restriction.

`Timing-Allow-Origin^h ~headerの利用に加えて，~serverは、 関連な~logicを利用して，どの計量を［ いつ／どこへ ］返すかを制御することもできる。 例えば、 正しく認証した利用者に限り，ある種の計量を供するなど。 ◎ In addition to using the Timing-Allow-Origin HTTP response header, the server can also use relevant logic to control which metrics are returned, when, and to whom - e.g. the server may only provide certain metrics to correctly authenticated users and nothing at all to all others.

7. ~IANA考慮点

恒久的~message~header~registryは、 次の登録により更新されるべきである `RFC3864$r ： ◎ The permanent message header field registry should be updated with the following registrations ([RFC3864]): ◎ 7.1. Server-Timing Header Field

A. 例

> 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

上の~headerは、 6 個の計量を通信している — それは、 ~serverが~UAに向けて~dataを通信するためにアリな仕方~すべてを示している： 計量~名【 `metric-name$P 】のみ, 値を伴う計量, 値と記述を伴う計量, 記述を伴う計量。 例えば，上の各~計量は、 `example.com/resource.jpg^c への~fetchに対し，次を指示しているであろう： ◎ The above header fields communicate six distinct metrics that illustrate all the possible ways for the server to communicate data to the user agent: metric name only, metric with value, metric with value and description, and metric with description. For example, the above metrics may indicate that for example.com/resource.jpg fetch:

1. ~cacheに当たらなかった（ `miss^v ）。 ◎ There was a cache miss.
2. 当の要請は `atl^l ~datacenter（ `dc^v ）を経由した。 ◎ The request was routed through the "atl" datacenter ("dc").
3. ~database（ `db^v ）にかかった~~時間は 53ms 。 ◎ The database ("db") time was 53 ms.
4. ~cacheを読取るのに 23.2ms にかかった。 ◎ A cache read took 23.2 ms.
5. ~app~server（ `app^v ） は `customView^v ~template（または関数）を処理するのに 47.2ms かかった。 ◎ The application server ("app") took 47.2ms to process "customView" template or function.
6. ~server上での要請から応答までにかかった合計~時間は 123.4ms であった。 それは、 応答の終端に記録され，`~trailer~field$を介して送達された。 ◎ The total time for the request-response cycle on the server was 123.4ms, which is recorded at the end of the response and delivered via a trailer field.

~appは、 供された~JS~interfaceを介して，供された各~計量を収集して, 処理して, 動作できる： ◎ The application can collect, process, and act on the provided metrics via the provided JavaScript interface:

/* 
`serverTiming$m を成す各~entryは、［
`navigation^l ／ `resource^l
］~entry上に住まう。
◎
serverTiming entries can live on 'navigation' and 'resource' entries
 */
for (const %entryType of ['navigation', 'resource']) {
  for (const {name: %url, %serverTiming} of `performance$m.`getEntriesByType(entryType)$m ) {
    /* 
`serverTiming^m 配列~上で反復する
◎
iterate over the serverTiming array
 */
    for (const {%name, %duration, %description} of %serverTiming) {
      /* 
“低速”なものだけ~careする
◎
we only care about "slow" ones
 */
      if (%duration > 200) {
        console.info('低速な~server計時~entry =',
          JSON.stringify({%url, %entryType, %name, %duration, %description}, null, 2))
      }
    }
  }
}

B. 利用事例

謝辞

この文書は、 次に挙げる仕様からの~textを， それらの~licenseから許可される下で再利用している ⇒＃ `NAVIGATION-TIMING$r, `RESOURCE-TIMING$r, `PERFORMANCE-TIMELINE-2$r, `RFC6797$r ◎ This document reuses text from the [NAVIGATION-TIMING], [RESOURCE-TIMING], [PERFORMANCE-TIMELINE-2], and [RFC6797] specifications as permitted by the licenses of those specifications.