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