Skip to content

Server-Timing

Surface server-side latency in the browser's Network panel during development — one module import, optional sub-step records from any handler.

Server-Timing is a W3C header browsers render in their Network panel (DevTools → Network → Timing tab) — a per-request breakdown of where the time went. It rides on the HTTP transport as a unit-stage interceptor: importing ServerTimingModule brings one that appends a final total;dur=<ms> to every answer but a refusal — a route’s, a self-mount’s and what the router answers itself; handlers add their own sub-steps by recording into a per-request Timings accumulator pulled from the request extensions. It is a development surface: on in the development and test profiles, off elsewhere until the deployment turns it on.

This is observability for the frontend developer’s browser, not a replacement for proper tracing — for cross-service spans and aggregations, reach for OpenTelemetry.

Terminal window
cargo add nest-rs --features server-timing
apps/api/src/module.rs
use nest_rs::core::module;
use nest_rs::server_timing::ServerTimingModule;
#[module(imports = [ServerTimingModule])]
pub struct ApiModule;

In the development and test profiles, every response now carries a Server-Timing header. The minimum, unstructured form is one entry:

Terminal window
$ curl -i http://localhost:3002/posts -H "Authorization: Bearer $TOKEN" | grep -i server-timing
server-timing: total;dur=12.34

That alone shows up in DevTools next to the request — round-trip vs. server time becomes a glance.

A refusal never carries it. A 401, 403, 407 or 429 goes out without timings in every profile, so the caller an authentication or rate check turned away cannot read how long that check worked — and so does a refusal answered inside a 200: a /graphql operation refused UNAUTHENTICATED, FORBIDDEN or RATE_LIMITED, a /mcp operation its guards refused. Such a refusal marks the request it rode on, and a marked request goes untimed.

An event stream (text/event-stream) goes untimed too: its head leaves before the work it streams, so a total there would measure nothing — and on /mcp could time an operation its guards refuse after the head left.

Pull Timings out of the request extensions and call record (or record_with_desc) with a duration. The interceptor concatenates every recorded entry into the final header, with total appended on the way out:

crates/features/src/posts/http/controller.rs
use std::time::Instant;
use nest_rs::http::{controller, routes};
use nest_rs::server_timing::Timings;
use nest_rs::http::Request;
use std::sync::Arc;
use nest_rs::http::Json;
#[controller(path = "/posts")]
pub struct PostsController {
#[inject]
posts_svc: Arc<PostsService>,
#[inject]
media_svc: Arc<MediaService>,
}
#[routes]
impl PostsController {
#[get("/")]
async fn list(&self, req: &Request) -> Result<Json<Vec<Post>>> {
let timings = req.extensions().get::<Timings>().cloned().unwrap_or_default();
let started = Instant::now();
let posts = self.posts_svc.feed().await?;
timings.record("db", started.elapsed());
let started = Instant::now();
let posts = self.media_svc.with_cover_urls(posts).await?;
timings.record_with_desc("covers", "object-store lookup", started.elapsed());
Ok(Json(posts))
}
}

Each timed span wraps a service call — the handler measures, it never computes. Attributing a slow request across two backends is the case this header exists for; a controller that also transformed rows would be timing its own layering mistake.

Terminal window
$ curl -i http://localhost:3002/posts -H "Authorization: Bearer $TOKEN" | grep -i server-timing
server-timing: db;dur=7.82, covers;dur=0.41;desc="object-store lookup", total;dur=8.96
  • record(name, dur) — short entry; name must be a valid header token (no spaces, no commas).
  • record_with_desc(name, desc, dur) — desc shows as a tooltip in DevTools; any string is allowed, the formatter quotes/escapes for you.

Where the header is off, the request carries no Timings, and unwrap_or_default() hands the handler an accumulator nobody reads: the same handler runs in every profile.

The header hands every client the time each backend took, so outside the development and test profiles the module stamps nothing until the deployment says so — the posture the OpenAPI documentation has. The profile is <PREFIX>_ENV (the env cascade), production when the process declares none, and one variable opens the header:

Terminal window
$ NESTRS_ENV=staging NESTRS_SERVER_TIMING__ENABLED=true nestrs run start api

The boot then logs one warn on nest_rs::server_timing, with the environment it runs in, so the opening shows wherever the logs go. A staging dashboard that reads the header needs that line in its deployment.

The same switch can be pinned in code, as ServerTimingConfig’s one field:

apps/api/src/module.rs
use nest_rs::config::Surface;
use nest_rs::core::module;
use nest_rs::server_timing::{ServerTimingConfig, ServerTimingModule};
#[module(imports = [ServerTimingModule::for_root(ServerTimingConfig { enabled: Surface::Open })])]
pub struct ApiModule;

The variable still outranks the pin, field by field, so <PREFIX>_SERVER_TIMING__ENABLED=false closes a pinned header in one deployment. A pin over ServerTimingConfig::default() leaves the header to the profile: on in development and test, off in a deployment.

  • crates/nest-rs-server-timing/ — ServerTimingModule, ServerTimingConfig, Timings, Entry.
  • OpenTelemetry — for spans the frontend cannot see (cross-service traces, async work after the response, queue jobs).
  • Interceptors — the seam ServerTimingModule plugs into; the same shape any other cross-cutting concern uses.