1//! Utilities for implementing and composing [`tracing`] subscribers.
2//!
3//! [`tracing`] is a framework for instrumenting Rust programs to collect
4//! scoped, structured, and async-aware diagnostics. The [`Subscriber`] trait
5//! represents the functionality necessary to collect this trace data. This
6//! crate contains tools for composing subscribers out of smaller units of
7//! behaviour, and batteries-included implementations of common subscriber
8//! functionality.
9//!
10//! `tracing-subscriber` is intended for use by both `Subscriber` authors and
11//! application authors using `tracing` to instrument their applications.
12//!
13//! *Compiler support: [requires `rustc` 1.63+][msrv]*
14//!
15//! [msrv]: #supported-rust-versions
16//!
17//! ## `Layer`s and `Filter`s
18//!
19//! The most important component of the `tracing-subscriber` API is the
20//! [`Layer`] trait, which provides a composable abstraction for building
21//! [`Subscriber`]s. Like the [`Subscriber`] trait, a [`Layer`] defines a
22//! particular behavior for collecting trace data. Unlike [`Subscriber`]s,
23//! which implement a *complete* strategy for how trace data is collected,
24//! [`Layer`]s provide *modular* implementations of specific behaviors.
25//! Therefore, they can be [composed together] to form a [`Subscriber`] which is
26//! capable of recording traces in a variety of ways. See the [`layer` module's
27//! documentation][layer] for details on using [`Layer`]s.
28//!
29//! In addition, the [`Filter`] trait defines an interface for filtering what
30//! spans and events are recorded by a particular layer. This allows different
31//! [`Layer`]s to handle separate subsets of the trace data emitted by a
32//! program. See the [documentation on per-layer filtering][plf] for more
33//! information on using [`Filter`]s.
34//!
35//! [`Layer`]: crate::layer::Layer
36//! [composed together]: crate::layer#composing-layers
37//! [layer]: crate::layer
38//! [`Filter`]: crate::layer::Filter
39//! [plf]: crate::layer#per-layer-filtering
40//!
41//! ## Included Subscribers
42//!
43//! The following `Subscriber`s are provided for application authors:
44//!
45//! - [`fmt`] - Formats and logs tracing data (requires the `fmt` feature flag)
46//!
47//! ## Feature Flags
48//!
49//! - `std`: Enables APIs that depend on the Rust standard library
50//! (enabled by default).
51//! - `alloc`: Depend on [`liballoc`] (enabled by "std").
52//! - `env-filter`: Enables the [`EnvFilter`] type, which implements filtering
53//! similar to the [`env_logger` crate]. **Requires "std"**.
54//! - `fmt`: Enables the [`fmt`] module, which provides a subscriber
55//! implementation for printing formatted representations of trace events.
56//! Enabled by default. **Requires "registry" and "std"**.
57//! - `ansi`: Enables `fmt` support for ANSI terminal colors. Enabled by
58//! default.
59//! - `registry`: enables the [`registry`] module. Enabled by default.
60//! **Requires "std"**.
61//! - `json`: Enables `fmt` support for JSON output. In JSON output, the ANSI
62//! feature does nothing. **Requires "fmt" and "std"**.
63//! - `local-time`: Enables local time formatting when using the [`time`
64//! crate]'s timestamp formatters with the `fmt` subscriber.
65//!
66//! [`registry`]: mod@registry
67//!
68//! ### Optional Dependencies
69//!
70//! - [`tracing-log`]: Enables better formatting for events emitted by `log`
71//! macros in the `fmt` subscriber. Enabled by default.
72//! - [`time`][`time` crate]: Enables support for using the [`time` crate] for timestamp
73//! formatting in the `fmt` subscriber.
74//! - [`smallvec`]: Causes the `EnvFilter` type to use the `smallvec` crate (rather
75//! than `Vec`) as a performance optimization. Enabled by default.
76//! - [`parking_lot`]: Use the `parking_lot` crate's `RwLock` implementation
77//! rather than the Rust standard library's implementation.
78//!
79//! ### `no_std` Support
80//!
81//! In embedded systems and other bare-metal applications, `tracing` can be
82//! used without requiring the Rust standard library, although some features are
83//! disabled. Although most of the APIs provided by `tracing-subscriber`, such
84//! as [`fmt`] and [`EnvFilter`], require the standard library, some
85//! functionality, such as the [`Layer`] trait, can still be used in
86//! `no_std` environments.
87//!
88//! The dependency on the standard library is controlled by two crate feature
89//! flags, "std", which enables the dependency on [`libstd`], and "alloc", which
90//! enables the dependency on [`liballoc`] (and is enabled by the "std"
91//! feature). These features are enabled by default, but `no_std` users can
92//! disable them using:
93//!
94//! ```toml
95//! # Cargo.toml
96//! tracing-subscriber = { version = "0.3", default-features = false }
97//! ```
98//!
99//! Additional APIs are available when [`liballoc`] is available. To enable
100//! `liballoc` but not `std`, use:
101//!
102//! ```toml
103//! # Cargo.toml
104//! tracing-subscriber = { version = "0.3", default-features = false, features = ["alloc"] }
105//! ```
106//!
107//! ### Unstable Features
108//!
109//! These feature flags enable **unstable** features. The public API may break in 0.1.x
110//! releases. To enable these features, the `--cfg tracing_unstable` must be passed to
111//! `rustc` when compiling.
112//!
113//! The following unstable feature flags are currently available:
114//!
115//! * `valuable`: Enables support for serializing values recorded using the
116//! [`valuable`] crate as structured JSON in the [`format::Json`] formatter.
117//!
118//! #### Enabling Unstable Features
119//!
120//! The easiest way to set the `tracing_unstable` cfg is to use the `RUSTFLAGS`
121//! env variable when running `cargo` commands:
122//!
123//! ```shell
124//! RUSTFLAGS="--cfg tracing_unstable" cargo build
125//! ```
126//! Alternatively, the following can be added to the `.cargo/config` file in a
127//! project to automatically enable the cfg flag for that project:
128//!
129//! ```toml
130//! [build]
131//! rustflags = ["--cfg", "tracing_unstable"]
132//! ```
133//!
134//! [feature flags]: https://doc.rust-lang.org/cargo/reference/manifest.html#the-features-section
135//! [`valuable`]: https://crates.io/crates/valuable
136//! [`format::Json`]: crate::fmt::format::Json
137//!
138//! ## Supported Rust Versions
139//!
140//! Tracing is built against the latest stable release. The minimum supported
141//! version is 1.63. The current Tracing version is not guaranteed to build on
142//! Rust versions earlier than the minimum supported version.
143//!
144//! Tracing follows the same compiler support policies as the rest of the Tokio
145//! project. The current stable Rust compiler and the three most recent minor
146//! versions before it will always be supported. For example, if the current
147//! stable compiler version is 1.69, the minimum supported version will not be
148//! increased past 1.66, three minor versions prior. Increasing the minimum
149//! supported compiler version is not considered a semver breaking change as
150//! long as doing so complies with this policy.
151//!
152//! [`Subscriber`]: tracing_core::subscriber::Subscriber
153//! [`tracing`]: https://docs.rs/tracing/latest/tracing
154//! [`EnvFilter`]: filter::EnvFilter
155//! [`fmt`]: mod@fmt
156//! [`tracing-log`]: https://crates.io/crates/tracing-log
157//! [`smallvec`]: https://crates.io/crates/smallvec
158//! [`env_logger` crate]: https://crates.io/crates/env_logger
159//! [`parking_lot`]: https://crates.io/crates/parking_lot
160//! [`time` crate]: https://crates.io/crates/time
161//! [`liballoc`]: https://doc.rust-lang.org/alloc/index.html
162//! [`libstd`]: https://doc.rust-lang.org/std/index.html
163#![doc(
164 html_logo_url = "https://raw.githubusercontent.com/tokio-rs/tracing/master/assets/logo-type.png",
165 issue_tracker_base_url = "https://github.com/tokio-rs/tracing/issues/"
166)]
167#![cfg_attr(
168 docsrs,
169 // Allows displaying cfgs/feature flags in the documentation.
170 feature(doc_cfg),
171 // Allows adding traits to RustDoc's list of "notable traits"
172 feature(doc_notable_trait),
173 // Fail the docs build if any intra-docs links are broken
174 deny(rustdoc::broken_intra_doc_links),
175)]
176#![warn(
177 missing_debug_implementations,
178 missing_docs,
179 rust_2018_idioms,
180 unreachable_pub,
181 bad_style,
182 dead_code,
183 improper_ctypes,
184 non_shorthand_field_patterns,
185 no_mangle_generic_items,
186 overflowing_literals,
187 path_statements,
188 patterns_in_fns_without_body,
189 private_in_public,
190 unconditional_recursion,
191 unused,
192 unused_allocation,
193 unused_comparisons,
194 unused_parens,
195 while_true
196)]
197// Using struct update syntax when a struct has no additional fields avoids
198// a potential source change if additional fields are added to the struct in the
199// future, reducing diff noise. Allow this even though clippy considers it
200// "needless".
201#![allow(clippy::needless_update)]
202#![cfg_attr(not(feature = "std"), no_std)]
203
204#[cfg(feature = "alloc")]
205extern crate alloc;
206
207#[macro_use]
208mod macros;
209
210pub mod field;
211pub mod filter;
212pub mod prelude;
213pub mod registry;
214
215pub mod layer;
216pub mod util;
217
218feature! {
219 #![feature = "std"]
220 pub mod reload;
221 pub(crate) mod sync;
222}
223
224feature! {
225 #![all(feature = "fmt", feature = "std")]
226 pub mod fmt;
227 pub use fmt::fmt;
228 pub use fmt::Subscriber as FmtSubscriber;
229}
230
231feature! {
232 #![all(feature = "env-filter", feature = "std")]
233 pub use filter::EnvFilter;
234}
235
236pub use layer::Layer;
237
238feature! {
239 #![all(feature = "registry", feature = "std")]
240 pub use registry::Registry;
241
242 ///
243 pub fn registry() -> Registry {
244 Registry::default()
245 }
246}
247
248mod sealed {
249 pub trait Sealed<A = ()> {}
250}
251