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")]
205 extern crate alloc;
206 
207 #[macro_use]
208 mod macros;
209 
210 pub mod field;
211 pub mod filter;
212 pub mod prelude;
213 pub mod registry;
214 
215 pub mod layer;
216 pub mod util;
217 
218 feature! {
219     #![feature = "std"]
220     pub mod reload;
221     pub(crate) mod sync;
222 }
223 
224 feature! {
225     #![all(feature = "fmt", feature = "std")]
226     pub mod fmt;
227     pub use fmt::fmt;
228     pub use fmt::Subscriber as FmtSubscriber;
229 }
230 
231 feature! {
232     #![all(feature = "env-filter", feature = "std")]
233     pub use filter::EnvFilter;
234 }
235 
236 pub use layer::Layer;
237 
238 feature! {
239     #![all(feature = "registry", feature = "std")]
240     pub use registry::Registry;
241 
242     ///
243     pub fn registry() -> Registry {
244         Registry::default()
245     }
246 }
247 
248 mod sealed {
249     pub trait Sealed<A = ()> {}
250 }
251