Server Timing

2. Conformance

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.

3. The Server-Timing Header Field

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.

4. The PerformanceServerTiming Interface

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.

5. Extension to the PerformanceResourceTiming interface

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

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

6. Process

8. IANA Considerations

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