Skip to content

Logs

The tracing log macros flow to the console and to OTel logs with structured fields, a configurable level per layer, and JSON for prod.

tracing::info!, debug!, warn!, error! are the framework’s logging API. Every event flows through the installed subscriber to the console and, when OTLP is configured, through the OpenTelemetryTracingBridge to OTel logs. Backend collectors index them alongside the traces of the same request.

ConcernTargetDefault level
Operation log — one line per unit of work, every edgenest_rs::operationinfo
HTTP spannest_rs::httpinfo; the chain a 5xx answer withholds — any error’s, a framework error’s included — at error (warn behind a 503)
MCP operationsnest_rs::mcpinfo
Route / endpoint mounting (boot)nest_rs::routesinfo
ORM queriesnest_rs::ormtrace
Relation dataloaders (#[expose(…, graphql)] batches)nest_rs::loaderdebug
Layer composition (per-route guard/pipe/… chains)nest_rs::layerstrace for the per-route effective-chain dump; debug for the redundant multi-scope lint (HTTP deduped once, WS per gateway); warn for actionable posture smells (reversed authn/authz order, the denials of a guard declaring no target, a gated endpoint denying every request for want of a guard)
A guard’s denialsthe guard’s own (Guard::target)warn, error for a 500: one guard denied the … per denial, filed by the edge, with the reason the denial names
Authn / Authznest_rs::authn / nest_rs::authzinfo (denials warn)
OAuth clientnest_rs::oauth::clientinfo (callback refusals warn, a redirect no header can carry error)
OAuth authorization server (token endpoint)nest_rs::oauth::serverwarn for each client ClientAuthenticationGuard refuses, its reason the strategy’s and its cause naming the method; the cause a server_error withholds is filed on nest_rs::http
RFC 9728 discoverynest_rs::oauth::resourceinfo (boot misconfiguration warn)
WebSocket eventsnest_rs::wsinfo
GraphQL execution and subscriptionsnest_rs::graphqlinfo
Queue / Schedulenest_rs::queue / nest_rs::scheduleinfo
Redis connection (the RedisConnection the queue, the worker, the rate-limit store and the schedule’s lock share, one per instance, each line carrying its instance)nest_rs::rediswarn per connect attempt while the boot budget runs
Module registrationnest_rs::moduleinfo
Lifecycle hooks (#[hooks])nest_rs::lifecycleerror for a hook that failed or panicked, warn for one abandoned at the budget
Application spans<crate>::<feature> (e.g. features::users)info

Controllers, resolvers, gateways log at info on success. Services keep per-call chatter at debug; a discrete operational event a service owns — a job enqueued, a file transcoded — earns info. Repo at trace. Access denials and security events at warn+ so they appear under the default info filter. A production deploy should respect info — no per-request debug! on the hot path.

The framework’s subscribers write the events of every library in the process, and a few of them quote what a client sent, or a secret, below some level. A line never carries either, so each of those libraries is clamped: its events are written from the level below which it quotes nothing at most. A clamp only narrows RUST_LOG, never opens what it closes: under warn, tungstenite writes its warnings and nothing below, and under nest_rs=debug no library writes at all.

LibraryWritten fromBelow that, it quotes
rmcpnothing (off)a client’s initialize params, notifications and cancel reasons (info); its Host and protocol-version headers (warn); the session id it named, when the session store fails (error); each tool call’s arguments and reply (debug, trace)
h2errora PING’s opaque data (warn); a GOAWAY’s debug data (debug)
rustlserrora client’s SNI (warn); its whole ClientHello (trace)
sqlx_postgreserrora malformed .pgpass line, password included, and an unknown connection parameter’s value (warn)
sea_ormdebugits connect span’s whole connection options, the URL’s password included (trace): a span’s fields reach your exporter whatever the console prints
tungsteniteinfoa close frame’s reason (debug); every message (trace)
opentelemetry-otlpinfothe export URL, whose userinfo or query may carry a collector’s credential, and the collector’s error body (debug)

A directive naming the library — or one of its modules — replaces its clamp, because EnvFilter keeps the later of two directives for one target and yours come after the framework’s: RUST_LOG=info,rmcp=debug writes rmcp’s debug lines, and with them what the table says they quote, so keep it to a development run. Under the clamp, one /mcp denial files one line, the framework’s: rmcp’s own response error is a warn, and a Host rmcp refuses is said by the mount, without the value. The mount also says, on nest_rs::mcp and without the session a client named, each failure rmcp’s own lines reported: a session call that failed (mcp session manager failed, error, its call), a stream that could not resume (warn), and a failure of your SessionStore (mcp session store failed, error for a load rmcp answers 500, warn for a store or a delete it carries on past). Two stay rmcp’s alone: why a session’s handshake failed in its worker — the session is closed, and a call still waiting on it is said as a failed session call — and an event store’s persist failures, which the mount never reaches: it opens no event store. The statement log <PREFIX>_SEAORM__SQLX_LOGGING turns on is sqlx::query’s and stays open — it writes each statement’s SQL, its values bound apart.

Two of EnvFilter’s rules reach a clamp. A directive matches every target its name begins with, so rustls=error also holds rustls-platform-verifier’s warnings, which rustls_platform_verifier=warn opens alone. And a span directive ([audited]=debug) opens what runs inside the span it names, a clamped library’s events included.

crates/features/src/users/service.rs
tracing::info!(
target: crate::users::TARGET,
user_id = %id,
"creating user",
);

user_id is the subject the event is about. Who asked for it is not a field you write: the operation span carries actor_id, and restating it here gives a backend two spellings of one fact.

Always prefer field = %value to format!("{}", value). The OTLP bridge serializes structured fields directly; a formatted string becomes opaque text the backend cannot filter on.

Every event runs under the operation span its edge opened, which already carries trace_id and span_id — the OpenTelemetry log-record vocabulary, so a backend joins logs to traces with no field mapping — and actor_id once an authn guard resolved a principal. Your structured fields layer on top of those, and you never write either by hand.

Both are also readable from code, anywhere the framework carries work: a handler, a service below it, a WS message, an MCP tool, a queue job in another process. And inside a streaming response, which is the one that surprises people — an #[sse] stream is written after its handler returned, and it still runs under the request that opened it.

crates/features/src/users/service.rs
let trace_id = nest_rs::core::current_trace_id();
let span_id = nest_rs::core::current_span_id();
// `None` for an anonymous caller — absence is the answer, not a missing one.
let actor_id = nest_rs::core::current_actor_id();

actor_id is an audit identity: who, for a log line or a created_by column. What a caller may do is decided in a guard, never by branching on this value.

Every log line carries the W3C trace context of the unit of work that emitted it, in both formats — trace_id, span_id, and actor_id once a guard resolved a principal. That is the whole correlation mechanism: two lines belong to the same work when the ids match, and you join them on that.

Terminal window
DEBUG features::posts: creating post title="hello" trace_id=01a01569ae687353bc034a9ee8bd8774 span_id=a3f7cc8bac648278 actor_id=01a0112ce24e75509be691162cbbab1f
{"timestamp":"2026-08-18T15:07:22.601081Z","level":"DEBUG","fields":{"message":"creating post","title":"hello"},"target":"features::posts","trace_id":"01a01569ae697a718f7e41c79e0eefe6","span_id":"39d4f26e5d048754","trace_flags":"01","actor_id":"01a0112ce24e75509be691162cbbab1f"}

This owes nothing to a collector, an exporter or this crate: the trace context is a kernel primitive, so a bare app logging to a terminal has it. Adding nest-rs-opentelemetry exports the same ids — it does not own them, and it does not change the shape of a line.

The ids are read from the context, never from the span

Section titled “The ids are read from the context, never from the span”

A line carries no span attributes and no span names. That is worth stating, because the alternative looks harmless and is not. A service runs under the HTTP request’s span, so rendering span state put the request’s method, path and user agent on every line the service emitted. The line stopped being about what the service did. Nested work made it worse, printing one trace_id per level:

Terminal window
DEBUG http.request{otel.kind="server" trace_id=01a014ec…a4 span_id=5fcb…b7 http.request.method=POST url.path="/posts"}:mcp.operation{otel.kind="server" trace_id=01a014ec…a4 span_id=b0c0…72}: features::posts: creating post title="hello"

Reading the context instead of the scope is what makes the line self-contained, and it is the same read your own code does:

crates/features/src/users/service.rs
let trace_id = nest_rs::core::current_trace_id();
let span_id = nest_rs::core::current_span_id();
let actor_id = nest_rs::core::current_actor_id();

It also reaches further than a span stack can. A streaming body is polled after its handler returned; the framework re-installs the request around it, so those lines carry the ids too.

Span structure itself is untouched — nesting is normal, and it is what the OTLP export builds its tree from. And since no line prints a span’s fields, the console never formats them: an attribute the export reads costs the console nothing.

The ids relate lines to each other; what the work was is one more line per unit of work, on nest_rs::operation, which every edge files: The operation log.

The console layer ships both formats, and the declared profile picks one: text under <PREFIX>_ENV=development or test, json under any other — production and an undeclared process alike, whatever the cargo build profile. Either is set on the process when a run wants the other:

Terminal window
NESTRS_LOG_FORMAT=text

A value that is neither stops the boot, naming the variable: a typo never falls back to the profile’s default in silence.

text is coloured only where stdout is a terminal. Piped to a reader — a logfmt parser, grep, a container’s log driver — or written to a file, a line carries no escape code to strip, and NO_COLOR set to anything but empty turns the colour off on a terminal too, as no-color.org asks.

Both are the framework’s own formatters, and they say the same thing: JSON puts trace_id, span_id and actor_id at the top level of the record, where a backend reads them with no field mapping, rather than nested under a span object. There is no variable that puts span state back on a line.

JSON also carries trace_flags, the third field OpenTelemetry’s log data model names beside the two ids. Text does not: a record joined against an export needs to know whether the export exists, and a human at a console never acts on a sampling bit.

To trace a console line back to the exact source that emitted it, enable source location:

Terminal window
NESTRS_LOG_SOURCE_LOCATION=true

Each event then carries the emitting file:line:

Terminal window
DEBUG nest_rs::layers: crates/nest-rs-core/src/layer_chain.rs:702: redundant layer declaration deduped…

Off by default — it widens every line and leaks source paths, so it stays out of production. Turn it on in .env.development (next to RUST_LOG=debug) so it is live while developing and off everywhere else, or pin it explicitly with log_source_location: true in the OpenTelemetryConfig init_with takes, which <PREFIX>_LOG_SOURCE_LOCATION still overrides.

Under #[nest_rs::main] the console is written by a thread of its own, nestrs-log, through a queue of 16 384 lines (CONSOLE_QUEUE_LINES), so no task waits on stdout. It writes in batches: a line that wakes it waits up to 2 ms for the lines filed after it, and they leave in one write, so a busy app pays one write for many lines. When stdout stops taking lines — a full pipe, a container log driver that stalled — the queue fills, and a line that finds it full is dropped rather than waited for: the app keeps answering. Once a second, while lines were dropped, one warn says how many since the process started:

Terminal window
WARN nest_rs::app: log lines dropped while the console was stalled dropped=83617

That line takes the same queue; if it is dropped too, the next one carries the larger count. A line stdout refuses outright — its reader gone — is counted the same way, and the first refusal is said on stderr. Every exit #[nest_rs::main] controls — main returning, a panic leaving it, a second signal — waits until every line queued before it is written, within one second (CONSOLE_FLUSH_TIMEOUT, the last step of the way down); past it the rest is lost, and one line on stderr says so. A hard kill loses what was queued, as it would with any writer.

A process that does not run on #[nest_rs::main] — a test binary — writes stdout directly, so a failing test keeps its last lines. A deployment that needs every line ships them through the OTel logs bridge, which the queue does not touch. A line your code prints itself with println! skips the queue, so it can appear before log lines filed earlier.

The OpenTelemetryTracingBridge is wired in only when an OTLP endpoint is configured. Without an endpoint, the bridge is skipped — it pays a small per-event cost just to drop the event, which is not worth paying when console-only logging is the goal. When the endpoint is set, every tracing event becomes an OTel log record with the same target, level, fields and trace_id.

  • Traces — the spans logs correlate against.
  • Metrics — the aggregate counterpart to logs.
  • OpenTelemetry — the appender and OTLP export.