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.56+][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 "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.56. 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 | |