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