]>
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 | //! | |
5e7ed085 | 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 | |
5e7ed085 | 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 | //! | |
04454e1e FG |
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 | |
f035d41b XL |
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 | /// | |
04454e1e | 153 | /// This may be used in contexts such as static initializers. |
f035d41b XL |
154 | /// |
155 | /// For example: | |
156 | /// ```rust | |
5099ac24 | 157 | /// use tracing_core::{callsite, identify_callsite}; |
f035d41b XL |
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 | /// | |
04454e1e FG |
177 | /// [`Identifier`]: callsite::Identifier |
178 | /// [`Callsite`]: callsite::Callsite | |
f035d41b XL |
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 | |
f035d41b | 190 | /// # use tracing_core::{callsite::Callsite, subscriber::Interest}; |
5099ac24 | 191 | /// use tracing_core::metadata; |
f035d41b XL |
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 | /// | |
04454e1e FG |
215 | /// [metadata]: metadata::Metadata |
216 | /// [`Metadata::new`]: metadata::Metadata::new | |
f035d41b XL |
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 | ) => { | |
3dfed10e | 227 | $crate::metadata! { |
f035d41b XL |
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 | ||
5099ac24 | 257 | // Facade module: `no_std` uses spinlocks, `std` uses the mutexes in the standard library |
f035d41b XL |
258 | #[cfg(not(feature = "std"))] |
259 | #[macro_use] | |
260 | mod lazy_static; | |
261 | ||
262 | // Trimmed-down vendored version of spin 0.5.2 (0387621) | |
263 | // Dependency of no_std lazy_static, not required in a std build | |
264 | #[cfg(not(feature = "std"))] | |
265 | pub(crate) mod spin; | |
266 | ||
267 | #[cfg(not(feature = "std"))] | |
268 | #[doc(hidden)] | |
3dfed10e XL |
269 | pub type Once = self::spin::Once<()>; |
270 | ||
271 | #[cfg(feature = "std")] | |
272 | pub use stdlib::sync::Once; | |
f035d41b XL |
273 | |
274 | pub mod callsite; | |
275 | pub mod dispatcher; | |
276 | pub mod event; | |
277 | pub mod field; | |
278 | pub mod metadata; | |
279 | mod parent; | |
280 | pub mod span; | |
281 | pub(crate) mod stdlib; | |
282 | pub mod subscriber; | |
283 | ||
284 | #[doc(inline)] | |
285 | pub use self::{ | |
286 | callsite::Callsite, | |
287 | dispatcher::Dispatch, | |
288 | event::Event, | |
289 | field::Field, | |
3dfed10e | 290 | metadata::{Level, LevelFilter, Metadata}, |
f035d41b XL |
291 | subscriber::Subscriber, |
292 | }; | |
293 | ||
294 | pub use self::{metadata::Kind, subscriber::Interest}; | |
295 | ||
296 | mod sealed { | |
297 | pub trait Sealed {} | |
298 | } |