Server Timing

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key words MAY, MUST, and SHOULD NOT in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

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             = #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

See [RFC7230] for definitions of #, *, OWS, token, and quoted-string.

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.

The user agent MAY surface provided metrics in any order - i.e. the order of metrics in the HTTP header field is not significant.

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.

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.

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.

This specification establishes the server-timing-params for server-timing-param-names "dur" for duration and "desc" for description, both optional.

To parse a server-timing header field given a string field:

1. Let position be a position variable, initially pointing at the start of field.

2. Let name be the result of collecting a sequence of code points from field that are not equal to U+003B (;), given position.

3. Strip leading and trailing ASCII whitespace from name.

4. If name is an empty string, return null.

5. Let metric be a new PerformanceServerTiming whose metric name is name.

6. Let params be an empty ordered map.

7. While position is not at the end of field:

   1. Advance position by 1.

   2. Let paramName be the result of collecting a sequence of code points from field that are not equal to U+003D (=), given position.

   3. Strip leading and trailing ASCII whitespace from paramName.

   4. If paramName is an empty string or params[paramName] exists, continue.

   5. Advance position by 1.

   6. Let paramValue be an empty string.

   7. Skip ASCII whitespace within field given position.

   8. If the code point at position within field is U+0022 ("), then:

      1. Set paramValue to the result of collecting an HTTP quoted string from field given position with the extract-value flag set.

      2. Collect a sequence of code points from field that are not equal to U+003B (;), given position. The result is not used.

   9. Otherwise:

      1. Let rawParamValue be the result of collecting a sequence of code points from field that are not equal to U+003B (;), given position.

      2. Let paramValue be the result of stripping rawParamValue.

8. Set metric's params to params.

9. Return metric.

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

When toJSON is called, run [WEBIDL]'s default toJSON steps.

The PerformanceResourceTiming interface, which this specification partially extends, is defined in [RESOURCE-TIMING].

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

The permanent message header field registry should be updated with the following registrations ([RFC3864]):