Header
Performance-Timing
Learn about Performance-Timing, a non-standard header for exposing server-side performance metrics to clients. Understand its use cases and alternatives.
What is Performance-Timing?
TL;DR:
Performance-Timingis a non-standard custom header. Use Server-Timing for standards-based metrics in DevTools and the Performance API.
Performance-Timing appears in some legacy apps, reverse proxies, and internal APIs to expose backend durations. It is not defined by an IETF or WHATWG HTTP header specification, so browsers and tools do not treat it consistently.
If you only need a private debug signal, it can still be useful. For public-facing telemetry and modern browser tooling, prefer Server-Timing.
Typical Legacy Syntax
There is no official grammar, so teams invent their own formats:
Performance-Timing: app=12ms;db=47ms;cache=3ms
```text
or:
```http
Performance-Timing: total=83, db=47, cache=3Because this is custom, parsers in clients often break when format changes.
Recommended Standard: Server-Timing
Use Server-Timing for interoperable metrics:
Server-Timing: db;dur=47;desc="Postgres", cache;dur=3;desc="Redis", app;dur=12
```text
This works with:
- Browser DevTools timing panels
- `PerformanceResourceTiming.serverTiming` in JavaScript
- Standards-based observability pipelines
## Migration Pattern
If you already emit `Performance-Timing`, migrate safely by shipping both headers during rollout:
```http
Performance-Timing: app=12ms;db=47ms;cache=3ms
Server-Timing: app;dur=12, db;dur=47, cache;dur=3After clients switch, remove Performance-Timing.
Common Mistakes
- Mixing units (
ms,s, raw numbers) in one header value - Exposing sensitive internal names (cluster IDs, SQL table names)
- Assuming browsers will visualize this header automatically
Related Headers
Why Performance-Timing Is Not Standardized
The absence of a standard for Performance-Timing is intentional. The HTTP working group recognized that a single header for all server-side timing metrics would be too rigid, so they designed Server-Timing with a flexible multi-metric syntax instead. Performance-Timing emerged organically in various frameworks and proxies before Server-Timing existed, which is why you still encounter it in legacy codebases and older middleware.
The Server-Timing header was standardized by the W3C in the Server Timing specification and is now supported in all major browsers. It integrates with the Performance API, allowing JavaScript to read server-side timing data programmatically via PerformanceResourceTiming.serverTiming. This makes it possible to correlate server-side metrics with client-side performance data in a single observability pipeline.
If you are maintaining a system that uses Performance-Timing, the migration path to Server-Timing is straightforward. Parse your existing Performance-Timing format, convert each metric to the name;dur=value;desc="description" syntax, and emit both headers during a transition period. Once all consumers have been updated to read Server-Timing, remove Performance-Timing. The transition is non-breaking because clients that do not understand Server-Timing will simply ignore it, and clients that do not understand Performance-Timing will ignore that instead.
Frequently Asked Questions
What is Performance Timing?
Performance Timing APIs measure page load and resource timing. They provide detailed metrics like DNS lookup, connection time, and content download duration.
How do I access performance timing data?
Use performance.timing for navigation timing, performance.getEntriesByType("resource") for resource timing. Modern APIs use PerformanceObserver.
What are the key timing metrics?
Key metrics include TTFB (responseStart - requestStart), DOM Content Loaded, Load event, and Core Web Vitals (LCP, FID, CLS).
How do HTTP headers affect timing?
Headers like Server-Timing provide server-side metrics. Timing-Allow-Origin controls cross-origin timing access. Cache headers affect resource timing.