2.1 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) syntax for the Server-Timing header field is as follows:

Server-Timing = "Server-Timing" ":" #server-timing-metric

server-timing-metric   = metric  [ ";" description ]
metric                 = metric-name [ "=" metric-value ]
metric-name            = token
metric-value           = 1*digit [ "." 1*digit ]
description            = token | quoted-string

• Each metric MUST have a name.
  • Metric names MAY be repeated.
  • Metric names are defined by the server.
• Each metric MAY have an optional numeric value.
• Each metric MAY have an optional description.
• The user agent MAY surface provided metrics in any order - i.e. the order of metrics in the HTTP header field is not significant.

See [RFC7230] for definitions of token, digit, and quoted-string.

2.2 The PerformanceServerTiming Interface

The PerformanceServerTiming interface participates in the [PERFORMANCE-TIMELINE-2] and extends the following attributes of the PerformanceEntry interface:

name

This attribute MUST return the resolved URL of the requested resource [HTML5]. This attribute MUST NOT change even if the fetch redirected to a different URL.

entryType

This attribute MUST return the DOMString "server".

startTime

This attribute MUST return value 0.

duration

This attribute MUST return a DOMHighResTimeStamp [HR-TIME-2] that contains the server-specified metric value, or value 0.

interface ServerEntry : PerformanceEntry {
    readonly        attribute DOMString metric;
    readonly        attribute DOMString description;
    serializer = {inherit, attribute};
};

2.3 Extensions to the Performance Interface

partial interface Performance {
    void clearServerTimings ();
    void setServerTimingBufferSize (unsigned long maxSize);
                    attribute EventHandler onservertimingbufferfull;
};

3.1 Processing Model

1. Once the Window object of the current document is created the user agent MUST create a PerformanceEntryList object (primary buffer) to store the list of PerformanceServerTiming resources.
2. Set the primary buffer to a size of 150, unless otherwise specified by the user agent or set by the setServerTimingBufferSize method.
3. For each server-specified metric received via the Server-Timing header field perform the following steps:
   1. Create a new PerformanceServerTiming object and set entryType to the DOMString server.
   2. Set the name to the resolved URL of the requested resource.
   3. Set metric to the server-specified metric name.
   4. Set duration to the server-specified metric value, or value 0.
   5. Set description to the server-specified metric description, or an empty string.
   6. Set startTime to the value 0.
   7. If the primary buffer is full, discard the PerformanceServerTiming object, created in step 3. Otherwise, add it to the primary buffer . If adding it causes the primary buffer to become full, fire the servertimingbufferfull event at the Document.
      1. If the clearServerTimings method is called in the event handler for the servertimingbufferfull event, clear all PerformanceServerTiming objects in the primary buffer.
      2. If the setServerTimingBufferSize method is called in the event handler for the servertimingbufferfull event, set the maximum size of the primary buffer to the maxSize parameter. If the maxSize parameter is less than the number of elements currently stored in the buffer, no elements in the buffer are to be removed.

The user-agent MUST process Server-Timing header field communicated via a trailer field (see [RFC7230] section 4.1.2) using the same algorithm.

3.2 Cross-origin Resources

Cross-origin resources (i.e. non same origin) MUST be included as PerformanceServerTiming objects in the Performance Timeline. If the "timing allow check" algorithm, as defined in [RESOURCE-TIMING], fails for a cross-origin resource:

• The duration MUST be set to value 0.
• The description MUST be set to an empty string.

Server must return the Timing-Allow-Origin HTTP response header, as defined in [RESOURCE-TIMING], to allow the user agent to fully expose, to the document origin(s) specified, the values of attributes that would have been set to zero or empty string due to the cross-origin restrictions.

5.1 Server-Timing

Header field name

Server-Timing

Applicable protocol

http

Status

standard

Author/Change controller

W3C

Specification document

This specification (See Server Timing Header Field)