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.49+][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.49. 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.45, the minimum supported version will not be |
102 | //! increased past 1.42, 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 (html_root_url = "https://docs.rs/tracing-core/0.1.22" )] |
120 | #![doc ( |
121 | html_logo_url = "https://raw.githubusercontent.com/tokio-rs/tracing/master/assets/logo-type.png" , |
122 | issue_tracker_base_url = "https://github.com/tokio-rs/tracing/issues/" |
123 | )] |
124 | #![cfg_attr (not(feature = "std" ), no_std)] |
125 | #![cfg_attr (docsrs, feature(doc_cfg), deny(rustdoc::broken_intra_doc_links))] |
126 | #![warn ( |
127 | missing_debug_implementations, |
128 | missing_docs, |
129 | rust_2018_idioms, |
130 | unreachable_pub, |
131 | bad_style, |
132 | const_err, |
133 | dead_code, |
134 | improper_ctypes, |
135 | non_shorthand_field_patterns, |
136 | no_mangle_generic_items, |
137 | overflowing_literals, |
138 | path_statements, |
139 | patterns_in_fns_without_body, |
140 | private_in_public, |
141 | unconditional_recursion, |
142 | unused, |
143 | unused_allocation, |
144 | unused_comparisons, |
145 | unused_parens, |
146 | while_true |
147 | )] |
148 | #[cfg (not(feature = "std" ))] |
149 | extern crate alloc; |
150 | |
151 | /// Statically constructs an [`Identifier`] for the provided [`Callsite`]. |
152 | /// |
153 | /// This may be used in contexts such as static initializers. |
154 | /// |
155 | /// For example: |
156 | /// ```rust |
157 | /// use tracing_core::{callsite, identify_callsite}; |
158 | /// # use tracing_core::{Metadata, subscriber::Interest}; |
159 | /// # fn main() { |
160 | /// pub struct MyCallsite { |
161 | /// // ... |
162 | /// } |
163 | /// impl callsite::Callsite for MyCallsite { |
164 | /// # fn set_interest(&self, _: Interest) { unimplemented!() } |
165 | /// # fn metadata(&self) -> &Metadata { unimplemented!() } |
166 | /// // ... |
167 | /// } |
168 | /// |
169 | /// static CALLSITE: MyCallsite = MyCallsite { |
170 | /// // ... |
171 | /// }; |
172 | /// |
173 | /// static CALLSITE_ID: callsite::Identifier = identify_callsite!(&CALLSITE); |
174 | /// # } |
175 | /// ``` |
176 | /// |
177 | /// [`Identifier`]: callsite::Identifier |
178 | /// [`Callsite`]: callsite::Callsite |
179 | #[macro_export ] |
180 | macro_rules! identify_callsite { |
181 | ($callsite:expr) => { |
182 | $crate::callsite::Identifier($callsite) |
183 | }; |
184 | } |
185 | |
186 | /// Statically constructs new span [metadata]. |
187 | /// |
188 | /// /// For example: |
189 | /// ```rust |
190 | /// # use tracing_core::{callsite::Callsite, subscriber::Interest}; |
191 | /// use tracing_core::metadata; |
192 | /// use tracing_core::metadata::{Kind, Level, Metadata}; |
193 | /// # fn main() { |
194 | /// # pub struct MyCallsite { } |
195 | /// # impl Callsite for MyCallsite { |
196 | /// # fn set_interest(&self, _: Interest) { unimplemented!() } |
197 | /// # fn metadata(&self) -> &Metadata { unimplemented!() } |
198 | /// # } |
199 | /// # |
200 | /// static FOO_CALLSITE: MyCallsite = MyCallsite { |
201 | /// // ... |
202 | /// }; |
203 | /// |
204 | /// static FOO_METADATA: Metadata = metadata!{ |
205 | /// name: "foo" , |
206 | /// target: module_path!(), |
207 | /// level: Level::DEBUG, |
208 | /// fields: &["bar" , "baz" ], |
209 | /// callsite: &FOO_CALLSITE, |
210 | /// kind: Kind::SPAN, |
211 | /// }; |
212 | /// # } |
213 | /// ``` |
214 | /// |
215 | /// [metadata]: metadata::Metadata |
216 | /// [`Metadata::new`]: metadata::Metadata::new |
217 | #[macro_export ] |
218 | macro_rules! metadata { |
219 | ( |
220 | name: $name:expr, |
221 | target: $target:expr, |
222 | level: $level:expr, |
223 | fields: $fields:expr, |
224 | callsite: $callsite:expr, |
225 | kind: $kind:expr |
226 | ) => { |
227 | $crate::metadata! { |
228 | name: $name, |
229 | target: $target, |
230 | level: $level, |
231 | fields: $fields, |
232 | callsite: $callsite, |
233 | kind: $kind, |
234 | } |
235 | }; |
236 | ( |
237 | name: $name:expr, |
238 | target: $target:expr, |
239 | level: $level:expr, |
240 | fields: $fields:expr, |
241 | callsite: $callsite:expr, |
242 | kind: $kind:expr, |
243 | ) => { |
244 | $crate::metadata::Metadata::new( |
245 | $name, |
246 | $target, |
247 | $level, |
248 | Some(file!()), |
249 | Some(line!()), |
250 | Some(module_path!()), |
251 | $crate::field::FieldSet::new($fields, $crate::identify_callsite!($callsite)), |
252 | $kind, |
253 | ) |
254 | }; |
255 | } |
256 | |
257 | pub(crate) mod lazy; |
258 | |
259 | // Trimmed-down vendored version of spin 0.5.2 (0387621) |
260 | // Dependency of no_std lazy_static, not required in a std build |
261 | #[cfg (not(feature = "std" ))] |
262 | pub(crate) mod spin; |
263 | |
264 | #[cfg (not(feature = "std" ))] |
265 | #[doc (hidden)] |
266 | pub type Once = self::spin::Once<()>; |
267 | |
268 | #[cfg (feature = "std" )] |
269 | pub use stdlib::sync::Once; |
270 | |
271 | pub mod callsite; |
272 | pub mod dispatcher; |
273 | pub mod event; |
274 | pub mod field; |
275 | pub mod metadata; |
276 | mod parent; |
277 | pub mod span; |
278 | pub(crate) mod stdlib; |
279 | pub mod subscriber; |
280 | |
281 | #[doc (inline)] |
282 | pub use self::{ |
283 | callsite::Callsite, |
284 | dispatcher::Dispatch, |
285 | event::Event, |
286 | field::Field, |
287 | metadata::{Level, LevelFilter, Metadata}, |
288 | subscriber::Subscriber, |
289 | }; |
290 | |
291 | pub use self::{metadata::Kind, subscriber::Interest}; |
292 | |
293 | mod sealed { |
294 | pub trait Sealed {} |
295 | } |
296 | |