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"))]
149extern 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]
180macro_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]
218macro_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
257pub(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"))]
262pub(crate) mod spin;
263
264#[cfg(not(feature = "std"))]
265#[doc(hidden)]
266pub type Once = self::spin::Once<()>;
267
268#[cfg(feature = "std")]
269pub use stdlib::sync::Once;
270
271pub mod callsite;
272pub mod dispatcher;
273pub mod event;
274pub mod field;
275pub mod metadata;
276mod parent;
277pub mod span;
278pub(crate) mod stdlib;
279pub mod subscriber;
280
281#[doc(inline)]
282pub use self::{
283 callsite::Callsite,
284 dispatcher::Dispatch,
285 event::Event,
286 field::Field,
287 metadata::{Level, LevelFilter, Metadata},
288 subscriber::Subscriber,
289};
290
291pub use self::{metadata::Kind, subscriber::Interest};
292
293mod sealed {
294 pub trait Sealed {}
295}
296