Server Timing

https://w3c.github.io/server-timing/
Admin
This specification defines a mechanism for servers to communicate performance metrics about the...
Tokens:4,136
Snippets:30
Trust Score:8.3
Update:8 months ago
Show doc for...
Tokens:
Raw
### HTTP Server-Timing Header Example

Source: https://w3c.github.io/server-timing/index

Demonstrates the Server-Timing HTTP header format, showcasing various ways to communicate metrics including name only, name with duration, and name with description. This is useful for understanding how servers report performance data.

```http
> GET /resource HTTP/1.1
> Host: example.com


< HTTP/1.1 200 OK
< Server-Timing: miss, db;dur=53, app;dur=47.2
< Server-Timing: customView, dc;desc=atl
< Server-Timing: cache;desc="Cache Read";dur=23.2
< Trailer: Server-Timing
< (... snip response body ...)
< Server-Timing: total;dur=123.4
```

--------------------------------

### Accessing Server-Timing Data with JavaScript

Source: https://w3c.github.io/server-timing/index

Provides a JavaScript example of how to access Server-Timing metrics using the Performance API. It iterates through navigation and resource entries, checking for slow server-timing entries and logging them. This is crucial for client-side analysis and integration with analytics tools.

```javascript
// serverTiming entries can live on 'navigation' and 'resource' entries
for (const entryType of ['navigation', 'resource']) {
  for (const {name: url, serverTiming} of performance.getEntriesByType(entryType)) {
    // iterate over the serverTiming array
    for (const {name, duration, description} of serverTiming) {
      // we only care about "slow" ones
      if (duration > 200) {
        console.info('Slow server-timing entry =',
          JSON.stringify({url, entryType, name, duration, description}, null, 2))
      }
    }
  }
}
```

--------------------------------

### Extend PerformanceResourceTiming with serverTiming (WebIDL)

Source: https://w3c.github.io/server-timing/index

Extends the PerformanceResourceTiming interface to include the serverTiming attribute. This attribute returns a FrozenArray of PerformanceServerTiming objects, representing the server timing metrics associated with a resource.

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

--------------------------------

### PerformanceServerTiming Interface

Source: https://w3c.github.io/server-timing/index

Defines the structure for server timing metrics, including name, duration, and description.

```APIDOC
## Interface: PerformanceServerTiming

### Description
Represents a single server timing metric, providing its name, duration, and an optional description.

### Attributes
- **name** (DOMString) - Readonly. The metric name.
- **duration** (DOMHighResTimeStamp) - Readonly. The duration of the metric in milliseconds (recommended).
- **description** (DOMString) - Readonly. An optional description of the metric.

### Methods
- **toJSON()** - Returns a JSON representation of the PerformanceServerTiming object.
```

--------------------------------

### Extension to PerformanceResourceTiming interface

Source: https://w3c.github.io/server-timing/index

Describes how the `PerformanceResourceTiming` interface is extended to include a `serverTiming` attribute, allowing access to the `PerformanceServerTiming` objects associated with a resource.

```APIDOC
## Extension to PerformanceResourceTiming interface

### Description
Extends the existing `PerformanceResourceTiming` interface to include a `serverTiming` attribute. This allows applications to retrieve the `PerformanceServerTiming` metrics associated with a specific resource load.

### Method
N/A (JavaScript Interface Extension)

### Endpoint
N/A (JavaScript Interface Extension)

### Parameters
N/A

### Request Example
N/A

### Response
#### Success Response (200)
- **serverTiming** (sequence<PerformanceServerTiming>) - A list of `PerformanceServerTiming` objects associated with the resource.

#### Response Example
```javascript
// Assuming 'resourceTiming' is an instance of PerformanceResourceTiming
const serverTimings = resourceTiming.serverTiming;
serverTimings.forEach(timing => {
  console.log(`Metric: ${timing.name}, Duration: ${timing.duration}, Description: ${timing.description}`);
});
```
```

--------------------------------

### PerformanceResourceTiming Extension

Source: https://w3c.github.io/server-timing/index

Extends the PerformanceResourceTiming interface to include server timing information.

```APIDOC
## Interface Extension: PerformanceResourceTiming

### Description
Extends the existing PerformanceResourceTiming interface to include a `serverTiming` attribute, which provides access to server-sent timing metrics.

### Attributes
- **serverTiming** (FrozenArray<PerformanceServerTiming>) - Readonly. An array of PerformanceServerTiming objects representing the server timing metrics associated with the resource.
```

--------------------------------

### PerformanceServerTiming Interface

