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-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.

4. The PerformanceServerTiming Interface

[Exposed=*]
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 ) ]

[Exposed=*]

partial
interface
PerformanceResourceTiming
{
readonly
attribute
FrozenArray
<
PerformanceServerTiming
>
serverTiming
;

FrozenArray<PerformanceServerTiming>
serverTiming;

};

6. Process

8. IANA Considerations

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