Skip to content

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.

Targets are dotted, lowercase, framework-prefixed. One target per concern per crate.

LayerTarget
HTTP request spannest_rs::http — opened by the transport, not by this crate
Operation log, one line per unit of worknest_rs::operation — the only target naming a kind of line rather than a subsystem; see The operation log
ORM queriesnest_rs::orm
Relation dataloadersnest_rs::loader
Authenticationnest_rs::authn
Authorizationnest_rs::authz
WebSocket eventsnest_rs::ws
GraphQL execution and subscriptionsnest_rs::graphql
MCP operationsnest_rs::mcp
Queue jobsnest_rs::queue
Scheduled jobsnest_rs::schedule
Module registrationnest_rs::module
Lifecycle hooks (#[hooks])nest_rs::lifecycle
Application spans<crate>::<feature> (e.g. features::users)
crates/features/src/users/http/controller.rs
#[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.

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.

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:

Terminal window
OTEL_TRACES_SAMPLER=parentbased_traceidratio
OTEL_TRACES_SAMPLER_ARG=0.1

A 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:

apps/api/src/main.rs
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.

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:

  1. 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.
  2. 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.

  • 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.