This specification enables a server to communicate performance metrics about the request-response cycle to the user agent. It also standardizes a JavaScript interface to enable applications to collect, process, and act on these metrics to optimize application delivery.
### 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:
```ABNF
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 minimize the HTTP overhead the provided names and descriptions should be kept as short as possible - e.g. use abbreviations and omit optional values where possible.
- Because there can be no guarantee of clock synchronization between client, server, and intermediaries, it is impossible to map a meaningful `startTime` onto the clients timeline. For that reason, any `startTime` attribution is purposely omitted from this specification. If the developers want to establish a relationship between multiple entries, they can do so by communicating custom data via metric names and/or descriptions.
- The server and/or any relevant intermediaries are in full control of which metrics are communicated to the user agent and when. For example, access to some metrics may be restricted due to privacy or security reasons - see
section.
"dur"] does not [=map/exists|exist=], return 0.
1. Let |dur| be the result of parsing this's params["dur"] using the [=rules for parsing floating-point number values=].
1. If |dur| is an error, return 0; Otherwise return |dur|.
Since duration is a {{DOMHighResTimeStamp}}, it usually represents a [=duration=] in
milliseconds. Since this is not enforcable in practice, duration can represent any unit
of time, and having it represent a [=duration=] in milliseconds is a recommendation.
### description attribute
The description getter steps are to return this's params["desc"] if it [=map/exists=], otherwise the empty string.
A {{PerformanceServerTiming}} has an associated string metric name, initially set to the empty string.
A {{PerformanceServerTiming}} has an associated ordered map params, initially empty.
### Extension to the {{PerformanceResourceTiming}} interface
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;
};
```
### serverTiming attribute
The serverTiming getter steps are the following:
1. Let |entries| be a new [=list=].
1. [=list/iterate|For each=] |field| in this's timing info's [=fetch timing info/server-timing headers=]:
1. Let |metric| be the result of [=parse a server-timing header field|parsing=] |field|.
1. If |metric| is not null, [=list/append=] |metric| to |entries|.
1. Return |entries|.
## IANA Considerations
The permanent message header field registry should be updated with the following registrations ([[RFC3864]]):
### Server-Timing Header Field
- Header field name
- Server-Timing
- Applicable protocol
- http
- Status
- standard
- Author/Change controller
- W3C
- Specification document
- This specification (See [=Server-Timing Header Field=])