Copyright © 2017 W3C® (MIT, ERCIM, Keio, Beihang). W3C liability, trademark and permissive document license rules apply.
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.
This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at https://www.w3.org/TR/.
This document was published by the Web Performance Working Group as a Working Draft. This document is intended to become a W3C Recommendation. Comments
regarding this document are welcome. Please send them to
public-web-perf@w3.org (subscribe,
archives) with [server-timing]
at the start of your email's subject.
Publication as a Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.
This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.
This document is governed by the 1 March 2017 W3C Process Document.
This section is non-normative.
Accurately measuring performance characteristics of web applications is an important aspect of making web applications faster. [NAVIGATION-TIMING-2] and [RESOURCE-TIMING-2] provide detailed request timing information for the document and its resources, which include time when the request was initiated, and various milestones to negotiate the connection and receive the response. However, while the user agent can observe the timing data of the request it has no insight into how or why certain stages of the request-response cycle have taken as much time as they have - e.g., how the request was routed, where the time was spent on the server, and so on.
This specification introduces PerformanceServerTiming
interface, which enables the server to communicate performance metrics about the request-response
cycle to the user agent, and a JavaScript interface to enable applications to collect, process, and act on these metrics to optimize application delivery.
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 [ OWS ";" OWS description ]
metric = metric-name [ OWS "=" OWS metric-value ]
metric-name = token
metric-value = 1\*DIGIT [ "." 1\*DIGIT ]
description = token | quoted-string
See [RFC7230] for definitions of token
, DIGIT
, quoted-string
, and OWS
.
To minimize the HTTP overhead the provided metrics 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 6. Privacy and Security section.
PerformanceServerTiming
Interface
[Exposed=(Window,Worker)]
interface PerformanceServerTiming
{
readonly attribute DOMString metric
;
readonly attribute double value
;
readonly attribute DOMString description
;
[Default]
object toJSON
();
};
When toJSON
is called, run [WEBIDL]'s
default toJSON operation.
metric
attribute
The metric
attribute MUST return the server-specified metric-name.
value
attribute
The value
attribute MUST return a double that contains the server-specified metric-value, or value
0.0
.
description
attribute
The description
attribute MUST return the server-specified metric-description, or an empty string.
PerformanceResourceTiming
interface
The PerformanceResourceTiming
interface, which this specification partially extends, is defined in [RESOURCE-TIMING-2].
[Exposed=(Window,Worker)]
partial interface PerformanceResourceTiming
{
readonly attribute FrozenArray<PerformanceServerTiming
> serverTiming
;
};
serverTiming
attribute
The serverTiming
attribute returns a sequence of PerformanceServerTiming
entries.
When processing the response of the current document call the server-timing header parsing algorithm with resource timing object set to the newly created
PerformanceNavigationTiming
object.
For each resource fetched by the current browsing context, excluding resources fetched by cross-origin stylesheets
fetched with no-cors
policy, call the server-timing header parsing algorithm with resource timing object set to
the newly created
PerformanceResourceTiming
object.
Given a resource timing object, perform the following steps:
PerformanceServerTiming
object.metric
to the server-specified metric-name.value
to the server-specified metric-value, or value 0 if omitted or not representable as a double.description
to the server-specified metric-description, or an empty string.serverTiming
attribute on resource timing object to
entryList.
The user-agent MUST process Server-Timing header field communicated via a trailer field (see [RFC7230] section 4.1.2) using the same algorithm.
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-2],
fails for a cross-origin resource:
value
MUST be set to value 0.description
MUST be set to an empty string.Server must return the Timing-Allow-Origin
HTTP response header, as defined in [RESOURCE-TIMING-2], 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.
This section is non-normative.
The interfaces defined in this specification expose potentially sensitive application and infrastructure information to any web page that has included a resource that advertises server timing metrics. For this reason the access to PerformanceServerTiming
interface is restricted by the same origin policy by default, as described in 5.2 Cross-origin Resources.
Resource providers can explicitly allow server timing information to be available by adding the Timing-Allow-Origin
HTTP response header, as defined in [RESOURCE-TIMING-2],
that species the domains that are allowed to access the server metrics.
In addition to using the Timing-Allow-Origin
HTTP response header, the server can also use relevant logic to control which metrics are returned, when, and to whom - e.g. the server may only provide certain metrics to correctly authenticated
users and nothing at all to all others.
The permanent message header field registry should be updated with the following registrations ([RFC3864]):
This section is non-normative.
> GET /resource HTTP/1.1 > Host: example.com < HTTP/1.1 200 OK < Server-Timing: miss, db=53, app=47.2; < Server-Timing: customView, dc;atl < Trailer: Server-Timing < (... snip response body ...) < Server-Timing: total=123.4
Name | Value | Description |
---|---|---|
miss | ||
db | 53 | |
app | 47.2 | |
customView | ||
dc | atl | |
total | 123.4 |
The above header fields communicate five distinct metrics that illustrate all the possible ways for the server to communicate data to the user agent: metric name only, metric with value, metric with value and description, and metric with description.
For example, the above metrics may indicate that for example.com/resource.jpg
fetch:
The application can collect, process, and act on the provided metrics via the provided JavaScript interface:
// Gather server timing for a particular resource
const serverTimings = window.performance
.getEntriesByName("https://example.com/resource.jpg", "resource")
// Get just the serverTiming array
.map(({ serverTiming }) => serverTiming);
serverEntries
// we only care about "slow" ones
filter({ value } => value > 2.0)
// process just the attributes we are interested in
.forEach(({ name, value, description }) => {
// ...
});
// Aternatively, we convert each into JSON
const entriesAsJson = serverEntries.map(entry => entry.toJSON());
This section is non-normative.
Server processing time can be a significant fraction of the total request time. For example, a dynamic response may require one or more database queries, cache lookups, API calls, time to process relevant data and render the response, and so on. Similarly, even a static response can be delayed due to overloaded servers, slow caches, or other reasons.
Today, the user agent developer tools are able to show when the request was initiated, and when the first and last bytes of the response were received. However, there is no visibility into where or how the time was spent on the server, which means that the developer is unable to quickly diagnose if there is a performance bottleneck on the server, and if so, in which component. Today, to answer this question, the developer is required to use different techniques: check the server logs, embed performance data within the response (if possible), use external tools, and so on. This makes identifying and diagnosing performance bottlenecks hard, and in many cases impractical.
Server Timing defines a standard mechanism that enables the server to communicate relevant performance metrics to the client and allows the client to surface them directly in the developer tools - e.g. the requests can be annotated with server sent metrics to provide insight into where or how the time was spent while generating the response.
In addition to surfacing server sent performance metrics in the developer tools, a standard JavaScript interface enables analytics tools to automatically collect, process, beacon, and aggregate these metrics for operational and performance analysis.
Server Timing enables origin servers to communicate performance metrics about where or how time is spent while processing the request. However, the same request and response may also be routed through one or more multiple proxies (e.g. cache servers, load balancers, and so on), each of which may introduce own delays and may want to provide performance metrics into where or how the time is spent.
For example, a CDN edge node may want to report which data center was being used, if the resource was available in cache, and how long it took to retrieve the response from cache or from the origin server. Further, the same process may be repeated by other proxies, thus allowing full end-to-end visibility into how the request was routed and where the time was spent.
Similarly, when a Service Worker is active, some or all of the navigation and resource requests may be routed through it. Effectively, an active Service Worker is a local proxy that is able to reroute requests, serve cached responses, synthesize responses, and more. As a result, Server Timing enables Service Worker to report custom performance metrics about how the request was processed: whether it was fetched from server or server from local cache, duration of relevant the processing steps, and so on.
This section is non-normative.
This document reuses text from the [NAVIGATION-TIMING-2], [RESOURCE-TIMING-2], [PERFORMANCE-TIMELINE-2], and [RFC6797] specifications as permitted by the licenses of those specifications.