]>
Commit | Line | Data |
---|---|---|
f035d41b XL |
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 | //! | |
ee023bcb | 26 | //! *Compiler support: [requires `rustc` 1.49+][msrv]* |
1b1a35ee XL |
27 | //! |
28 | //! [msrv]: #supported-rust-versions | |
29 | //! | |
f035d41b XL |
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 | //! | |
5099ac24 | 46 | //! ## Crate Feature Flags |
f035d41b | 47 | //! |
5099ac24 | 48 | //! The following crate [feature flags] are available: |
f035d41b XL |
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] | |
5099ac24 | 56 | //! tracing-core = { version = "0.1.22", default-features = false } |
f035d41b XL |
57 | //! ``` |
58 | //! | |
f035d41b XL |
59 | //! **Note**:`tracing-core`'s `no_std` support requires `liballoc`. |
60 | //! | |
5099ac24 FG |
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 | //! | |
1b1a35ee XL |
92 | //! ## Supported Rust Versions |
93 | //! | |
94 | //! Tracing is built against the latest stable release. The minimum supported | |
ee023bcb | 95 | //! version is 1.49. The current Tracing version is not guaranteed to build on |
1b1a35ee XL |
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 | //! | |
f035d41b XL |
107 | //! [`span::Id`]: span/struct.Id.html |
108 | //! [`Event`]: event/struct.Event.html | |
109 | //! [`Subscriber`]: subscriber/trait.Subscriber.html | |
110 | //! [`Metadata`]: metadata/struct.Metadata.html | |
111 | //! [`Callsite`]: callsite/trait.Callsite.html | |
112 | //! [`Field`]: field/struct.Field.html | |
113 | //! [`FieldSet`]: field/struct.FieldSet.html | |
114 | //! [`Value`]: field/trait.Value.html | |
115 | //! [`ValueSet`]: field/struct.ValueSet.html | |
116 | //! [`Dispatch`]: dispatcher/struct.Dispatch.html | |
117 | //! [`tokio-rs/tracing`]: https://github.com/tokio-rs/tracing | |
118 | //! [`tracing`]: https://crates.io/crates/tracing | |
5099ac24 | 119 | #![doc(html_root_url = "https://docs.rs/tracing-core/0.1.22")] |
3dfed10e | 120 | #![doc( |
1b1a35ee | 121 | html_logo_url = "https://raw.githubusercontent.com/tokio-rs/tracing/master/assets/logo-type.png", |
3dfed10e XL |
122 | issue_tracker_base_url = "https://github.com/tokio-rs/tracing/issues/" |
123 | )] | |
f035d41b | 124 | #![cfg_attr(not(feature = "std"), no_std)] |
c295e0f8 | 125 | #![cfg_attr(docsrs, feature(doc_cfg), deny(rustdoc::broken_intra_doc_links))] |
f035d41b XL |
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, where the | |
154 | /// [`Callsite::id`] function is not currently usable. | |
155 | /// | |
156 | /// For example: | |
157 | /// ```rust | |
5099ac24 | 158 | /// use tracing_core::{callsite, identify_callsite}; |
f035d41b XL |
159 | /// # use tracing_core::{Metadata, subscriber::Interest}; |
160 | /// # fn main() { | |
161 | /// pub struct MyCallsite { | |
162 | /// // ... | |
163 | /// } | |
164 | /// impl callsite::Callsite for MyCallsite { | |
165 | /// # fn set_interest(&self, _: Interest) { unimplemented!() } | |
166 | /// # fn metadata(&self) -> &Metadata { unimplemented!() } | |
167 | /// // ... | |
168 | /// } | |
169 | /// | |
170 | /// static CALLSITE: MyCallsite = MyCallsite { | |
171 | /// // ... | |
172 | /// }; | |
173 | /// | |
174 | /// static CALLSITE_ID: callsite::Identifier = identify_callsite!(&CALLSITE); | |
175 | /// # } | |
176 | /// ``` | |
177 | /// | |
178 | /// [`Identifier`]: callsite/struct.Identifier.html | |
179 | /// [`Callsite`]: callsite/trait.Callsite.html | |
180 | /// [`Callsite::id`]: callsite/trait.Callsite.html#method.id | |
181 | #[macro_export] | |
182 | macro_rules! identify_callsite { | |
183 | ($callsite:expr) => { | |
184 | $crate::callsite::Identifier($callsite) | |
185 | }; | |
186 | } | |
187 | ||
188 | /// Statically constructs new span [metadata]. | |
189 | /// | |
190 | /// /// For example: | |
191 | /// ```rust | |
f035d41b | 192 | /// # use tracing_core::{callsite::Callsite, subscriber::Interest}; |
5099ac24 | 193 | /// use tracing_core::metadata; |
f035d41b XL |
194 | /// use tracing_core::metadata::{Kind, Level, Metadata}; |
195 | /// # fn main() { | |
196 | /// # pub struct MyCallsite { } | |
197 | /// # impl Callsite for MyCallsite { | |
198 | /// # fn set_interest(&self, _: Interest) { unimplemented!() } | |
199 | /// # fn metadata(&self) -> &Metadata { unimplemented!() } | |
200 | /// # } | |
201 | /// # | |
202 | /// static FOO_CALLSITE: MyCallsite = MyCallsite { | |
203 | /// // ... | |
204 | /// }; | |
205 | /// | |
206 | /// static FOO_METADATA: Metadata = metadata!{ | |
207 | /// name: "foo", | |
208 | /// target: module_path!(), | |
209 | /// level: Level::DEBUG, | |
210 | /// fields: &["bar", "baz"], | |
211 | /// callsite: &FOO_CALLSITE, | |
212 | /// kind: Kind::SPAN, | |
213 | /// }; | |
214 | /// # } | |
215 | /// ``` | |
216 | /// | |
217 | /// [metadata]: metadata/struct.Metadata.html | |
218 | /// [`Metadata::new`]: metadata/struct.Metadata.html#method.new | |
219 | #[macro_export] | |
220 | macro_rules! metadata { | |
221 | ( | |
222 | name: $name:expr, | |
223 | target: $target:expr, | |
224 | level: $level:expr, | |
225 | fields: $fields:expr, | |
226 | callsite: $callsite:expr, | |
227 | kind: $kind:expr | |
228 | ) => { | |
3dfed10e | 229 | $crate::metadata! { |
f035d41b XL |
230 | name: $name, |
231 | target: $target, | |
232 | level: $level, | |
233 | fields: $fields, | |
234 | callsite: $callsite, | |
235 | kind: $kind, | |
236 | } | |
237 | }; | |
238 | ( | |
239 | name: $name:expr, | |
240 | target: $target:expr, | |
241 | level: $level:expr, | |
242 | fields: $fields:expr, | |
243 | callsite: $callsite:expr, | |
244 | kind: $kind:expr, | |
245 | ) => { | |
246 | $crate::metadata::Metadata::new( | |
247 | $name, | |
248 | $target, | |
249 | $level, | |
250 | Some(file!()), | |
251 | Some(line!()), | |
252 | Some(module_path!()), | |
253 | $crate::field::FieldSet::new($fields, $crate::identify_callsite!($callsite)), | |
254 | $kind, | |
255 | ) | |
256 | }; | |
257 | } | |
258 | ||
5099ac24 | 259 | // when `std` is enabled, use the `lazy_static` crate from crates.io |
f035d41b | 260 | #[cfg(feature = "std")] |
5099ac24 | 261 | pub(crate) use lazy_static::lazy_static; |
f035d41b | 262 | |
5099ac24 | 263 | // Facade module: `no_std` uses spinlocks, `std` uses the mutexes in the standard library |
f035d41b XL |
264 | #[cfg(not(feature = "std"))] |
265 | #[macro_use] | |
266 | mod lazy_static; | |
267 | ||
268 | // Trimmed-down vendored version of spin 0.5.2 (0387621) | |
269 | // Dependency of no_std lazy_static, not required in a std build | |
270 | #[cfg(not(feature = "std"))] | |
271 | pub(crate) mod spin; | |
272 | ||
273 | #[cfg(not(feature = "std"))] | |
274 | #[doc(hidden)] | |
3dfed10e XL |
275 | pub type Once = self::spin::Once<()>; |
276 | ||
277 | #[cfg(feature = "std")] | |
278 | pub use stdlib::sync::Once; | |
f035d41b XL |
279 | |
280 | pub mod callsite; | |
281 | pub mod dispatcher; | |
282 | pub mod event; | |
283 | pub mod field; | |
284 | pub mod metadata; | |
285 | mod parent; | |
286 | pub mod span; | |
287 | pub(crate) mod stdlib; | |
288 | pub mod subscriber; | |
289 | ||
290 | #[doc(inline)] | |
291 | pub use self::{ | |
292 | callsite::Callsite, | |
293 | dispatcher::Dispatch, | |
294 | event::Event, | |
295 | field::Field, | |
3dfed10e | 296 | metadata::{Level, LevelFilter, Metadata}, |
f035d41b XL |
297 | subscriber::Subscriber, |
298 | }; | |
299 | ||
300 | pub use self::{metadata::Kind, subscriber::Interest}; | |
301 | ||
302 | mod sealed { | |
303 | pub trait Sealed {} | |
304 | } |