阅读中文版本

Server-Timing Metrics Header

Server-Timing reports named backend durations to the browser so performance data reaches real user monitoring without shipping a client-side probe.

Definition

The Server-Timing response header carries one or more metric entries, each with a name and a duration in milliseconds, describing where time was spent while the server handled the request.

It is useful for correlation between front-end timing APIs and server-side work such as database or cache time. Compared to simpler alternatives, this concept fits best when the trade-off it represents is the one the system actually cares about.

When to use it

A common use case is applying it at the boundary where the cost of getting it wrong is highest, and the scenario usually involves a concrete guarantee the system must uphold. Unlike an ad hoc approach, it makes that guarantee explicit, reviewable, and testable.

How it works

Entries use the syntax name;dur=milliseconds, optionally with a description, and repeated names are allowed so a handler can report several internal phases.

Browsers expose the values through the PerformanceResourceTiming interface, which lets a real user monitoring beacon merge server-side durations with navigation and resource timings.

Trade-offs and alternatives

Because headers add bytes to every response, gate detailed timings behind a sampling rate or a debug flag and never include anything that could leak internal topology or user data. The main drawback is the extra complexity it introduces, so the benefit should clearly outweigh that cost before a team adopts it.

Common misconceptions

A persistent misconception is that Server-Timing measures network latency between client and server. Another is that these values are visible to the end user and therefore sensitive. For example, an engineer who assumes otherwise may design around a guarantee that does not actually exist, which only becomes obvious under load or failure.

Anti-patterns to avoid

Two recurring anti-patterns are to emitting per-request timings on a high-volume endpoint without sampling and to putting user identifiers or query text into metric names. Both tend to surface as hard-to-debug production issues rather than obvious test failures. Related concepts include Hop-by-Hop Versus End-to-End Headers, HTTP Trailer Fields, CAA Records Constraining Certificates.