1 //! Core primitives for `tracing`. 2 //! 3 //! [`tracing`] is a framework for instrumenting Rust programs to collect 4 //! structured, event-based diagnostic information. This crate defines the core 5 //! primitives of `tracing`. 6 //! 7 //! This crate provides: 8 //! 9 //! * [`span::Id`] identifies a span within the execution of a program. 10 //! 11 //! * [`Event`] represents a single event within a trace. 12 //! 13 //! * [`Subscriber`], the trait implemented to collect trace data. 14 //! 15 //! * [`Metadata`] and [`Callsite`] provide information describing spans and 16 //! `Event`s. 17 //! 18 //! * [`Field`], [`FieldSet`], [`Value`], and [`ValueSet`] represent the 19 //! structured data attached to a span. 20 //! 21 //! * [`Dispatch`] allows spans and events to be dispatched to `Subscriber`s. 22 //! 23 //! In addition, it defines the global callsite registry and per-thread current 24 //! dispatcher which other components of the tracing system rely on. 25 //! 26 //! *Compiler support: [requires `rustc` 1.63+][msrv]* 27 //! 28 //! [msrv]: #supported-rust-versions 29 //! 30 //! ## Usage 31 //! 32 //! Application authors will typically not use this crate directly. Instead, 33 //! they will use the [`tracing`] crate, which provides a much more 34 //! fully-featured API. However, this crate's API will change very infrequently, 35 //! so it may be used when dependencies must be very stable. 36 //! 37 //! `Subscriber` implementations may depend on `tracing-core` rather than 38 //! `tracing`, as the additional APIs provided by `tracing` are primarily useful 39 //! for instrumenting libraries and applications, and are generally not 40 //! necessary for `Subscriber` implementations. 41 //! 42 //! The [`tokio-rs/tracing`] repository contains less stable crates designed to 43 //! be used with the `tracing` ecosystem. It includes a collection of 44 //! `Subscriber` implementations, as well as utility and adapter crates. 45 //! 46 //! ## Crate Feature Flags 47 //! 48 //! The following crate [feature flags] are available: 49 //! 50 //! * `std`: Depend on the Rust standard library (enabled by default). 51 //! 52 //! `no_std` users may disable this feature with `default-features = false`: 53 //! 54 //! ```toml 55 //! [dependencies] 56 //! tracing-core = { version = "0.1.22", default-features = false } 57 //! ``` 58 //! 59 //! **Note**:`tracing-core`'s `no_std` support requires `liballoc`. 60 //! 61 //! ### Unstable Features 62 //! 63 //! These feature flags enable **unstable** features. The public API may break in 0.1.x 64 //! releases. To enable these features, the `--cfg tracing_unstable` must be passed to 65 //! `rustc` when compiling. 66 //! 67 //! The following unstable feature flags are currently available: 68 //! 69 //! * `valuable`: Enables support for recording [field values] using the 70 //! [`valuable`] crate. 71 //! 72 //! #### Enabling Unstable Features 73 //! 74 //! The easiest way to set the `tracing_unstable` cfg is to use the `RUSTFLAGS` 75 //! env variable when running `cargo` commands: 76 //! 77 //! ```shell 78 //! RUSTFLAGS="--cfg tracing_unstable" cargo build 79 //! ``` 80 //! Alternatively, the following can be added to the `.cargo/config` file in a 81 //! project to automatically enable the cfg flag for that project: 82 //! 83 //! ```toml 84 //! [build] 85 //! rustflags = ["--cfg", "tracing_unstable"] 86 //! ``` 87 //! 88 //! [feature flags]: https://doc.rust-lang.org/cargo/reference/manifest.html#the-features-section 89 //! [field values]: crate::field 90 //! [`valuable`]: https://crates.io/crates/valuable 91 //! 92 //! ## Supported Rust Versions 93 //! 94 //! Tracing is built against the latest stable release. The minimum supported 95 //! version is 1.63. The current Tracing version is not guaranteed to build on 96 //! Rust versions earlier than the minimum supported version. 97 //! 98 //! Tracing follows the same compiler support policies as the rest of the Tokio 99 //! project. The current stable Rust compiler and the three most recent minor 100 //! versions before it will always be supported. For example, if the current 101 //! stable compiler version is 1.69, the minimum supported version will not be 102 //! increased past 1.66, three minor versions prior. Increasing the minimum 103 //! supported compiler version is not considered a semver breaking change as 104 //! long as doing so complies with this policy. 105 //! 106 //! 107 //! [`span::Id`]: span::Id 108 //! [`Event`]: event::Event 109 //! [`Subscriber`]: subscriber::Subscriber 110 //! [`Metadata`]: metadata::Metadata 111 //! [`Callsite`]: callsite::Callsite 112 //! [`Field`]: field::Field 113 //! [`FieldSet`]: field::FieldSet 114 //! [`Value`]: field::Value 115 //! [`ValueSet`]: field::ValueSet 116 //! [`Dispatch`]: dispatcher::Dispatch 117 //! [`tokio-rs/tracing`]: https://github.com/tokio-rs/tracing 118 //! [`tracing`]: https://crates.io/crates/tracing 119 #![doc( 120 html_logo_url = "https://raw.githubusercontent.com/tokio-rs/tracing/master/assets/logo-type.png", 121 issue_tracker_base_url = "https://github.com/tokio-rs/tracing/issues/" 122 )] 123 #![cfg_attr(not(feature = "std"), no_std)] 124 #![cfg_attr(docsrs, feature(doc_cfg), deny(rustdoc::broken_intra_doc_links))] 125 #![warn( 126 missing_debug_implementations, 127 missing_docs, 128 rust_2018_idioms, 129 unreachable_pub, 130 bad_style, 131 dead_code, 132 improper_ctypes, 133 non_shorthand_field_patterns, 134 no_mangle_generic_items, 135 overflowing_literals, 136 path_statements, 137 patterns_in_fns_without_body, 138 private_interfaces, 139 private_bounds, 140 unconditional_recursion, 141 unused, 142 unused_allocation, 143 unused_comparisons, 144 unused_parens, 145 while_true 146 )] 147 #[cfg(not(feature = "std"))] 148 extern crate alloc; 149 150 #[doc(hidden)] 151 pub mod __macro_support { 152 // Re-export the `core` functions that are used in macros. This allows 153 // a crate to be named `core` and avoid name clashes. 154 // See here: https://github.com/tokio-rs/tracing/issues/2761 155 pub use core::{file, line, module_path, option::Option}; 156 } 157 158 /// Statically constructs an [`Identifier`] for the provided [`Callsite`]. 159 /// 160 /// This may be used in contexts such as static initializers. 161 /// 162 /// For example: 163 /// ```rust 164 /// use tracing_core::{callsite, identify_callsite}; 165 /// # use tracing_core::{Metadata, subscriber::Interest}; 166 /// # fn main() { 167 /// pub struct MyCallsite { 168 /// // ... 169 /// } 170 /// impl callsite::Callsite for MyCallsite { 171 /// # fn set_interest(&self, _: Interest) { unimplemented!() } 172 /// # fn metadata(&self) -> &Metadata { unimplemented!() } 173 /// // ... 174 /// } 175 /// 176 /// static CALLSITE: MyCallsite = MyCallsite { 177 /// // ... 178 /// }; 179 /// 180 /// static CALLSITE_ID: callsite::Identifier = identify_callsite!(&CALLSITE); 181 /// # } 182 /// ``` 183 /// 184 /// [`Identifier`]: callsite::Identifier 185 /// [`Callsite`]: callsite::Callsite 186 #[macro_export] 187 macro_rules! identify_callsite { 188 ($callsite:expr) => { 189 $crate::callsite::Identifier($callsite) 190 }; 191 } 192 193 /// Statically constructs new span [metadata]. 194 /// 195 /// /// For example: 196 /// ```rust 197 /// # use tracing_core::{callsite::Callsite, subscriber::Interest}; 198 /// use tracing_core::metadata; 199 /// use tracing_core::metadata::{Kind, Level, Metadata}; 200 /// # fn main() { 201 /// # pub struct MyCallsite { } 202 /// # impl Callsite for MyCallsite { 203 /// # fn set_interest(&self, _: Interest) { unimplemented!() } 204 /// # fn metadata(&self) -> &Metadata { unimplemented!() } 205 /// # } 206 /// # 207 /// static FOO_CALLSITE: MyCallsite = MyCallsite { 208 /// // ... 209 /// }; 210 /// 211 /// static FOO_METADATA: Metadata = metadata!{ 212 /// name: "foo", 213 /// target: module_path!(), 214 /// level: Level::DEBUG, 215 /// fields: &["bar", "baz"], 216 /// callsite: &FOO_CALLSITE, 217 /// kind: Kind::SPAN, 218 /// }; 219 /// # } 220 /// ``` 221 /// 222 /// [metadata]: metadata::Metadata 223 /// [`Metadata::new`]: metadata::Metadata::new 224 #[macro_export] 225 macro_rules! metadata { 226 ( 227 name: $name:expr, 228 target: $target:expr, 229 level: $level:expr, 230 fields: $fields:expr, 231 callsite: $callsite:expr, 232 kind: $kind:expr 233 ) => { 234 $crate::metadata! { 235 name: $name, 236 target: $target, 237 level: $level, 238 fields: $fields, 239 callsite: $callsite, 240 kind: $kind, 241 } 242 }; 243 ( 244 name: $name:expr, 245 target: $target:expr, 246 level: $level:expr, 247 fields: $fields:expr, 248 callsite: $callsite:expr, 249 kind: $kind:expr, 250 ) => { 251 $crate::metadata::Metadata::new( 252 $name, 253 $target, 254 $level, 255 $crate::__macro_support::Option::Some($crate::__macro_support::file!()), 256 $crate::__macro_support::Option::Some($crate::__macro_support::line!()), 257 $crate::__macro_support::Option::Some($crate::__macro_support::module_path!()), 258 $crate::field::FieldSet::new($fields, $crate::identify_callsite!($callsite)), 259 $kind, 260 ) 261 }; 262 } 263 264 pub(crate) mod lazy; 265 266 // Trimmed-down vendored version of spin 0.5.2 (0387621) 267 // Dependency of no_std lazy_static, not required in a std build 268 #[cfg(not(feature = "std"))] 269 pub(crate) mod spin; 270 271 #[cfg(not(feature = "std"))] 272 #[doc(hidden)] 273 pub type Once = self::spin::Once<()>; 274 275 #[cfg(feature = "std")] 276 pub use stdlib::sync::Once; 277 278 pub mod callsite; 279 pub mod dispatcher; 280 pub mod event; 281 pub mod field; 282 pub mod metadata; 283 mod parent; 284 pub mod span; 285 pub(crate) mod stdlib; 286 pub mod subscriber; 287 288 #[doc(inline)] 289 pub use self::{ 290 callsite::Callsite, 291 dispatcher::Dispatch, 292 event::Event, 293 field::Field, 294 metadata::{Level, LevelFilter, Metadata}, 295 subscriber::Subscriber, 296 }; 297 298 pub use self::{metadata::Kind, subscriber::Interest}; 299 300 mod sealed { 301 pub trait Sealed {} 302 } 303
