axum-impl-tracing

name	axum-impl-tracing
description	Use when adding structured logging or request tracing to an Axum service, when wiring a tracing-subscriber, when instrumenting handlers, when log timings look interleaved or spans nest under the wrong parent, or when exporting spans to an OpenTelemetry backend. Prevents holding a Span::enter guard across an await point, calling init twice, missing the SubscriberExt and SubscriberInitExt imports, spanning on the raw URI instead of MatchedPath, recording a span field that was never declared, and interpolating values into the log message with format. Covers tracing-subscriber registry and EnvFilter and fmt::layer, the tower-http TraceLayer::new_for_http middleware and its six hooks, the tracing event macros, the instrument attribute, the Debug and Display field sigils, the span-guard-across-await rule, and OpenTelemetry export. Keywords: tracing, tracing-subscriber, registry, EnvFilter, RUST_LOG, fmt layer, TraceLayer, new_for_http, make_span_with, on_response, on_failure, info macro, error macro, instrument, Span enter, Instrument, MatchedPath, opentelemetry, otlp, traceparent, logs are interleaved, traces look wrong, timings are wrong, with does not resolve, no logs appear, panic on second init, how do I add logging to axum, what is structured logging.
license	MIT
compatibility	Designed for Claude Code. Requires Axum 0.7,0.8.
metadata	{"author":"OpenAEC-Foundation","version":"1.0"}

Axum Tracing and Structured Logging

Overview

Observability in an Axum service rests on two crates. tracing is the instrumentation facade: handler code and middleware emit events and create spans through it, with no knowledge of where the data goes. tracing-subscriber is the collector: it receives that data and decides what to filter, format, and export. The application wires them together exactly once, in main, before the server starts.

A subscriber is built compositionally: a Registry for span storage plus one or more Layers, each adding one behavior (filtering, console formatting, OTLP export). The tracing and tracing-subscriber APIs in this skill are identical for Axum 0.7 and 0.8; the version difference in Axum does not reach this layer.

Three rules dominate correct tracing code:

1. Install the subscriber exactly once in main, before axum::serve. NEVER call .init() a second time.
2. NEVER hold the drop guard from Span::enter() across an .await. Use #[instrument] or Future::instrument for async code.
3. Emit structured key = value fields. NEVER interpolate values into the message string with format!.

Quick Reference

Need	API	Notes
Build the subscriber	tracing_subscriber::registry()	needs registry feature
Compose a layer	.with(layer)	from SubscriberExt, import required
Install globally	.init()	from SubscriberInitExt, call once
Filter by RUST_LOG	EnvFilter::try_from_default_env()	returns Result, falls back
Console output	tracing_subscriber::fmt::layer()	human-readable formatting
Instrument every request