Traces
Every request, job and scheduled tick opens a span; W3C traceparent propagation and sampling, seeded on the span every edge opens, stitch traces together.
Traces come from tracing spans. Because OpenTelemetry::init links
tracing-opentelemetry to
the OTel SDK at boot, every framework span is exported under the trace id the
kernel already decided — the SDK adopts it rather than minting a second one, so
a log line and the exported span name one request by one value. Every other span
automatically gets a trace_id
and exports through OTLP when an endpoint is configured.
Span targets
Section titled “Span targets”Targets are dotted, lowercase, framework-prefixed. One target per concern per crate.
| Layer | Target |
|---|---|
| HTTP request span | nest_rs::http — opened by the transport, not by this crate |
| Operation log, one line per unit of work | nest_rs::operation — the only target naming a kind of line rather than a subsystem; see The operation log |
| ORM queries | nest_rs::orm |
| Relation dataloaders | nest_rs::loader |
| Authentication | nest_rs::authn |
| Authorization | nest_rs::authz |
| WebSocket events | nest_rs::ws |
| GraphQL execution and subscriptions | nest_rs::graphql |
| MCP operations | nest_rs::mcp |
| Queue jobs | nest_rs::queue |
| Scheduled jobs | nest_rs::schedule |
| Module registration | nest_rs::module |
Lifecycle hooks (#[hooks]) | nest_rs::lifecycle |
| Application spans | <crate>::<feature> (e.g. features::users) |
Custom spans
Section titled “Custom spans”#[get("/{id}")]#[tracing::instrument(skip(self), fields(user_id = %id.0))]async fn read(&self, id: Path<Uuid>) -> Result<Json<User>> { let user = self.svc.find(id.0).await?; Ok(Json(user))}#[tracing::instrument] opens a span that stays current for the whole async
fn, across every .await. Inside it, use tracing::info! for an event.
Always prefer field = %value to format!("{}", value) — structured fields
serialize cleanly to OTLP and stay filterable in the backend.
W3C propagation
Section titled “W3C propagation”traceparent propagation is automatic on incoming HTTP requests — behind a
trusted proxy. The transport, not this crate, decides whether an inbound
traceparent may be believed: it is continued when the direct peer is in
<PREFIX>_HTTP__TRUSTED_PROXIES, and the trace is restarted otherwise, which
is what the specification defines a front gate to do. Without that gate any
client could file its request into a trace of its choosing and set the sampled
flag on traffic it generates. The response carries traceresponse so a caller
can match a span in their backend to a span in yours.
The W3C propagator is installed even when no OTLP endpoint is set — useful when a sibling service in your monorepo does export and you want the connection preserved across the hop.
Sampling
Section titled “Sampling”ParentBased(TraceIdRatioBased(ratio)) — children inherit the parent’s
sampling decision, so a request either samples end-to-end or not at all. The
deployment picks the sampler with the specification’s own variables, read as
the SDK reads them:
OTEL_TRACES_SAMPLER=parentbased_traceidratioOTEL_TRACES_SAMPLER_ARG=0.1A sampler the SDK does not build (jaeger_remote, xray, a misspelling,
Always_On — the names are lowercase) and an argument that is not a number
between 0 and 1 fail the boot naming the variable, where the SDK would sample
every trace in their place. An argument beside a sampler that takes none is
ignored and said at warn.
Or pinned, in main, under those variables:
let _otel = OpenTelemetry::init_with(OpenTelemetryConfig { trace_sample_ratio: 0.1, ..OpenTelemetryConfig::from_env()?})?;The sampler comes from
opentelemetry_sdk::trace::Sampler.
A pinned ratio outside [0.0, 1.0] fails init_with, naming
OpenTelemetryConfig::trace_sample_ratio.
The request span
Section titled “The request span”OpenTelemetry::init seeds what this crate adds onto the framework’s span
constructor, which every edge opens its unit through — there’s nothing to
mount, and no per-request interceptor. It does two things, and both are
things nothing else can supply:
- Links the remote parent when the transport continued an upstream trace, so the exported span is a child of the caller’s rather than a second root. A restarted trace has no parent by definition, and none is invented.
- Writes the sampler’s decision back onto the trace context, so an outbound
traceparent— into a queue envelope, back to the caller — reports what this deployment actually kept.
Everything else belongs to the transport and exists whether or not this crate is
installed: the span itself, its W3C trace context, the traceresponse response
header, and the access log. The span carries the OTel HTTP semantic-convention attributes:
http.request.method (a method the conventions know or a route registers,
spelled exactly, or _OTHER), url.path (the addressed path), url.scheme
(https or http: the client’s own, forwarded by a proxy
<PREFIX>_HTTP__TRUSTED_PROXIES lists, else the listener’s),
http.route (the
matched template, so a backend groups on something low-cardinality),
http.response.status_code, http.response.body.size and
user_agent.original. It carries no client.address, which the conventions
recommend: a client’s address is personal data, and a collector keeps what it
receives — no access line carries it either.
The span is the one place a value the client chose is kept, and only what
the conventions ask for. url.path, user_agent.original and — for a
method outside the known set — http.request.method_original are the client’s
to write. The conventions require or recommend them and the span goes to your
own collector, so it keeps them: a stated exception to the rule that no line
and no reply quotes a client’s value, which the
access line follows. A header the span
records beyond that set is one that parsed under its grammar: a traceparent
the transport did not continue is recorded as the four hex fields it parsed
to, and an X-Request-Id from a trusted proxy only in the shape a proxy mints
it — a UUID, or 16 to 64 hex digits, as nginx’s $request_id is. Anything
else is not recorded. The shape is all the span can check: behind a proxy
that forwards a client’s X-Request-Id, hex text the client wrote — a secret
minted as hex or as a UUID included — is recorded as a minted id would be.
It is named {method} {route} through otel.name. tracing fixes a span
name to a literal, and one literal for every route makes a trace list
unreadable. A request the router’s fallback
answers is named for its mount’s catch-all, GET /{*path} at the root. A
request neither a route nor the fallback claims is named by its method alone,
never by the URL, and a method outside the known set reads HTTP there, as
the conventions spell it.
Body size and duration are measured at end-of-body, not at handler return, so a half-streamed response and a client disconnect both still produce one access line and one complete span.
The request span and the access event both belong to nest-rs-http, and exist
whether or not this crate is installed. What this crate adds is the parent
from an inbound traceparent and the sampler’s verdict, seeded onto the span
constructor: no interceptor, and no header the access line reads.
Toggle the line with <PREFIX>_HTTP__ACCESS_LOG=false; nothing about propagation
or OTLP export changes.
Going further
Section titled “Going further”- Logs — the structured fields on the span.
- The operation log — the access event, one line per unit of work.
- Metrics — the aggregate counterpart to spans.
- OpenTelemetry — sampling, propagation, and OTLP export.