tracing

tracing is the de-facto structured diagnostics framework for the Rust ecosystem, maintained by the Tokio project though usable entirely without the Tokio runtime. It replaces flat, unstructured log lines with spans (periods of time) and events (moments in time) that carry typed key-value fields, so that async and multi-threaded programs can be understood causally instead of just chronologically.

The crate ships the macros and #[instrument] attribute applications use to emit trace data, while collection is delegated to a pluggable Subscriber implementation — most commonly provided by the companion tracing-subscriber crate — so instrumentation code never has to know or care how (or whether) its output is formatted, filtered, or exported.

What You Get

• The tracing crate’s span/event macros (span!, event!, info!, debug!, etc.) and the #[instrument] attribute for automatic function instrumentation
• A Subscriber trait (re-exported from tracing-core) that lets you plug in any collector — console formatting, JSON, OpenTelemetry export — without changing instrumentation code
• Compatibility layers (tracing-log) for capturing existing log-crate output, plus futures integration (tracing-futures, Instrument) for tracing spans across .await points
• A large family of companion crates maintained in the same workspace — tracing-subscriber, tracing-appender, tracing-error, tracing-journald, tracing-mock — covering formatting, file rotation, error context, systemd journal output, and testing

Common Use Cases

• Instrumenting async Tokio services so interleaved task execution can be traced by span context instead of untangled from flat log lines
• Adding structured, typed diagnostics to a library without forcing downstream consumers into a specific logging backend
• Exporting spans to OpenTelemetry-compatible backends (Jaeger, Honeycomb, Datadog) for distributed tracing in production
• Replacing ad hoc println!/log debugging with queryable, field-based structured logs

Under The Hood

Architecture — The project is a Cargo workspace that splits concerns across crates: tracing-core holds the no_std-compatible primitives (the Subscriber trait, Dispatch, span::Id, Metadata, and a global callsite registry), tracing layers the public macro API (span!, event!, level-named shorthands, and #[instrument] via the tracing-attributes proc-macro crate) on top, and separate crates (tracing-subscriber, tracing-appender, tracing-journald, tracing-error, tracing-log, tracing-futures) each own one concern instead of bloating the core. The central runtime abstraction is Dispatch — a cloneable, type-erased handle to whichever Subscriber is currently active (thread-local via with_default/set_default, or process-global via set_global_default) — which every span/event macro call routes through, with per-callsite interest caching so disabled instrumentation short-circuits cheaply.

Tech Stack — Pure Rust, 2018 edition, MSRV pinned to 1.65. Runtime dependencies are minimal by design: tracing-core (path dependency within the workspace), an optional log crate for bridging with log-based libraries, tracing-attributes (optional, gated behind the attributes feature) for the #[instrument] proc-macro, and pin-project-lite for the Instrumented future wrapper. The std feature is opt-out-able for no_std embedded/kernel use, and the crate is benchmarked with criterion and tested on wasm32 via wasm-bindgen-test.

Code Quality — The tracing/tests/ directory contains 15+ integration test files exercising subtle correctness edge cases around callsite/interest caching (filters_are_not_reevaluated_for_the_same_span.rs, multiple_max_level_hints.rs, filter_caching_is_lexically_scoped.rs), macro hygiene, and no-subscriber fallback behavior. A dedicated tracing-mock crate exists purely to give the workspace (and downstream users) a test-double Subscriber for asserting on span/event sequences. Module-level doc comments throughout lib.rs, span.rs, and dispatcher.rs embed runnable rustdoc doctests that double as both documentation and regression tests, and CI (.github/workflows/CI.yml, plus a separate audit.yml for dependency auditing) runs on every push.

API Design — The macro surface (info!, span!, #[instrument]) is deliberately modeled on the familiar log-crate macros to keep migration low-friction, and #[instrument] collapses “wrap this function in a span and record its arguments” into a single attribute line — the most common entry point in real-world code. The docs explicitly call out a well-known async footgun (holding a span guard across an .await point produces incorrect traces) rather than staying silent about it, which reflects real attention to developer experience. The Subscriber trait itself is kept intentionally minimal (seven methods) so third-party collector authors have a small surface to implement, while richer composability is pushed to the separate tracing-subscriber crate’s Layer trait rather than complicating the core.