Latency tracing (a v10r span API, Server-Timing as one renderer)

Generated from pattern-library/registry.json — do not edit by hand; change the registry and run bun run patterns:build.

Category: Velocity Measurement · Tier: deep · Maturity: proven (verified 2026-09-09 @ 921e8266-dirty) · Risk: medium — it sits on every request, and the header is client-readable

Every layer records spans into a request-scoped recorder stamped by the outermost handler; Server-Timing renders them for callers who already see internals, and unattributed reports the wall-clock time no span claimed.

When to use: Use anywhere performance matters and a slow response needs to decompose — the request lifecycle, domain operations, databases, caches, external services.

Docs

• docs/blueprint/velocity/measurement.md#latency-tracing — Why unattributed is a floor, not a figure (GitHub · GitLab)

Code

• src/lib/server/http/request-timing.ts — The span API domain code records into (GitHub · GitLab)
• src/hooks.server.ts — requestTiming, outermost so total is the whole request (GitHub · GitLab)

Tests

• src/lib/server/http/request-timing.test.ts (GitHub · GitLab)
• src/lib/server/security/handle-chain.gate.test.ts — Pins the tracer outermost and the IP stamp above everything that consumes it (GitHub · GitLab)

Proof

• /showcases/observability/overview

Invariants

• Instrumentation does not materially damage performance — a span is one clock pair and one push, and the span list is capped so instrumenting inside a loop degrades to silence rather than to unbounded memory.
• unattributed is a FLOOR, not a figure: concurrent spans overlap, so their durations can sum past the wall clock and the value clamps at zero. A zero means 'spans covered it', never 'nothing was missed'.
• Full span detail is disclosure — it maps internal architecture and hands out a timing oracle — so it goes only to callers who already see internals.
• Span names are sanitized to header tokens; a raw name would inject a delimiter and corrupt every field after it.
• Coverage is stated, not implied: prerendered routes never reach the handler on a CDN-served deployment.

Emulation notes

• Own the tracing API and put the vendor behind it. Domain code depends on the shape, so swapping Server-Timing for an OpenTelemetry exporter is one adapter, not a migration — and no dependency is needed to start.
• The tracer must be the OUTERMOST middleware or total measures a subset, and every 'unattributed' figure derived from it is understated. Where a security handler must be first for its own reasons, prove the ordering in a gate rather than arguing it in a comment.
• Round durations coarsely. Finer resolution is noise at request scale and a sharper clock is a sharper side channel.

Machine-readable record: latency-tracing in pattern-library/registry.json.