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.
Install
Section titled “Install”cargo add nest-rs --features server-timingWire it in
Section titled “Wire it in”use nest_rs::core::module;use nest_rs::server_timing::ServerTimingModule;
#[module(imports = [ServerTimingModule])]pub struct ApiModule;Run it
Section titled “Run it”In the development and test profiles, every response now carries a
Server-Timing header. The minimum, unstructured form is one entry:
$ curl -i http://localhost:3002/posts -H "Authorization: Bearer $TOKEN" | grep -i server-timingserver-timing: total;dur=12.34That 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.
Record sub-steps
Section titled “Record sub-steps”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:
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.
$ curl -i http://localhost:3002/posts -H "Authorization: Bearer $TOKEN" | grep -i server-timingserver-timing: db;dur=7.82, covers;dur=0.41;desc="object-store lookup", total;dur=8.96record(name, dur)— short entry;namemust be a valid header token (no spaces, no commas).record_with_desc(name, desc, dur)—descshows 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.
Turn it on in production
Section titled “Turn it on in production”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:
$ NESTRS_ENV=staging NESTRS_SERVER_TIMING__ENABLED=true nestrs run start apiThe 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:
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.
Reference
Section titled “Reference”crates/nest-rs-server-timing/—ServerTimingModule,ServerTimingConfig,Timings,Entry.
Going further
Section titled “Going further”- OpenTelemetry — for spans the frontend cannot see (cross-service traces, async work after the response, queue jobs).
- Interceptors — the seam
ServerTimingModuleplugs into; the same shape any other cross-cutting concern uses.