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.
Default level per layer
Section titled “Default level per layer”| Concern | Target | Default level |
|---|---|---|
| Operation log — one line per unit of work, every edge | nest_rs::operation | info |
| HTTP span | nest_rs::http | info; the chain a 5xx answer withholds — any error’s, a framework error’s included — at error (warn behind a 503) |
| MCP operations | nest_rs::mcp | info |
| Route / endpoint mounting (boot) | nest_rs::routes | info |
| ORM queries | nest_rs::orm | trace |
Relation dataloaders (#[expose(…, graphql)] batches) | nest_rs::loader | debug |
| Layer composition (per-route guard/pipe/… chains) | nest_rs::layers | trace 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 denials | the 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 / Authz | nest_rs::authn / nest_rs::authz | info (denials warn) |
| OAuth client | nest_rs::oauth::client | info (callback refusals warn, a redirect no header can carry error) |
| OAuth authorization server (token endpoint) | nest_rs::oauth::server | warn 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 discovery | nest_rs::oauth::resource | info (boot misconfiguration warn) |
| WebSocket events | nest_rs::ws | info |
| GraphQL execution and subscriptions | nest_rs::graphql | info |
| Queue / Schedule | nest_rs::queue / nest_rs::schedule | info |
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::redis | warn per connect attempt while the boot budget runs |
| Module registration | nest_rs::module | info |
Lifecycle hooks (#[hooks]) | nest_rs::lifecycle | error 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 libraries the framework wires
Section titled “The libraries the framework wires”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.
| Library | Written from | Below that, it quotes |
|---|---|---|
rmcp | nothing (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) |
h2 | error | a PING’s opaque data (warn); a GOAWAY’s debug data (debug) |
rustls | error | a client’s SNI (warn); its whole ClientHello (trace) |
sqlx_postgres | error | a malformed .pgpass line, password included, and an unknown connection parameter’s value (warn) |
sea_orm | debug | its connect span’s whole connection options, the URL’s password included (trace): a span’s fields reach your exporter whatever the console prints |
tungstenite | info | a close frame’s reason (debug); every message (trace) |
opentelemetry-otlp | info | the 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.
Structured fields
Section titled “Structured fields”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.
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.
One line, one unit of work
Section titled “One line, one unit of work”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.
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:
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:
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.
Every unit of work files one line
Section titled “Every unit of work files one line”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.
Text vs JSON
Section titled “Text vs JSON”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:
NESTRS_LOG_FORMAT=textA 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.
Source location (file:line)
Section titled “Source location (file:line)”To trace a console line back to the exact source that emitted it, enable source location:
NESTRS_LOG_SOURCE_LOCATION=trueEach event then carries the emitting file:line:
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.
A console that stalls
Section titled “A console that stalls”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:
WARN nest_rs::app: log lines dropped while the console was stalled dropped=83617That 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.
OTel logs bridge
Section titled “OTel logs bridge”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.
Going further
Section titled “Going further”- Traces — the spans logs correlate against.
- Metrics — the aggregate counterpart to logs.
- OpenTelemetry — the appender and OTLP export.