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-name s 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 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 

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-2 RESOURCE-TIMING ].

WebIDL[Exposed=(Window,Worker)]
partial interface PerformanceResourceTiming {
  readonly attribute

  readonly attribute FrozenArray<PerformanceServerTiming> serverTiming;

};

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