Source: https://w3c.github.io/server-timing/index

Defines the `PerformanceServerTiming` interface, which represents a single performance metric provided by the server. It includes attributes for the metric's name, duration, and an optional description.

```APIDOC
## PerformanceServerTiming Interface

### Description
Represents a single performance metric reported by the server. This interface provides attributes to access the metric's name, duration, and a descriptive text.

### Method
N/A (JavaScript Interface)

### Endpoint
N/A (JavaScript Interface)

### Parameters
N/A

### Request Example
N/A

### Response
#### Success Response (200)
- **name** (string) - The name of the performance metric (e.g., 'cache', 'db').
- **duration** (double) - The time in milliseconds that the metric took to complete. This attribute is optional and may not be present for all metrics.
- **description** (string) - A human-readable description of the metric. This attribute is optional.

#### Response Example
```javascript
{
  "name": "db",
  "duration": 50.75,
  "description": "Database Query"
}
```
```

--------------------------------

### Define PerformanceServerTiming Interface (WebIDL)

Source: https://w3c.github.io/server-timing/index

Defines the PerformanceServerTiming interface, which represents a single server timing metric. It includes read-only attributes for name, duration, and description, along with a toJSON method.

```WebIDL
WebIDL[Exposed=(Window,Worker)]
interface PerformanceServerTiming {
  readonly attribute DOMString name;
  readonly attribute DOMHighResTimeStamp duration;
  readonly attribute DOMString description;
  [Default] object toJSON();
};
```

--------------------------------

### Server-Timing Header Field

Source: https://w3c.github.io/server-timing/index

This section details the `Server-Timing` HTTP header field, which allows servers to send performance metrics directly to the user agent. It specifies the format and potential metrics that can be included.

```APIDOC
## Server-Timing Header Field

### Description
Allows servers to communicate performance metrics about the request-response cycle to the user agent via an HTTP header.

### Method
N/A (HTTP Header)

### Endpoint
N/A (HTTP Header)

### Parameters
#### Header Field
- **Server-Timing** (string) - Required - A custom header field containing performance metrics.

### Request Example
N/A

### Response
#### Success Response (200)
- **Server-Timing** (string) - The header field containing performance metrics. Example format: `metric1;desc="description1",metric2;dur=123.45;desc="description2"`

#### Response Example
```
Server-Timing: cache;desc="Cache Read",db;dur=50;desc="Database Query"
```
```

--------------------------------

### Server-Timing Header Field Registration

Source: https://w3c.github.io/server-timing/index

Details the IANA registration for the Server-Timing HTTP header field.

```APIDOC
## IANA Considerations: 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)
```

--------------------------------

### Server-Timing Header Field Specification

Source: https://w3c.github.io/server-timing/index

Defines the structure and parsing rules for the Server-Timing HTTP header.

```APIDOC
## Server-Timing Header Field

### Description
The `Server-Timing` header field communicates one or more metrics and descriptions for a given request-response cycle.

### ABNF Syntax
```
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
```

### Notes
- Multiple metrics with the same `metric-name` are allowed and must be processed.
- The order of metrics in the header is not significant.
- Unrecognized `server-timing-param-name`s should be ignored.
- `server-timing-param-name`s should not appear multiple times within a `server-timing-metric`. Only the first instance is processed.
- Extraneous characters after a `server-timing-param-value` or `metric-name` should be ignored.
- The specification establishes `dur` (duration) and `desc` (description) as optional parameters.

### Parsing Logic
1. Initialize `position` to the start of the header string.
2. Extract `name` by collecting characters until a semicolon (`;`) is encountered.
3. Trim whitespace from `name`. If `name` is empty, return null.
4. Create a `PerformanceServerTiming` object with `name`.
5. Initialize an empty ordered map for `params`.
6. While not at the end of the string:
   a. Advance `position` by 1.
   b. Extract `paramName` until an equals sign (`=`) is encountered.
   c. Trim whitespace from `paramName`. If empty or already exists in `params`, continue.
   d. Advance `position` by 1.
   e. Initialize `paramValue` as an empty string.
   f. Skip whitespace.
   g. If the character at `position` is a double quote (`"`):
      i. Extract `paramValue` as an HTTP quoted string.
      ii. Consume characters until the next semicolon (`;`).
   h. Else:
      i. Extract `rawParamValue` until a semicolon (`;`) is encountered.
      ii. Trim whitespace from `rawParamValue` to get `paramValue`.
7. Set the `metric`'s `params` to the collected map.
8. Return the `metric` object.
```
Tokens:
Raw