diff options
Diffstat (limited to 'vendor/tracing-core/src/lib.rs')
| -rw-r--r-- | vendor/tracing-core/src/lib.rs | 295 |
1 files changed, 295 insertions, 0 deletions
diff --git a/vendor/tracing-core/src/lib.rs b/vendor/tracing-core/src/lib.rs new file mode 100644 index 000000000..c1f87b22f --- /dev/null +++ b/vendor/tracing-core/src/lib.rs @@ -0,0 +1,295 @@ +//! Core primitives for `tracing`. +//! +//! [`tracing`] is a framework for instrumenting Rust programs to collect +//! structured, event-based diagnostic information. This crate defines the core +//! primitives of `tracing`. +//! +//! This crate provides: +//! +//! * [`span::Id`] identifies a span within the execution of a program. +//! +//! * [`Event`] represents a single event within a trace. +//! +//! * [`Subscriber`], the trait implemented to collect trace data. +//! +//! * [`Metadata`] and [`Callsite`] provide information describing spans and +//! `Event`s. +//! +//! * [`Field`], [`FieldSet`], [`Value`], and [`ValueSet`] represent the +//! structured data attached to a span. +//! +//! * [`Dispatch`] allows spans and events to be dispatched to `Subscriber`s. +//! +//! In addition, it defines the global callsite registry and per-thread current +//! dispatcher which other components of the tracing system rely on. +//! +//! *Compiler support: [requires `rustc` 1.49+][msrv]* +//! +//! [msrv]: #supported-rust-versions +//! +//! ## Usage +//! +//! Application authors will typically not use this crate directly. Instead, +//! they will use the [`tracing`] crate, which provides a much more +//! fully-featured API. However, this crate's API will change very infrequently, +//! so it may be used when dependencies must be very stable. +//! +//! `Subscriber` implementations may depend on `tracing-core` rather than +//! `tracing`, as the additional APIs provided by `tracing` are primarily useful +//! for instrumenting libraries and applications, and are generally not +//! necessary for `Subscriber` implementations. +//! +//! The [`tokio-rs/tracing`] repository contains less stable crates designed to +//! be used with the `tracing` ecosystem. It includes a collection of +//! `Subscriber` implementations, as well as utility and adapter crates. +//! +//! ## Crate Feature Flags +//! +//! The following crate [feature flags] are available: +//! +//! * `std`: Depend on the Rust standard library (enabled by default). +//! +//! `no_std` users may disable this feature with `default-features = false`: +//! +//! ```toml +//! [dependencies] +//! tracing-core = { version = "0.1.22", default-features = false } +//! ``` +//! +//! **Note**:`tracing-core`'s `no_std` support requires `liballoc`. +//! +//! ### Unstable Features +//! +//! These feature flags enable **unstable** features. The public API may break in 0.1.x +//! releases. To enable these features, the `--cfg tracing_unstable` must be passed to +//! `rustc` when compiling. +//! +//! The following unstable feature flags are currently available: +//! +//! * `valuable`: Enables support for recording [field values] using the +//! [`valuable`] crate. +//! +//! #### Enabling Unstable Features +//! +//! The easiest way to set the `tracing_unstable` cfg is to use the `RUSTFLAGS` +//! env variable when running `cargo` commands: +//! +//! ```shell +//! RUSTFLAGS="--cfg tracing_unstable" cargo build +//! ``` +//! Alternatively, the following can be added to the `.cargo/config` file in a +//! project to automatically enable the cfg flag for that project: +//! +//! ```toml +//! [build] +//! rustflags = ["--cfg", "tracing_unstable"] +//! ``` +//! +//! [feature flags]: https://doc.rust-lang.org/cargo/reference/manifest.html#the-features-section +//! [field values]: crate::field +//! [`valuable`]: https://crates.io/crates/valuable +//! +//! ## Supported Rust Versions +//! +//! Tracing is built against the latest stable release. The minimum supported +//! version is 1.49. The current Tracing version is not guaranteed to build on +//! Rust versions earlier than the minimum supported version. +//! +//! Tracing follows the same compiler support policies as the rest of the Tokio +//! project. The current stable Rust compiler and the three most recent minor +//! versions before it will always be supported. For example, if the current +//! stable compiler version is 1.45, the minimum supported version will not be +//! increased past 1.42, three minor versions prior. Increasing the minimum +//! supported compiler version is not considered a semver breaking change as +//! long as doing so complies with this policy. +//! +//! +//! [`span::Id`]: span::Id +//! [`Event`]: event::Event +//! [`Subscriber`]: subscriber::Subscriber +//! [`Metadata`]: metadata::Metadata +//! [`Callsite`]: callsite::Callsite +//! [`Field`]: field::Field +//! [`FieldSet`]: field::FieldSet +//! [`Value`]: field::Value +//! [`ValueSet`]: field::ValueSet +//! [`Dispatch`]: dispatcher::Dispatch +//! [`tokio-rs/tracing`]: https://github.com/tokio-rs/tracing +//! [`tracing`]: https://crates.io/crates/tracing +#![doc(html_root_url = "https://docs.rs/tracing-core/0.1.22")] +#![doc( + html_logo_url = "https://raw.githubusercontent.com/tokio-rs/tracing/master/assets/logo-type.png", + issue_tracker_base_url = "https://github.com/tokio-rs/tracing/issues/" +)] +#![cfg_attr(not(feature = "std"), no_std)] +#![cfg_attr(docsrs, feature(doc_cfg), deny(rustdoc::broken_intra_doc_links))] +#![warn( + missing_debug_implementations, + missing_docs, + rust_2018_idioms, + unreachable_pub, + bad_style, + const_err, + dead_code, + improper_ctypes, + non_shorthand_field_patterns, + no_mangle_generic_items, + overflowing_literals, + path_statements, + patterns_in_fns_without_body, + private_in_public, + unconditional_recursion, + unused, + unused_allocation, + unused_comparisons, + unused_parens, + while_true +)] +#[cfg(not(feature = "std"))] +extern crate alloc; + +/// Statically constructs an [`Identifier`] for the provided [`Callsite`]. +/// +/// This may be used in contexts such as static initializers. +/// +/// For example: +/// ```rust +/// use tracing_core::{callsite, identify_callsite}; +/// # use tracing_core::{Metadata, subscriber::Interest}; +/// # fn main() { +/// pub struct MyCallsite { +/// // ... +/// } +/// impl callsite::Callsite for MyCallsite { +/// # fn set_interest(&self, _: Interest) { unimplemented!() } +/// # fn metadata(&self) -> &Metadata { unimplemented!() } +/// // ... +/// } +/// +/// static CALLSITE: MyCallsite = MyCallsite { +/// // ... +/// }; +/// +/// static CALLSITE_ID: callsite::Identifier = identify_callsite!(&CALLSITE); +/// # } +/// ``` +/// +/// [`Identifier`]: callsite::Identifier +/// [`Callsite`]: callsite::Callsite +#[macro_export] +macro_rules! identify_callsite { + ($callsite:expr) => { + $crate::callsite::Identifier($callsite) + }; +} + +/// Statically constructs new span [metadata]. +/// +/// /// For example: +/// ```rust +/// # use tracing_core::{callsite::Callsite, subscriber::Interest}; +/// use tracing_core::metadata; +/// use tracing_core::metadata::{Kind, Level, Metadata}; +/// # fn main() { +/// # pub struct MyCallsite { } +/// # impl Callsite for MyCallsite { +/// # fn set_interest(&self, _: Interest) { unimplemented!() } +/// # fn metadata(&self) -> &Metadata { unimplemented!() } +/// # } +/// # +/// static FOO_CALLSITE: MyCallsite = MyCallsite { +/// // ... +/// }; +/// +/// static FOO_METADATA: Metadata = metadata!{ +/// name: "foo", +/// target: module_path!(), +/// level: Level::DEBUG, +/// fields: &["bar", "baz"], +/// callsite: &FOO_CALLSITE, +/// kind: Kind::SPAN, +/// }; +/// # } +/// ``` +/// +/// [metadata]: metadata::Metadata +/// [`Metadata::new`]: metadata::Metadata::new +#[macro_export] +macro_rules! metadata { + ( + name: $name:expr, + target: $target:expr, + level: $level:expr, + fields: $fields:expr, + callsite: $callsite:expr, + kind: $kind:expr + ) => { + $crate::metadata! { + name: $name, + target: $target, + level: $level, + fields: $fields, + callsite: $callsite, + kind: $kind, + } + }; + ( + name: $name:expr, + target: $target:expr, + level: $level:expr, + fields: $fields:expr, + callsite: $callsite:expr, + kind: $kind:expr, + ) => { + $crate::metadata::Metadata::new( + $name, + $target, + $level, + Some(file!()), + Some(line!()), + Some(module_path!()), + $crate::field::FieldSet::new($fields, $crate::identify_callsite!($callsite)), + $kind, + ) + }; +} + +pub(crate) mod lazy; + +// Trimmed-down vendored version of spin 0.5.2 (0387621) +// Dependency of no_std lazy_static, not required in a std build +#[cfg(not(feature = "std"))] +pub(crate) mod spin; + +#[cfg(not(feature = "std"))] +#[doc(hidden)] +pub type Once = self::spin::Once<()>; + +#[cfg(feature = "std")] +pub use stdlib::sync::Once; + +pub mod callsite; +pub mod dispatcher; +pub mod event; +pub mod field; +pub mod metadata; +mod parent; +pub mod span; +pub(crate) mod stdlib; +pub mod subscriber; + +#[doc(inline)] +pub use self::{ + callsite::Callsite, + dispatcher::Dispatch, + event::Event, + field::Field, + metadata::{Level, LevelFilter, Metadata}, + subscriber::Subscriber, +}; + +pub use self::{metadata::Kind, subscriber::Interest}; + +mod sealed { + pub trait Sealed {} +} |