Server Timing Laravel Package

Technical Evaluation

Architecture fit. fetzi/server-timing is a narrowly scoped instrumentation library: it collects named timers during request handling and serializes them into the W3C Server-Timing response header, which browsers surface in DevTools and via the PerformanceServerTiming JS API. This positions it as a developer-facing latency breakdown layer, not an observability platform. For a Laravel monolith or API this is a good fit when the goal is "let engineers see where the 800ms went without leaving the browser," and a poor fit as a substitute for APM (no aggregation, no percentile math, no cross-request storage, no alerting). Architecturally it is a thin middleware + timer registry — low conceptual weight, easy to reason about, unlikely to entangle with domain code.

Integration feasibility. The package is PSR-oriented (PSR-7/PSR-15 style middleware and a timer abstraction). Laravel integration is therefore either an officially documented adapter or a ~40-line custom middleware that resolves timers from the container and appends the header to the response. Verify before committing:

• Whether a Laravel service provider / middleware ships in the package or must be hand-written.
• Whether timers are bound per-request (container-scoped) or shared state — critical for Octane/Swoole/worker-mode residency.
• Whether the header is emitted on exception/error responses (5xx are exactly when you want the timing breakdown).
• How it composes with existing middleware that replaces responses (e.g., response caching, ETag, compression).

Overall integration risk is low: the package cannot corrupt business logic, only attach a header.

Technical risk.

• Information disclosure (primary risk): metric names and durations leak internal structure — table names, downstream service names, query counts — to any client, including unauthenticated ones. This must be environment-gated and ideally route-scoped.
• Maintenance/bus factor: 44 stars, single-maintainer, MIT. Small surface area means it is trivially forkable and vendorable, which materially mitigates abandonment risk. Pin the version; do not float.
• Redundancy: if OpenTelemetry or a comparable tracer is planned, Server-Timing becomes a second, inconsistent source of timing truth. Decide up front whether this is a stopgap or a permanent DX affordance.
• Header bloat: each metric is ~20–60 bytes; 30 metrics across every response is measurable on high-RPS JSON endpoints and interacts with proxy header buffer limits.

Key questions.

1. Is a Laravel adapter shipped, or do we own the middleware?
2. Does the timer state survive Octane workers correctly, or does it need per-request scoping?
3. Can metric emission be conditioned on env, route, or an opt-in header (e.g., X-Server-Timing: 1)?
4. Does it capture DB query time and outbound HTTP latency out of the box, or only explicit user-defined spans?
5. What is the maintainer's release cadence and issue-response history over the last 12 months?
6. Does it play correctly with response caching — do cached responses carry stale timings?

Integration Approach

Stack fit. Laravel 10/11/12 on PHP 8.1+ is a natural fit: Composer install, one middleware registration in bootstrap/app.php (L11+) or Http/Kernel.php, optional config file for metric allow-listing. No database, queue, or infrastructure dependency. This is a same-sprint change, not a project.

Migration path. Additive and reversible by removing one middleware line or flipping a config flag — no schema changes, no data migration, no client contract change. The only "migration" concern is retiring it later if OTel supersedes it, which is a deletion, not a migration.

Compatibility. Verify the composer.json PHP and PSR constraints against our runtime before adoption. Check Laravel version support explicitly — Laravel's middleware contract is not PSR-15, so any adapter is Laravel-specific and version-sensitive. Test the header assertion in the existing feature-test suite to catch regressions on framework upgrades.

Sequencing.

1. Spike (0.5 day): install on a branch, wire middleware to a single non-production route, confirm header shape in Chrome DevTools and via curl -I.
2. Convention setting (0.5 day): decide metric naming (e.g., db, cache, ext_api, app) and a hard cap on metric count. Without a naming policy this decays into noise.
3. Instrumentation (1–2 days): add timers at the three or four boundaries that actually matter — bootstrap, DB, cache, outbound HTTP, view render. Resist instrumenting everything.
4. Gating (0.5 day): environment-scoped enablement, plus a header-based opt-in (X-Server-Timing: 1) for production if we want it live without exposing internals to all traffic.
5. CI + rollout (0.5 day): test asserting header presence on a sample route; ship behind config defaulting to off in production, on in staging.
6. Evaluate (2–4 weeks): did it actually shorten debugging cycles, or did engineers go straight to the APM anyway? Kill it if the answer is the latter.

Operational Impact

Maintenance. Low code surface, high bus-factor exposure. Pin to an exact version, vendor the source if the maintainer goes quiet, and budget ~4 hours/quarter to review upstream releases. Because the library is small and MIT, the realistic worst case is "we own a 500-line fork," which is acceptable — but someone must be named as owner.

Support. Community-only; no SLA, no vendor escalation. Acceptable for a developer-tooling concern, unacceptable if any customer-facing SLA or compliance report depends on these numbers. Position it explicitly as an internal DX aid, never as an SLO measurement source.

Scaling. Per-request CPU overhead is negligible (a few hrtime calls). The scaling concerns are elsewhere:

• Header size — a fixed budget (roughly ≤8 metrics, ≤1KB) should be enforced, since every response pays it at every RPS.
• Cardinality — metrics must be static names, not interpolated with IDs or table names, or the header becomes both unbounded and an information-disclosure vector.
• No aggregation — it scales horizontally by doing nothing, which also means it gives you zero fleet-wide visibility. Pair with real telemetry.

Failure modes.

• Timer exception escapes and turns a 200 into a 500 — middleware must wrap collection in try/catch and fail open.
• Silent stripping by CDN, load balancer, or reverse proxy (Cloudflare, ALB, nginx buffer limits) — header appears in staging and vanishes in production; verify end-to-end through the actual edge.
• Internal topology leakage to unauthenticated clients — mitigate with env gating and static metric names.
• Cache poisoning of timings — a cached response replays stale durations; suppress the header on cache hits or emit a distinct cache;desc=hit metric.
• Octane cross-request bleed — timers accumulating across requests in a resident worker, producing absurd or growing values; must be verified under Octane specifically.

Ramp-up. Near-zero for a mid-level Laravel engineer: one day to integrate, one day to establish conventions. The real onboarding cost is cultural — teaching the team to reach for the browser timing panel before adding log statements, and to keep metric names curated. If that habit doesn't form inside a month, the package is dead weight and should be removed rather than maintained.