vendor/tracing-subscriber-0.3.3/src/lib.rs

   1 //! Utilities for implementing and composing [`tracing`] subscribers.
   2 //!
   3 //! [`tracing`] is a framework for instrumenting Rust programs to collect
   4 //! scoped, structured, and async-aware diagnostics. The [`Subscriber`] trait
   5 //! represents the functionality necessary to collect this trace data. This
   6 //! crate contains tools for composing subscribers out of smaller units of
   7 //! behaviour, and batteries-included implementations of common subscriber
   8 //! functionality.
   9 //!
  10 //! `tracing-subscriber` is intended for use by both `Subscriber` authors and
  11 //! application authors using `tracing` to instrument their applications.
  12 //!
  13 //! *Compiler support: [requires `rustc` 1.42+][msrv]*
  14 //!
  15 //! [msrv]: #supported-rust-versions
  16 //!
  17 //! ## `Layer`s and `Filter`s
  18 //!
  19 //! The most important component of the `tracing-subscriber` API is the
  20 //! [`Layer`] trait, which provides a composable abstraction for building
  21 //! [`Subscriber`]s. Like the [`Subscriber`] trait, a [`Layer`] defines a
  22 //! particular behavior for collecting trace data. Unlike [`Subscriber`]s,
  23 //! which implement a *complete* strategy for how trace data is collected,
  24 //! [`Layer`]s provide *modular* implementations of specific behaviors.
  25 //! Therefore, they can be [composed together] to form a [`Subscriber`] which is
  26 //! capable of recording traces in a variety of ways. See the [`layer` module's
  27 //! documentation][layer] for details on using [`Layer`]s.
  28 //!
  29 //! In addition, the [`Filter`] trait defines an interface for filtering what
  30 //! spans and events are recorded by a particular layer. This allows different
  31 //! [`Layer`]s to handle separate subsets of the trace data emitted by a
  32 //! program. See the [documentation on per-layer filtering][plf] for more
  33 //! information on using [`Filter`]s.
  34 //!
  35 //! [`Layer`]: crate::layer::Layer
  36 //! [composed together]: crate::layer#composing-layers
  37 //! [layer]: crate::layer
  38 //! [`Filter`]: crate::layer::Filter
  39 //! [plf]: crate::layer#per-layer-filtering
  40 //!
  41 //! ## Included Subscribers
  42 //!
  43 //! The following `Subscriber`s are provided for application authors:
  44 //!
  45 //! - [`fmt`] - Formats and logs tracing data (requires the `fmt` feature flag)
  46 //!
  47 //! ## Feature Flags
  48 //!
  49 //! - `std`: Enables APIs that depend on the on the Rust standard library
  50 //!   (enabled by default).
  51 //! - `alloc`: Depend on [`liballoc`] (enabled by "std").
  52 //! - `env-filter`: Enables the [`EnvFilter`] type, which implements filtering
  53 //!   similar to the [`env_logger` crate]. **Requires "std"**.
  54 //! - `fmt`: Enables the [`fmt`] module, which provides a subscriber
  55 //!   implementation for printing formatted representations of trace events.
  56 //!   Enabled by default. **Requires "std"**.
  57 //! - `ansi`: Enables `fmt` support for ANSI terminal colors. Enabled by
  58 //!   default.
  59 //! - `registry`: enables the [`registry`] module. Enabled by default.
  60 //!   **Requires "std"**.
  61 //! - `json`: Enables `fmt` support for JSON output. In JSON output, the ANSI
  62 //!   feature does nothing. **Requires "fmt" and "std"**.
  63 //! - [`local-time`]: Enables local time formatting when using the [`time`
  64 //!   crate]'s timestamp formatters with the `fmt` subscriber.
  65 //!
  66 //! ### Optional Dependencies
  67 //!
  68 //! - [`tracing-log`]: Enables better formatting for events emitted by `log`
  69 //!   macros in the `fmt` subscriber. Enabled by default.
  70 //! - [`time`][`time` crate]: Enables support for using the [`time` crate] for timestamp
  71 //!   formatting in the `fmt` subscriber.
  72 //! - [`smallvec`]: Causes the `EnvFilter` type to use the `smallvec` crate (rather
  73 //!   than `Vec`) as a performance optimization. Enabled by default.
  74 //! - [`parking_lot`]: Use the `parking_lot` crate's `RwLock` implementation
  75 //!   rather than the Rust standard library's implementation.
  76 //!
  77 //! ### `no_std` Support
  78 //!
  79 //! In embedded systems and other bare-metal applications, `tracing` can be
  80 //! used without requiring the Rust standard library, although some features are
  81 //! disabled. Although most of the APIs provided by `tracing-subscriber`, such
  82 //! as [`fmt`] and [`EnvFilter`], require the standard library, some
  83 //! functionality, such as the [`Subscriber`] trait, can still be used in
  84 //! `no_std` environments.
  85 //!
  86 //! The dependency on the standard library is controlled by two crate feature
  87 //! flags, "std", which enables the dependency on [`libstd`], and "alloc", which
  88 //! enables the dependency on [`liballoc`] (and is enabled by the "std"
  89 //! feature). These features are enabled by default, but `no_std` users can
  90 //! disable them using:
  91 //!
  92 //! ```toml
  93 //! # Cargo.toml
  94 //! tracing-subscriber = { version = "0.3", default-features = false }
  95 //! ```
  96 //!
  97 //! Additional APIs are available when [`liballoc`] is available. To enable
  98 //! `liballoc` but not `std`, use:
  99 //!
 100 //! ```toml
 101 //! # Cargo.toml
 102 //! tracing-subscriber = { version = "0.3", default-features = false, features = ["alloc"] }
 103 //! ```
 104 //!
 105 //! ## Supported Rust Versions
 106 //!
 107 //! Tracing is built against the latest stable release. The minimum supported
 108 //! version is 1.42. The current Tracing version is not guaranteed to build on
 109 //! Rust versions earlier than the minimum supported version.
 110 //!
 111 //! Tracing follows the same compiler support policies as the rest of the Tokio
 112 //! project. The current stable Rust compiler and the three most recent minor
 113 //! versions before it will always be supported. For example, if the current
 114 //! stable compiler version is 1.45, the minimum supported version will not be
 115 //! increased past 1.42, three minor versions prior. Increasing the minimum
 116 //! supported compiler version is not considered a semver breaking change as
 117 //! long as doing so complies with this policy.
 118 //!
 119 //! [`tracing`]: https://docs.rs/tracing/latest/tracing/
 120 //! [`Subscriber`]: https://docs.rs/tracing-core/latest/tracing_core/subscriber/trait.Subscriber.html
 121 //! [`EnvFilter`]: filter/struct.EnvFilter.html
 122 //! [`fmt`]: fmt/index.html
 123 //! [`tracing-log`]: https://crates.io/crates/tracing-log
 124 //! [`smallvec`]: https://crates.io/crates/smallvec
 125 //! [`env_logger` crate]: https://crates.io/crates/env_logger
 126 //! [`parking_lot`]: https://crates.io/crates/parking_lot
 127 //! [`time` crate]: https://crates.io/crates/time
 128 //! [`liballoc`]: https://doc.rust-lang.org/alloc/index.html
 129 #![doc(html_root_url = "https://docs.rs/tracing-subscriber/0.3.1")]
 130 #![doc(
 131     html_logo_url = "https://raw.githubusercontent.com/tokio-rs/tracing/master/assets/logo-type.png",
 132     issue_tracker_base_url = "https://github.com/tokio-rs/tracing/issues/"
 133 )]
 134 #![cfg_attr(
 135     docsrs,
 136     // Allows displaying cfgs/feature flags in the documentation.
 137     feature(doc_cfg),
 138     // Allows adding traits to RustDoc's list of "notable traits"
 139     feature(doc_notable_trait),
 140     // Fail the docs build if any intra-docs links are broken
 141     deny(rustdoc::broken_intra_doc_links),
 142 )]
 143 #![warn(
 144     missing_debug_implementations,
 145     missing_docs,
 146     rust_2018_idioms,
 147     unreachable_pub,
 148     bad_style,
 149     const_err,
 150     dead_code,
 151     improper_ctypes,
 152     non_shorthand_field_patterns,
 153     no_mangle_generic_items,
 154     overflowing_literals,
 155     path_statements,
 156     patterns_in_fns_without_body,
 157     private_in_public,
 158     unconditional_recursion,
 159     unused,
 160     unused_allocation,
 161     unused_comparisons,
 162     unused_parens,
 163     while_true
 164 )]
 165 // Using struct update syntax when a struct has no additional fields avoids
 166 // a potential source change if additional fields are added to the struct in the
 167 // future, reducing diff noise. Allow this even though clippy considers it
 168 // "needless".
 169 #![allow(clippy::needless_update)]
 170 #![cfg_attr(not(feature = "std"), no_std)]
 171
 172 #[cfg(feature = "alloc")]
 173 extern crate alloc;
 174
 175 #[macro_use]
 176 mod macros;
 177
 178 pub mod field;
 179 pub mod filter;
 180 pub mod prelude;
 181 pub mod registry;
 182
 183 pub mod layer;
 184 pub mod util;
 185
 186 feature! {
 187     #![feature = "std"]
 188     pub mod reload;
 189     pub(crate) mod sync;
 190 }
 191
 192 feature! {
 193     #![all(feature = "fmt", feature = "std")]
 194     pub mod fmt;
 195     pub use fmt::fmt;
 196     pub use fmt::Subscriber as FmtSubscriber;
 197 }
 198
 199 feature! {
 200     #![all(feature = "env-filter", feature = "std")]
 201     pub use filter::EnvFilter;
 202 }
 203
 204 pub use layer::Layer;
 205
 206 feature! {
 207     #![all(feature = "registry", feature = "std")]
 208     pub use registry::Registry;
 209
 210     ///
 211     pub fn registry() -> Registry {
 212         Registry::default()
 213     }
 214 }
 215
 216 mod sealed {
 217     pub trait Sealed<A = ()> {}
 218 }