vendor/tracing-core/src/lib.rs

   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.40+][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.16", default-features = false }
  57 //!   ```
  58 //!
  59 //!   **Note**:`tracing-core`'s `no_std` support requires `liballoc`.
  60 //!
  61 //! ## Supported Rust Versions
  62 //!
  63 //! Tracing is built against the latest stable release. The minimum supported
  64 //! version is 1.40. The current Tracing version is not guaranteed to build on
  65 //! Rust versions earlier than the minimum supported version.
  66 //!
  67 //! Tracing follows the same compiler support policies as the rest of the Tokio
  68 //! project. The current stable Rust compiler and the three most recent minor
  69 //! versions before it will always be supported. For example, if the current
  70 //! stable compiler version is 1.45, the minimum supported version will not be
  71 //! increased past 1.42, three minor versions prior. Increasing the minimum
  72 //! supported compiler version is not considered a semver breaking change as
  73 //! long as doing so complies with this policy.
  74 //!
  75 //!
  76 //! [`span::Id`]: span/struct.Id.html
  77 //! [`Event`]: event/struct.Event.html
  78 //! [`Subscriber`]: subscriber/trait.Subscriber.html
  79 //! [`Metadata`]: metadata/struct.Metadata.html
  80 //! [`Callsite`]: callsite/trait.Callsite.html
  81 //! [`Field`]: field/struct.Field.html
  82 //! [`FieldSet`]: field/struct.FieldSet.html
  83 //! [`Value`]: field/trait.Value.html
  84 //! [`ValueSet`]: field/struct.ValueSet.html
  85 //! [`Dispatch`]: dispatcher/struct.Dispatch.html
  86 //! [`tokio-rs/tracing`]: https://github.com/tokio-rs/tracing
  87 //! [`tracing`]: https://crates.io/crates/tracing
  88 #![doc(html_root_url = "https://docs.rs/tracing-core/0.1.16")]
  89 #![doc(
  90     html_logo_url = "https://raw.githubusercontent.com/tokio-rs/tracing/master/assets/logo-type.png",
  91     issue_tracker_base_url = "https://github.com/tokio-rs/tracing/issues/"
  92 )]
  93 #![cfg_attr(not(feature = "std"), no_std)]
  94 #![cfg_attr(docsrs, feature(doc_cfg))]
  95 #![warn(
  96     missing_debug_implementations,
  97     missing_docs,
  98     rust_2018_idioms,
  99     unreachable_pub,
 100     bad_style,
 101     const_err,
 102     dead_code,
 103     improper_ctypes,
 104     non_shorthand_field_patterns,
 105     no_mangle_generic_items,
 106     overflowing_literals,
 107     path_statements,
 108     patterns_in_fns_without_body,
 109     private_in_public,
 110     unconditional_recursion,
 111     unused,
 112     unused_allocation,
 113     unused_comparisons,
 114     unused_parens,
 115     while_true
 116 )]
 117 #[cfg(not(feature = "std"))]
 118 extern crate alloc;
 119
 120 /// Statically constructs an [`Identifier`] for the provided [`Callsite`].
 121 ///
 122 /// This may be used in contexts, such as static initializers, where the
 123 /// [`Callsite::id`] function is not currently usable.
 124 ///
 125 /// For example:
 126 /// ```rust
 127 /// # #[macro_use]
 128 /// # extern crate tracing_core;
 129 /// use tracing_core::callsite;
 130 /// # use tracing_core::{Metadata, subscriber::Interest};
 131 /// # fn main() {
 132 /// pub struct MyCallsite {
 133 ///    // ...
 134 /// }
 135 /// impl callsite::Callsite for MyCallsite {
 136 /// # fn set_interest(&self, _: Interest) { unimplemented!() }
 137 /// # fn metadata(&self) -> &Metadata { unimplemented!() }
 138 ///     // ...
 139 /// }
 140 ///
 141 /// static CALLSITE: MyCallsite = MyCallsite {
 142 ///     // ...
 143 /// };
 144 ///
 145 /// static CALLSITE_ID: callsite::Identifier = identify_callsite!(&CALLSITE);
 146 /// # }
 147 /// ```
 148 ///
 149 /// [`Identifier`]: callsite/struct.Identifier.html
 150 /// [`Callsite`]: callsite/trait.Callsite.html
 151 /// [`Callsite::id`]: callsite/trait.Callsite.html#method.id
 152 #[macro_export]
 153 macro_rules! identify_callsite {
 154     ($callsite:expr) => {
 155         $crate::callsite::Identifier($callsite)
 156     };
 157 }
 158
 159 /// Statically constructs new span [metadata].
 160 ///
 161 /// /// For example:
 162 /// ```rust
 163 /// # #[macro_use]
 164 /// # extern crate tracing_core;
 165 /// # use tracing_core::{callsite::Callsite, subscriber::Interest};
 166 /// use tracing_core::metadata::{Kind, Level, Metadata};
 167 /// # fn main() {
 168 /// # pub struct MyCallsite { }
 169 /// # impl Callsite for MyCallsite {
 170 /// # fn set_interest(&self, _: Interest) { unimplemented!() }
 171 /// # fn metadata(&self) -> &Metadata { unimplemented!() }
 172 /// # }
 173 /// #
 174 /// static FOO_CALLSITE: MyCallsite = MyCallsite {
 175 ///     // ...
 176 /// };
 177 ///
 178 /// static FOO_METADATA: Metadata = metadata!{
 179 ///     name: "foo",
 180 ///     target: module_path!(),
 181 ///     level: Level::DEBUG,
 182 ///     fields: &["bar", "baz"],
 183 ///     callsite: &FOO_CALLSITE,
 184 ///     kind: Kind::SPAN,
 185 /// };
 186 /// # }
 187 /// ```
 188 ///
 189 /// [metadata]: metadata/struct.Metadata.html
 190 /// [`Metadata::new`]: metadata/struct.Metadata.html#method.new
 191 #[macro_export]
 192 macro_rules! metadata {
 193     (
 194         name: $name:expr,
 195         target: $target:expr,
 196         level: $level:expr,
 197         fields: $fields:expr,
 198         callsite: $callsite:expr,
 199         kind: $kind:expr
 200     ) => {
 201         $crate::metadata! {
 202             name: $name,
 203             target: $target,
 204             level: $level,
 205             fields: $fields,
 206             callsite: $callsite,
 207             kind: $kind,
 208         }
 209     };
 210     (
 211         name: $name:expr,
 212         target: $target:expr,
 213         level: $level:expr,
 214         fields: $fields:expr,
 215         callsite: $callsite:expr,
 216         kind: $kind:expr,
 217     ) => {
 218         $crate::metadata::Metadata::new(
 219             $name,
 220             $target,
 221             $level,
 222             Some(file!()),
 223             Some(line!()),
 224             Some(module_path!()),
 225             $crate::field::FieldSet::new($fields, $crate::identify_callsite!($callsite)),
 226             $kind,
 227         )
 228     };
 229 }
 230
 231 // std uses lazy_static from crates.io
 232 #[cfg(feature = "std")]
 233 #[macro_use]
 234 extern crate lazy_static;
 235
 236 // no_std uses vendored version of lazy_static 1.4.0 (4216696) with spin
 237 // This can conflict when included in a project already using std lazy_static
 238 // Remove this module when cargo enables specifying dependencies for no_std
 239 #[cfg(not(feature = "std"))]
 240 #[macro_use]
 241 mod lazy_static;
 242
 243 // Trimmed-down vendored version of spin 0.5.2 (0387621)
 244 // Dependency of no_std lazy_static, not required in a std build
 245 #[cfg(not(feature = "std"))]
 246 pub(crate) mod spin;
 247
 248 #[cfg(not(feature = "std"))]
 249 #[doc(hidden)]
 250 pub type Once = self::spin::Once<()>;
 251
 252 #[cfg(feature = "std")]
 253 pub use stdlib::sync::Once;
 254
 255 pub mod callsite;
 256 pub mod dispatcher;
 257 pub mod event;
 258 pub mod field;
 259 pub mod metadata;
 260 mod parent;
 261 pub mod span;
 262 pub(crate) mod stdlib;
 263 pub mod subscriber;
 264
 265 #[doc(inline)]
 266 pub use self::{
 267     callsite::Callsite,
 268     dispatcher::Dispatch,
 269     event::Event,
 270     field::Field,
 271     metadata::{Level, LevelFilter, Metadata},
 272     subscriber::Subscriber,
 273 };
 274
 275 pub use self::{metadata::Kind, subscriber::Interest};
 276
 277 mod sealed {
 278     pub trait Sealed {}
 279 }