diff options
Diffstat (limited to 'vendor/tracing-subscriber-0.3.3/src/layer/mod.rs')
| -rw-r--r-- | vendor/tracing-subscriber-0.3.3/src/layer/mod.rs | 1285 |
1 files changed, 0 insertions, 1285 deletions
diff --git a/vendor/tracing-subscriber-0.3.3/src/layer/mod.rs b/vendor/tracing-subscriber-0.3.3/src/layer/mod.rs deleted file mode 100644 index f3f994490..000000000 --- a/vendor/tracing-subscriber-0.3.3/src/layer/mod.rs +++ /dev/null @@ -1,1285 +0,0 @@ -//! The [`Layer`] trait, a composable abstraction for building [`Subscriber`]s. -//! -//! The [`Subscriber`] trait in `tracing-core` represents the _complete_ set of -//! functionality required to consume `tracing` instrumentation. This means that -//! a single `Subscriber` instance is a self-contained implementation of a -//! complete strategy for collecting traces; but it _also_ means that the -//! `Subscriber` trait cannot easily be composed with other `Subscriber`s. -//! -//! In particular, [`Subscriber`]s are responsible for generating [span IDs] and -//! assigning them to spans. Since these IDs must uniquely identify a span -//! within the context of the current trace, this means that there may only be -//! a single `Subscriber` for a given thread at any point in time — -//! otherwise, there would be no authoritative source of span IDs. -//! -//! On the other hand, the majority of the [`Subscriber`] trait's functionality -//! is composable: any number of subscribers may _observe_ events, span entry -//! and exit, and so on, provided that there is a single authoritative source of -//! span IDs. The [`Layer`] trait represents this composable subset of the -//! [`Subscriber`] behavior; it can _observe_ events and spans, but does not -//! assign IDs. -//! -//! ## Composing Layers -//! -//! Since a [`Layer`] does not implement a complete strategy for collecting -//! traces, it must be composed with a `Subscriber` in order to be used. The -//! [`Layer`] trait is generic over a type parameter (called `S` in the trait -//! definition), representing the types of `Subscriber` they can be composed -//! with. Thus, a [`Layer`] may be implemented that will only compose with a -//! particular `Subscriber` implementation, or additional trait bounds may be -//! added to constrain what types implementing `Subscriber` a `Layer` can wrap. -//! -//! `Layer`s may be added to a `Subscriber` by using the [`SubscriberExt::with`] -//! method, which is provided by `tracing-subscriber`'s [prelude]. This method -//! returns a [`Layered`] struct that implements `Subscriber` by composing the -//! `Layer` with the `Subscriber`. -//! -//! For example: -//! ```rust -//! use tracing_subscriber::Layer; -//! use tracing_subscriber::prelude::*; -//! use tracing::Subscriber; -//! -//! pub struct MyLayer { -//! // ... -//! } -//! -//! impl<S: Subscriber> Layer<S> for MyLayer { -//! // ... -//! } -//! -//! pub struct MySubscriber { -//! // ... -//! } -//! -//! # use tracing_core::{span::{Id, Attributes, Record}, Metadata, Event}; -//! impl Subscriber for MySubscriber { -//! // ... -//! # fn new_span(&self, _: &Attributes) -> Id { Id::from_u64(1) } -//! # fn record(&self, _: &Id, _: &Record) {} -//! # fn event(&self, _: &Event) {} -//! # fn record_follows_from(&self, _: &Id, _: &Id) {} -//! # fn enabled(&self, _: &Metadata) -> bool { false } -//! # fn enter(&self, _: &Id) {} -//! # fn exit(&self, _: &Id) {} -//! } -//! # impl MyLayer { -//! # fn new() -> Self { Self {} } -//! # } -//! # impl MySubscriber { -//! # fn new() -> Self { Self { }} -//! # } -//! -//! let subscriber = MySubscriber::new() -//! .with(MyLayer::new()); -//! -//! tracing::subscriber::set_global_default(subscriber); -//! ``` -//! -//! Multiple `Layer`s may be composed in the same manner: -//! ```rust -//! # use tracing_subscriber::{Layer, layer::SubscriberExt}; -//! # use tracing::Subscriber; -//! pub struct MyOtherLayer { -//! // ... -//! } -//! -//! impl<S: Subscriber> Layer<S> for MyOtherLayer { -//! // ... -//! } -//! -//! pub struct MyThirdLayer { -//! // ... -//! } -//! -//! impl<S: Subscriber> Layer<S> for MyThirdLayer { -//! // ... -//! } -//! # pub struct MyLayer {} -//! # impl<S: Subscriber> Layer<S> for MyLayer {} -//! # pub struct MySubscriber { } -//! # use tracing_core::{span::{Id, Attributes, Record}, Metadata, Event}; -//! # impl Subscriber for MySubscriber { -//! # fn new_span(&self, _: &Attributes) -> Id { Id::from_u64(1) } -//! # fn record(&self, _: &Id, _: &Record) {} -//! # fn event(&self, _: &Event) {} -//! # fn record_follows_from(&self, _: &Id, _: &Id) {} -//! # fn enabled(&self, _: &Metadata) -> bool { false } -//! # fn enter(&self, _: &Id) {} -//! # fn exit(&self, _: &Id) {} -//! } -//! # impl MyLayer { -//! # fn new() -> Self { Self {} } -//! # } -//! # impl MyOtherLayer { -//! # fn new() -> Self { Self {} } -//! # } -//! # impl MyThirdLayer { -//! # fn new() -> Self { Self {} } -//! # } -//! # impl MySubscriber { -//! # fn new() -> Self { Self { }} -//! # } -//! -//! let subscriber = MySubscriber::new() -//! .with(MyLayer::new()) -//! .with(MyOtherLayer::new()) -//! .with(MyThirdLayer::new()); -//! -//! tracing::subscriber::set_global_default(subscriber); -//! ``` -//! -//! The [`Layer::with_subscriber`] constructs the [`Layered`] type from a -//! [`Layer`] and [`Subscriber`], and is called by [`SubscriberExt::with`]. In -//! general, it is more idiomatic to use [`SubscriberExt::with`], and treat -//! [`Layer::with_subscriber`] as an implementation detail, as `with_subscriber` -//! calls must be nested, leading to less clear code for the reader. -//! -//! [prelude]: crate::prelude -//! -//! ## Recording Traces -//! -//! The [`Layer`] trait defines a set of methods for consuming notifications from -//! tracing instrumentation, which are generally equivalent to the similarly -//! named methods on [`Subscriber`]. Unlike [`Subscriber`], the methods on -//! `Layer` are additionally passed a [`Context`] type, which exposes additional -//! information provided by the wrapped subscriber (such as [the current span]) -//! to the layer. -//! -//! ## Filtering with `Layer`s -//! -//! As well as strategies for handling trace events, the `Layer` trait may also -//! be used to represent composable _filters_. This allows the determination of -//! what spans and events should be recorded to be decoupled from _how_ they are -//! recorded: a filtering layer can be applied to other layers or -//! subscribers. `Layer`s can be used to implement _global filtering_, where a -//! `Layer` provides a filtering strategy for the entire subscriber. -//! Additionally, individual recording `Layer`s or sets of `Layer`s may be -//! combined with _per-layer filters_ that control what spans and events are -//! recorded by those layers. -//! -//! ### Global Filtering -//! -//! A `Layer` that implements a filtering strategy should override the -//! [`register_callsite`] and/or [`enabled`] methods. It may also choose to implement -//! methods such as [`on_enter`], if it wishes to filter trace events based on -//! the current span context. -//! -//! Note that the [`Layer::register_callsite`] and [`Layer::enabled`] methods -//! determine whether a span or event is enabled *globally*. Thus, they should -//! **not** be used to indicate whether an individual layer wishes to record a -//! particular span or event. Instead, if a layer is only interested in a subset -//! of trace data, but does *not* wish to disable other spans and events for the -//! rest of the layer stack should ignore those spans and events in its -//! notification methods. -//! -//! The filtering methods on a stack of `Layer`s are evaluated in a top-down -//! order, starting with the outermost `Layer` and ending with the wrapped -//! [`Subscriber`]. If any layer returns `false` from its [`enabled`] method, or -//! [`Interest::never()`] from its [`register_callsite`] method, filter -//! evaluation will short-circuit and the span or event will be disabled. -//! -//! ### Per-Layer Filtering -//! -//! **Note**: per-layer filtering APIs currently require the [`"registry"` crate -//! feature flag][feat] to be enabled. -//! -//! Sometimes, it may be desirable for one `Layer` to record a particular subset -//! of spans and events, while a different subset of spans and events are -//! recorded by other `Layer`s. For example: -//! -//! - A layer that records metrics may wish to observe only events including -//! particular tracked values, while a logging layer ignores those events. -//! - If recording a distributed trace is expensive, it might be desirable to -//! only send spans with `INFO` and lower verbosity to the distributed tracing -//! system, while logging more verbose spans to a file. -//! - Spans and events with a particular target might be recorded differently -//! from others, such as by generating an HTTP access log from a span that -//! tracks the lifetime of an HTTP request. -//! -//! The [`Filter`] trait is used to control what spans and events are -//! observed by an individual `Layer`, while still allowing other `Layer`s to -//! potentially record them. The [`Layer::with_filter`] method combines a -//! `Layer` with a [`Filter`], returning a [`Filtered`] layer. -//! -//! This crate's [`filter`] module provides a number of types which implement -//! the [`Filter`] trait, such as [`LevelFilter`], [`Targets`], and -//! [`FilterFn`]. These [`Filter`]s provide ready-made implementations of -//! common forms of filtering. For custom filtering policies, the [`FilterFn`] -//! and [`DynFilterFn`] types allow implementing a [`Filter`] with a closure or -//! function pointer. In addition, when more control is required, the [`Filter`] -//! trait may also be implemented for user-defined types. -//! -//! <pre class="compile_fail" style="white-space:normal;font:inherit;"> -//! <strong>Warning</strong>: Currently, the <a href="../struct.Registry.html"> -//! <code>Registry</code></a> type defined in this crate is the only root -//! <code>Subscriber</code> capable of supporting <code>Layer</code>s with -//! per-layer filters. In the future, new APIs will be added to allow other -//! root <code>Subscriber</code>s to support per-layer filters. -//! </pre> -//! -//! For example, to generate an HTTP access log based on spans with -//! the `http_access` target, while logging other spans and events to -//! standard out, a [`Filter`] can be added to the access log layer: -//! -//! ``` -//! use tracing_subscriber::{filter, prelude::*}; -//! -//! // Generates an HTTP access log. -//! let access_log = // ... -//! # filter::LevelFilter::INFO; -//! -//! // Add a filter to the access log layer so that it only observes -//! // spans and events with the `http_access` target. -//! let access_log = access_log.with_filter(filter::filter_fn(|metadata| { -//! // Returns `true` if and only if the span or event's target is -//! // "http_access". -//! metadata.target() == "http_access" -//! })); -//! -//! // A general-purpose logging layer. -//! let fmt_layer = tracing_subscriber::fmt::layer(); -//! -//! // Build a subscriber that combines the access log and stdout log -//! // layers. -//! tracing_subscriber::registry() -//! .with(fmt_layer) -//! .with(access_log) -//! .init(); -//! ``` -//! -//! Multiple layers can have their own, separate per-layer filters. A span or -//! event will be recorded if it is enabled by _any_ per-layer filter, but it -//! will be skipped by the layers whose filters did not enable it. Building on -//! the previous example: -//! -//! ``` -//! use tracing_subscriber::{filter::{filter_fn, LevelFilter}, prelude::*}; -//! -//! let access_log = // ... -//! # LevelFilter::INFO; -//! let fmt_layer = tracing_subscriber::fmt::layer(); -//! -//! tracing_subscriber::registry() -//! // Add the filter for the "http_access" target to the access -//! // log layer, like before. -//! .with(access_log.with_filter(filter_fn(|metadata| { -//! metadata.target() == "http_access" -//! }))) -//! // Add a filter for spans and events with the INFO level -//! // and below to the logging layer. -//! .with(fmt_layer.with_filter(LevelFilter::INFO)) -//! .init(); -//! -//! // Neither layer will observe this event -//! tracing::debug!(does_anyone_care = false, "a tree fell in the forest"); -//! -//! // This event will be observed by the logging layer, but not -//! // by the access log layer. -//! tracing::warn!(dose_roentgen = %3.8, "not great, but not terrible"); -//! -//! // This event will be observed only by the access log layer. -//! tracing::trace!(target: "http_access", "HTTP request started"); -//! -//! // Both layers will observe this event. -//! tracing::error!(target: "http_access", "HTTP request failed with a very bad error!"); -//! ``` -//! -//! A per-layer filter can be applied to multiple [`Layer`]s at a time, by -//! combining them into a [`Layered`] layer using [`Layer::and_then`], and then -//! calling [`Layer::with_filter`] on the resulting [`Layered`] layer. -//! -//! Consider the following: -//! - `layer_a` and `layer_b`, which should only receive spans and events at -//! the [`INFO`] [level] and above. -//! - A third layer, `layer_c`, which should receive spans and events at -//! the [`DEBUG`] [level] as well. -//! The layers and filters would be composed thusly: -//! -//! ``` -//! use tracing_subscriber::{filter::LevelFilter, prelude::*}; -//! -//! let layer_a = // ... -//! # LevelFilter::INFO; -//! let layer_b = // ... -//! # LevelFilter::INFO; -//! let layer_c = // ... -//! # LevelFilter::INFO; -//! -//! let info_layers = layer_a -//! // Combine `layer_a` and `layer_b` into a `Layered` layer: -//! .and_then(layer_b) -//! // ...and then add an `INFO` `LevelFilter` to that layer: -//! .with_filter(LevelFilter::INFO); -//! -//! tracing_subscriber::registry() -//! // Add `layer_c` with a `DEBUG` filter. -//! .with(layer_c.with_filter(LevelFilter::DEBUG)) -//! .with(info_layers) -//! .init(); -//!``` -//! -//! If a [`Filtered`] [`Layer`] is combined with another [`Layer`] -//! [`Layer::and_then`], and a filter is added to the [`Layered`] layer, that -//! layer will be filtered by *both* the inner filter and the outer filter. -//! Only spans and events that are enabled by *both* filters will be -//! observed by that layer. This can be used to implement complex filtering -//! trees. -//! -//! As an example, consider the following constraints: -//! - Suppose that a particular [target] is used to indicate events that -//! should be counted as part of a metrics system, which should be only -//! observed by a layer that collects metrics. -//! - A log of high-priority events ([`INFO`] and above) should be logged -//! to stdout, while more verbose events should be logged to a debugging log file. -//! - Metrics-focused events should *not* be included in either log output. -//! -//! In that case, it is possible to apply a filter to both logging layers to -//! exclude the metrics events, while additionally adding a [`LevelFilter`] -//! to the stdout log: -//! -//! ``` -//! # // wrap this in a function so we don't actually create `debug.log` when -//! # // running the doctests.. -//! # fn docs() -> Result<(), Box<dyn std::error::Error + 'static>> { -//! use tracing_subscriber::{filter, prelude::*}; -//! use std::{fs::File, sync::Arc}; -//! -//! // A layer that logs events to stdout using the human-readable "pretty" -//! // format. -//! let stdout_log = tracing_subscriber::fmt::layer() -//! .pretty(); -//! -//! // A layer that logs events to a file. -//! let file = File::create("debug.log")?; -//! let debug_log = tracing_subscriber::fmt::layer() -//! .with_writer(Arc::new(file)); -//! -//! // A layer that collects metrics using specific events. -//! let metrics_layer = /* ... */ filter::LevelFilter::INFO; -//! -//! tracing_subscriber::registry() -//! .with( -//! stdout_log -//! // Add an `INFO` filter to the stdout logging layer -//! .with_filter(filter::LevelFilter::INFO) -//! // Combine the filtered `stdout_log` layer with the -//! // `debug_log` layer, producing a new `Layered` layer. -//! .and_then(debug_log) -//! // Add a filter to *both* layers that rejects spans and -//! // events whose targets start with `metrics`. -//! .with_filter(filter::filter_fn(|metadata| { -//! !metadata.target().starts_with("metrics") -//! })) -//! ) -//! .with( -//! // Add a filter to the metrics label that *only* enables -//! // events whose targets start with `metrics`. -//! metrics_layer.with_filter(filter::filter_fn(|metadata| { -//! metadata.target().starts_with("metrics") -//! })) -//! ) -//! .init(); -//! -//! // This event will *only* be recorded by the metrics layer. -//! tracing::info!(target: "metrics::cool_stuff_count", value = 42); -//! -//! // This event will only be seen by the debug log file layer: -//! tracing::debug!("this is a message, and part of a system of messages"); -//! -//! // This event will be seen by both the stdout log layer *and* -//! // the debug log file layer, but not by the metrics layer. -//! tracing::warn!("the message is a warning about danger!"); -//! # Ok(()) } -//! ``` -//! -//! ## Runtime Configuration With Layers -//! -//! In some cases, a particular [`Layer`] may be enabled or disabled based on -//! runtime configuration. This can introduce challenges, because the type of a -//! layered [`Subscriber`] depends on which layers are added to it: if an `if` -//! or `match` expression adds some [`Layer`]s in one branch and other layers -//! in another, the [`Subscriber`] values returned by those branches will have -//! different types. For example, the following _will not_ work: -//! -//! ```compile_fail -//! # fn docs() -> Result<(), Box<dyn std::error::Error + 'static>> { -//! # struct Config { -//! # is_prod: bool, -//! # path: &'static str, -//! # } -//! # let cfg = Config { is_prod: false, path: "debug.log" }; -//! use std::{fs::File, sync::Arc}; -//! use tracing_subscriber::{Registry, prelude::*}; -//! -//! let stdout_log = tracing_subscriber::fmt::layer().pretty(); -//! let subscriber = Registry::default().with(stdout_log); -//! -//! // The compile error will occur here because the if and else -//! // branches have different (and therefore incompatible) types. -//! let subscriber = if cfg.is_prod { -//! let file = File::create(cfg.path)?; -//! let layer = tracing_subscriber::fmt::layer() -//! .json() -//! .with_writer(Arc::new(file)); -//! subscriber.with(layer) -//! } else { -//! subscriber -//! }; -//! -//! tracing::subscriber::set_global_default(subscriber) -//! .expect("Unable to set global subscriber"); -//! # Ok(()) } -//! ``` -//! -//! However, a [`Layer`] wrapped in an [`Option`] [also implements the `Layer` -//! trait][option-impl]. This allows individual layers to be enabled or disabled at -//! runtime while always producing a [`Subscriber`] of the same type. For -//! example: -//! -//! ``` -//! # fn docs() -> Result<(), Box<dyn std::error::Error + 'static>> { -//! # struct Config { -//! # is_prod: bool, -//! # path: &'static str, -//! # } -//! # let cfg = Config { is_prod: false, path: "debug.log" }; -//! use std::{fs::File, sync::Arc}; -//! use tracing_subscriber::{Registry, prelude::*}; -//! -//! let stdout_log = tracing_subscriber::fmt::layer().pretty(); -//! let subscriber = Registry::default().with(stdout_log); -//! -//! // if `cfg.is_prod` is true, also log JSON-formatted logs to a file. -//! let json_log = if cfg.is_prod { -//! let file = File::create(cfg.path)?; -//! let json_log = tracing_subscriber::fmt::layer() -//! .json() -//! .with_writer(Arc::new(file)); -//! Some(json_log) -//! } else { -//! None -//! }; -//! -//! // If `cfg.is_prod` is false, then `json` will be `None`, and this layer -//! // will do nothing. However, the subscriber will still have the same type -//! // regardless of whether the `Option`'s value is `None` or `Some`. -//! let subscriber = subscriber.with(json_log); -//! -//! tracing::subscriber::set_global_default(subscriber) -//! .expect("Unable to set global subscriber"); -//! # Ok(()) } -//! ``` -//! -//! [`Subscriber`]: https://docs.rs/tracing-core/latest/tracing_core/subscriber/trait.Subscriber.html -//! [span IDs]: https://docs.rs/tracing-core/latest/tracing_core/span/struct.Id.html -//! [the current span]: Context::current_span -//! [`register_callsite`]: Layer::register_callsite -//! [`enabled`]: Layer::enabled -//! [`on_enter`]: Layer::on_enter -//! [`Layer::register_callsite`]: Layer::register_callsite -//! [`Layer::enabled`]: Layer::enabled -//! [`Interest::never()`]: https://docs.rs/tracing-core/latest/tracing_core/subscriber/struct.Interest.html#method.never -//! [option-impl]: crate::layer::Layer#impl-Layer<S>-for-Option<L> -//! [`Filtered`]: crate::filter::Filtered -//! [`filter`]: crate::filter -//! [`Targets`]: crate::filter::Targets -//! [`FilterFn`]: crate::filter::FilterFn -//! [`DynFilterFn`]: crate::filter::DynFilterFn -//! [level]: tracing_core::Level -//! [`INFO`]: tracing_core::Level::INFO -//! [`DEBUG`]: tracing_core::Level::DEBUG -//! [target]: tracing_core::Metadata::target -//! [`LevelFilter`]: crate::filter::LevelFilter -//! [feat]: crate#feature-flags -use crate::filter; - -use tracing_core::{ - metadata::Metadata, - span, - subscriber::{Interest, Subscriber}, - Event, LevelFilter, -}; - -use core::any::TypeId; - -feature! { - #![feature = "alloc"] - use alloc::boxed::Box; - use core::ops::{Deref, DerefMut}; -} - -mod context; -mod layered; -pub use self::{context::*, layered::*}; - -// The `tests` module is `pub(crate)` because it contains test utilities used by -// other modules. -#[cfg(test)] -pub(crate) mod tests; - -/// A composable handler for `tracing` events. -/// -/// A `Layer` implements a behavior for recording or collecting traces that can -/// be composed together with other `Layer`s to build a [`Subscriber`]. See the -/// [module-level documentation](crate::layer) for details. -/// -/// [`Subscriber`]: tracing_core::Subscriber -#[cfg_attr(docsrs, doc(notable_trait))] -pub trait Layer<S> -where - S: Subscriber, - Self: 'static, -{ - /// Performs late initialization when attaching a `Layer` to a - /// [`Subscriber`]. - /// - /// This is a callback that is called when the `Layer` is added to a - /// [`Subscriber`] (e.g. in [`Layer::with_subscriber`] and - /// [`SubscriberExt::with`]). Since this can only occur before the - /// [`Subscriber`] has been set as the default, both the `Layer` and - /// [`Subscriber`] are passed to this method _mutably_. This gives the - /// `Layer` the opportunity to set any of its own fields with values - /// recieved by method calls on the [`Subscriber`]. - /// - /// For example, [`Filtered`] layers implement `on_layer` to call the - /// [`Subscriber`]'s [`register_filter`] method, and store the returned - /// [`FilterId`] as a field. - /// - /// **Note** In most cases, `Layer` implementations will not need to - /// implement this method. However, in cases where a type implementing - /// `Layer` wraps one or more other types that implement `Layer`, like the - /// [`Layered`] and [`Filtered`] types in this crate, that type MUST ensure - /// that the inner `Layer`s' `on_layer` methods are called. Otherwise, - /// functionality that relies on `on_layer`, such as [per-layer filtering], - /// may not work correctly. - /// - /// [`Filtered`]: crate::filter::Filtered - /// [`register_filter`]: crate::registry::LookupSpan::register_filter - /// [per-layer filtering]: #per-layer-filtering - /// [`FilterId`]: crate::filter::FilterId - fn on_layer(&mut self, subscriber: &mut S) { - let _ = subscriber; - } - - /// Registers a new callsite with this layer, returning whether or not - /// the layer is interested in being notified about the callsite, similarly - /// to [`Subscriber::register_callsite`]. - /// - /// By default, this returns [`Interest::always()`] if [`self.enabled`] returns - /// true, or [`Interest::never()`] if it returns false. - /// - /// <pre class="ignore" style="white-space:normal;font:inherit;"> - /// <strong>Note</strong>: This method (and <a href="#method.enabled"> - /// <code>Layer::enabled</code></a>) determine whether a span or event is - /// globally enabled, <em>not</em> whether the individual layer will be - /// notified about that span or event. This is intended to be used - /// by layers that implement filtering for the entire stack. Layers which do - /// not wish to be notified about certain spans or events but do not wish to - /// globally disable them should ignore those spans or events in their - /// <a href="#method.on_event"><code>on_event</code></a>, - /// <a href="#method.on_enter"><code>on_enter</code></a>, - /// <a href="#method.on_exit"><code>on_exit</code></a>, and other notification - /// methods. - /// </pre> - /// - /// See [the trait-level documentation] for more information on filtering - /// with `Layer`s. - /// - /// Layers may also implement this method to perform any behaviour that - /// should be run once per callsite. If the layer wishes to use - /// `register_callsite` for per-callsite behaviour, but does not want to - /// globally enable or disable those callsites, it should always return - /// [`Interest::always()`]. - /// - /// [`Interest`]: https://docs.rs/tracing-core/latest/tracing_core/struct.Interest.html - /// [`Subscriber::register_callsite`]: https://docs.rs/tracing-core/latest/tracing_core/trait.Subscriber.html#method.register_callsite - /// [`Interest::never()`]: https://docs.rs/tracing-core/latest/tracing_core/subscriber/struct.Interest.html#method.never - /// [`Interest::always()`]: https://docs.rs/tracing-core/latest/tracing_core/subscriber/struct.Interest.html#method.always - /// [`self.enabled`]: #method.enabled - /// [`Layer::enabled`]: #method.enabled - /// [`on_event`]: #method.on_event - /// [`on_enter`]: #method.on_enter - /// [`on_exit`]: #method.on_exit - /// [the trait-level documentation]: #filtering-with-layers - fn register_callsite(&self, metadata: &'static Metadata<'static>) -> Interest { - if self.enabled(metadata, Context::none()) { - Interest::always() - } else { - Interest::never() - } - } - - /// Returns `true` if this layer is interested in a span or event with the - /// given `metadata` in the current [`Context`], similarly to - /// [`Subscriber::enabled`]. - /// - /// By default, this always returns `true`, allowing the wrapped subscriber - /// to choose to disable the span. - /// - /// <pre class="ignore" style="white-space:normal;font:inherit;"> - /// <strong>Note</strong>: This method (and <a href="#method.register_callsite"> - /// <code>Layer::register_callsite</code></a>) determine whether a span or event is - /// globally enabled, <em>not</em> whether the individual layer will be - /// notified about that span or event. This is intended to be used - /// by layers that implement filtering for the entire stack. Layers which do - /// not wish to be notified about certain spans or events but do not wish to - /// globally disable them should ignore those spans or events in their - /// <a href="#method.on_event"><code>on_event</code></a>, - /// <a href="#method.on_enter"><code>on_enter</code></a>, - /// <a href="#method.on_exit"><code>on_exit</code></a>, and other notification - /// methods. - /// </pre> - /// - /// - /// See [the trait-level documentation] for more information on filtering - /// with `Layer`s. - /// - /// [`Interest`]: https://docs.rs/tracing-core/latest/tracing_core/struct.Interest.html - /// [`Context`]: ../struct.Context.html - /// [`Subscriber::enabled`]: https://docs.rs/tracing-core/latest/tracing_core/trait.Subscriber.html#method.enabled - /// [`Layer::register_callsite`]: #method.register_callsite - /// [`on_event`]: #method.on_event - /// [`on_enter`]: #method.on_enter - /// [`on_exit`]: #method.on_exit - /// [the trait-level documentation]: #filtering-with-layers - fn enabled(&self, metadata: &Metadata<'_>, ctx: Context<'_, S>) -> bool { - let _ = (metadata, ctx); - true - } - - /// Notifies this layer that a new span was constructed with the given - /// `Attributes` and `Id`. - fn on_new_span(&self, attrs: &span::Attributes<'_>, id: &span::Id, ctx: Context<'_, S>) { - let _ = (attrs, id, ctx); - } - - // TODO(eliza): do we want this to be a public API? If we end up moving - // filtering layers to a separate trait, we may no longer want `Layer`s to - // be able to participate in max level hinting... - #[doc(hidden)] - fn max_level_hint(&self) -> Option<LevelFilter> { - None - } - - /// Notifies this layer that a span with the given `Id` recorded the given - /// `values`. - // Note: it's unclear to me why we'd need the current span in `record` (the - // only thing the `Context` type currently provides), but passing it in anyway - // seems like a good future-proofing measure as it may grow other methods later... - fn on_record(&self, _span: &span::Id, _values: &span::Record<'_>, _ctx: Context<'_, S>) {} - - /// Notifies this layer that a span with the ID `span` recorded that it - /// follows from the span with the ID `follows`. - // Note: it's unclear to me why we'd need the current span in `record` (the - // only thing the `Context` type currently provides), but passing it in anyway - // seems like a good future-proofing measure as it may grow other methods later... - fn on_follows_from(&self, _span: &span::Id, _follows: &span::Id, _ctx: Context<'_, S>) {} - - /// Notifies this layer that an event has occurred. - fn on_event(&self, _event: &Event<'_>, _ctx: Context<'_, S>) {} - - /// Notifies this layer that a span with the given ID was entered. - fn on_enter(&self, _id: &span::Id, _ctx: Context<'_, S>) {} - - /// Notifies this layer that the span with the given ID was exited. - fn on_exit(&self, _id: &span::Id, _ctx: Context<'_, S>) {} - - /// Notifies this layer that the span with the given ID has been closed. - fn on_close(&self, _id: span::Id, _ctx: Context<'_, S>) {} - - /// Notifies this layer that a span ID has been cloned, and that the - /// subscriber returned a different ID. - fn on_id_change(&self, _old: &span::Id, _new: &span::Id, _ctx: Context<'_, S>) {} - - /// Composes this layer around the given `Layer`, returning a `Layered` - /// struct implementing `Layer`. - /// - /// The returned `Layer` will call the methods on this `Layer` and then - /// those of the new `Layer`, before calling the methods on the subscriber - /// it wraps. For example: - /// - /// ```rust - /// # use tracing_subscriber::layer::Layer; - /// # use tracing_core::Subscriber; - /// pub struct FooLayer { - /// // ... - /// } - /// - /// pub struct BarLayer { - /// // ... - /// } - /// - /// pub struct MySubscriber { - /// // ... - /// } - /// - /// impl<S: Subscriber> Layer<S> for FooLayer { - /// // ... - /// } - /// - /// impl<S: Subscriber> Layer<S> for BarLayer { - /// // ... - /// } - /// - /// # impl FooLayer { - /// # fn new() -> Self { Self {} } - /// # } - /// # impl BarLayer { - /// # fn new() -> Self { Self { }} - /// # } - /// # impl MySubscriber { - /// # fn new() -> Self { Self { }} - /// # } - /// # use tracing_core::{span::{Id, Attributes, Record}, Metadata, Event}; - /// # impl tracing_core::Subscriber for MySubscriber { - /// # fn new_span(&self, _: &Attributes) -> Id { Id::from_u64(1) } - /// # fn record(&self, _: &Id, _: &Record) {} - /// # fn event(&self, _: &Event) {} - /// # fn record_follows_from(&self, _: &Id, _: &Id) {} - /// # fn enabled(&self, _: &Metadata) -> bool { false } - /// # fn enter(&self, _: &Id) {} - /// # fn exit(&self, _: &Id) {} - /// # } - /// let subscriber = FooLayer::new() - /// .and_then(BarLayer::new()) - /// .with_subscriber(MySubscriber::new()); - /// ``` - /// - /// Multiple layers may be composed in this manner: - /// - /// ```rust - /// # use tracing_subscriber::layer::Layer; - /// # use tracing_core::Subscriber; - /// # pub struct FooLayer {} - /// # pub struct BarLayer {} - /// # pub struct MySubscriber {} - /// # impl<S: Subscriber> Layer<S> for FooLayer {} - /// # impl<S: Subscriber> Layer<S> for BarLayer {} - /// # impl FooLayer { - /// # fn new() -> Self { Self {} } - /// # } - /// # impl BarLayer { - /// # fn new() -> Self { Self { }} - /// # } - /// # impl MySubscriber { - /// # fn new() -> Self { Self { }} - /// # } - /// # use tracing_core::{span::{Id, Attributes, Record}, Metadata, Event}; - /// # impl tracing_core::Subscriber for MySubscriber { - /// # fn new_span(&self, _: &Attributes) -> Id { Id::from_u64(1) } - /// # fn record(&self, _: &Id, _: &Record) {} - /// # fn event(&self, _: &Event) {} - /// # fn record_follows_from(&self, _: &Id, _: &Id) {} - /// # fn enabled(&self, _: &Metadata) -> bool { false } - /// # fn enter(&self, _: &Id) {} - /// # fn exit(&self, _: &Id) {} - /// # } - /// pub struct BazLayer { - /// // ... - /// } - /// - /// impl<S: Subscriber> Layer<S> for BazLayer { - /// // ... - /// } - /// # impl BazLayer { fn new() -> Self { BazLayer {} } } - /// - /// let subscriber = FooLayer::new() - /// .and_then(BarLayer::new()) - /// .and_then(BazLayer::new()) - /// .with_subscriber(MySubscriber::new()); - /// ``` - fn and_then<L>(self, layer: L) -> Layered<L, Self, S> - where - L: Layer<S>, - Self: Sized, - { - let inner_has_layer_filter = filter::layer_has_plf(&self); - Layered::new(layer, self, inner_has_layer_filter) - } - - /// Composes this `Layer` with the given [`Subscriber`], returning a - /// `Layered` struct that implements [`Subscriber`]. - /// - /// The returned `Layered` subscriber will call the methods on this `Layer` - /// and then those of the wrapped subscriber. - /// - /// For example: - /// ```rust - /// # use tracing_subscriber::layer::Layer; - /// # use tracing_core::Subscriber; - /// pub struct FooLayer { - /// // ... - /// } - /// - /// pub struct MySubscriber { - /// // ... - /// } - /// - /// impl<S: Subscriber> Layer<S> for FooLayer { - /// // ... - /// } - /// - /// # impl FooLayer { - /// # fn new() -> Self { Self {} } - /// # } - /// # impl MySubscriber { - /// # fn new() -> Self { Self { }} - /// # } - /// # use tracing_core::{span::{Id, Attributes, Record}, Metadata}; - /// # impl tracing_core::Subscriber for MySubscriber { - /// # fn new_span(&self, _: &Attributes) -> Id { Id::from_u64(0) } - /// # fn record(&self, _: &Id, _: &Record) {} - /// # fn event(&self, _: &tracing_core::Event) {} - /// # fn record_follows_from(&self, _: &Id, _: &Id) {} - /// # fn enabled(&self, _: &Metadata) -> bool { false } - /// # fn enter(&self, _: &Id) {} - /// # fn exit(&self, _: &Id) {} - /// # } - /// let subscriber = FooLayer::new() - /// .with_subscriber(MySubscriber::new()); - ///``` - /// - /// [`Subscriber`]: https://docs.rs/tracing-core/latest/tracing_core/trait.Subscriber.html - fn with_subscriber(mut self, mut inner: S) -> Layered<Self, S> - where - Self: Sized, - { - let inner_has_layer_filter = filter::subscriber_has_plf(&inner); - self.on_layer(&mut inner); - Layered::new(self, inner, inner_has_layer_filter) - } - - /// Combines `self` with a [`Filter`], returning a [`Filtered`] layer. - /// - /// The [`Filter`] will control which spans and events are enabled for - /// this layer. See [the trait-level documentation][plf] for details on - /// per-layer filtering. - /// - /// [`Filtered`]: crate::filter::Filtered - /// [plf]: #per-layer-filtering - #[cfg(all(feature = "registry", feature = "std"))] - #[cfg_attr(docsrs, doc(cfg(all(feature = "registry", feature = "std"))))] - fn with_filter<F>(self, filter: F) -> filter::Filtered<Self, F, S> - where - Self: Sized, - F: Filter<S>, - { - filter::Filtered::new(self, filter) - } - - #[doc(hidden)] - unsafe fn downcast_raw(&self, id: TypeId) -> Option<*const ()> { - if id == TypeId::of::<Self>() { - Some(self as *const _ as *const ()) - } else { - None - } - } -} - -feature! { - #![all(feature = "registry", feature = "std")] - /// A per-[`Layer`] filter that determines whether a span or event is enabled - /// for an individual layer. - /// - /// See [the module-level documentation][plf] for details on using [`Filter`]s. - /// - /// [plf]: crate::layer#per-layer-filtering - #[cfg_attr(docsrs, doc(notable_trait))] - pub trait Filter<S> { - /// Returns `true` if this layer is interested in a span or event with the - /// given [`Metadata`] in the current [`Context`], similarly to - /// [`Subscriber::enabled`]. - /// - /// If this returns `false`, the span or event will be disabled _for the - /// wrapped [`Layer`]_. Unlike [`Layer::enabled`], the span or event will - /// still be recorded if any _other_ layers choose to enable it. However, - /// the layer [filtered] by this filter will skip recording that span or - /// event. - /// - /// If all layers indicate that they do not wish to see this span or event, - /// it will be disabled. - /// - /// [`metadata`]: tracing_core::Metadata - /// [`Subscriber::enabled`]: tracing_core::Subscriber::enabled - /// [filtered]: crate::filter::Filtered - fn enabled(&self, meta: &Metadata<'_>, cx: &Context<'_, S>) -> bool; - - /// Returns an [`Interest`] indicating whether this layer will [always], - /// [sometimes], or [never] be interested in the given [`Metadata`]. - /// - /// When a given callsite will [always] or [never] be enabled, the results - /// of evaluating the filter may be cached for improved performance. - /// Therefore, if a filter is capable of determining that it will always or - /// never enable a particular callsite, providing an implementation of this - /// function is recommended. - /// - /// <pre class="ignore" style="white-space:normal;font:inherit;"> - /// <strong>Note</strong>: If a <code>Filter</code> will perform - /// <em>dynamic filtering</em> that depends on the current context in which - /// a span or event was observered (e.g. only enabling an event when it - /// occurs within a particular span), it <strong>must</strong> return - /// <code>Interest::sometimes()</code> from this method. If it returns - /// <code>Interest::always()</code> or <code>Interest::never()</code>, the - /// <code>enabled</code> method may not be called when a particular instance - /// of that span or event is recorded. - /// </pre> - /// - /// This method is broadly similar to [`Subscriber::register_callsite`]; - /// however, since the returned value represents only the interest of - /// *this* layer, the resulting behavior is somewhat different. - /// - /// If a [`Subscriber`] returns [`Interest::always()`][always] or - /// [`Interest::never()`][never] for a given [`Metadata`], its [`enabled`] - /// method is then *guaranteed* to never be called for that callsite. On the - /// other hand, when a `Filter` returns [`Interest::always()`][always] or - /// [`Interest::never()`][never] for a callsite, _other_ [`Layer`]s may have - /// differing interests in that callsite. If this is the case, the callsite - /// will recieve [`Interest::sometimes()`][sometimes], and the [`enabled`] - /// method will still be called for that callsite when it records a span or - /// event. - /// - /// Returning [`Interest::always()`][always] or [`Interest::never()`][never] from - /// `Filter::callsite_enabled` will permanently enable or disable a - /// callsite (without requiring subsequent calls to [`enabled`]) if and only - /// if the following is true: - /// - /// - all [`Layer`]s that comprise the subscriber include `Filter`s - /// (this includes a tree of [`Layered`] layers that share the same - /// `Filter`) - /// - all those `Filter`s return the same [`Interest`]. - /// - /// For example, if a [`Subscriber`] consists of two [`Filtered`] layers, - /// and both of those layers return [`Interest::never()`][never], that - /// callsite *will* never be enabled, and the [`enabled`] methods of those - /// [`Filter`]s will not be called. - /// - /// ## Default Implementation - /// - /// The default implementation of this method assumes that the - /// `Filter`'s [`enabled`] method _may_ perform dynamic filtering, and - /// returns [`Interest::sometimes()`][sometimes], to ensure that [`enabled`] - /// is called to determine whether a particular _instance_ of the callsite - /// is enabled in the current context. If this is *not* the case, and the - /// `Filter`'s [`enabled`] method will always return the same result - /// for a particular [`Metadata`], this method can be overridden as - /// follows: - /// - /// ``` - /// use tracing_subscriber::layer; - /// use tracing_core::{Metadata, subscriber::Interest}; - /// - /// struct MyFilter { - /// // ... - /// } - /// - /// impl MyFilter { - /// // The actual logic for determining whether a `Metadata` is enabled - /// // must be factored out from the `enabled` method, so that it can be - /// // called without a `Context` (which is not provided to the - /// // `callsite_enabled` method). - /// fn is_enabled(&self, metadata: &Metadata<'_>) -> bool { - /// // ... - /// # drop(metadata); true - /// } - /// } - /// - /// impl<S> layer::Filter<S> for MyFilter { - /// fn enabled(&self, metadata: &Metadata<'_>, _: &layer::Context<'_, S>) -> bool { - /// // Even though we are implementing `callsite_enabled`, we must still provide a - /// // working implementation of `enabled`, as returning `Interest::always()` or - /// // `Interest::never()` will *allow* caching, but will not *guarantee* it. - /// // Other filters may still return `Interest::sometimes()`, so we may be - /// // asked again in `enabled`. - /// self.is_enabled(metadata) - /// } - /// - /// fn callsite_enabled(&self, metadata: &'static Metadata<'static>) -> Interest { - /// // The result of `self.enabled(metadata, ...)` will always be - /// // the same for any given `Metadata`, so we can convert it into - /// // an `Interest`: - /// if self.is_enabled(metadata) { - /// Interest::always() - /// } else { - /// Interest::never() - /// } - /// } - /// } - /// ``` - /// - /// [`Metadata`]: tracing_core::Metadata - /// [`Interest`]: tracing_core::Interest - /// [always]: tracing_core::Interest::always - /// [sometimes]: tracing_core::Interest::sometimes - /// [never]: tracing_core::Interest::never - /// [`Subscriber::register_callsite`]: tracing_core::Subscriber::register_callsite - /// [`Subscriber`]: tracing_core::Subscriber - /// [`enabled`]: Filter::enabled - /// [`Filtered`]: crate::filter::Filtered - fn callsite_enabled(&self, meta: &'static Metadata<'static>) -> Interest { - let _ = meta; - Interest::sometimes() - } - - /// Returns an optional hint of the highest [verbosity level][level] that - /// this `Filter` will enable. - /// - /// If this method returns a [`LevelFilter`], it will be used as a hint to - /// determine the most verbose level that will be enabled. This will allow - /// spans and events which are more verbose than that level to be skipped - /// more efficiently. An implementation of this method is optional, but - /// strongly encouraged. - /// - /// If the maximum level the `Filter` will enable can change over the - /// course of its lifetime, it is free to return a different value from - /// multiple invocations of this method. However, note that changes in the - /// maximum level will **only** be reflected after the callsite [`Interest`] - /// cache is rebuilt, by calling the - /// [`tracing_core::callsite::rebuild_interest_cache`][rebuild] function. - /// Therefore, if the `Filter will change the value returned by this - /// method, it is responsible for ensuring that - /// [`rebuild_interest_cache`][rebuild] is called after the value of the max - /// level changes. - /// - /// ## Default Implementation - /// - /// By default, this method returns `None`, indicating that the maximum - /// level is unknown. - /// - /// [level]: tracing_core::metadata::Level - /// [`LevelFilter`]: crate::filter::LevelFilter - /// [`Interest`]: tracing_core::subscriber::Interest - /// [rebuild]: tracing_core::callsite::rebuild_interest_cache - fn max_level_hint(&self) -> Option<LevelFilter> { - None - } - } -} - -/// Extension trait adding a `with(Layer)` combinator to `Subscriber`s. -pub trait SubscriberExt: Subscriber + crate::sealed::Sealed { - /// Wraps `self` with the provided `layer`. - fn with<L>(self, layer: L) -> Layered<L, Self> - where - L: Layer<Self>, - Self: Sized, - { - layer.with_subscriber(self) - } -} - -/// A layer that does nothing. -#[derive(Clone, Debug, Default)] -pub struct Identity { - _p: (), -} - -// === impl Layer === - -impl<L, S> Layer<S> for Option<L> -where - L: Layer<S>, - S: Subscriber, -{ - fn on_layer(&mut self, subscriber: &mut S) { - if let Some(ref mut layer) = self { - layer.on_layer(subscriber) - } - } - - #[inline] - fn on_new_span(&self, attrs: &span::Attributes<'_>, id: &span::Id, ctx: Context<'_, S>) { - if let Some(ref inner) = self { - inner.on_new_span(attrs, id, ctx) - } - } - - #[inline] - fn register_callsite(&self, metadata: &'static Metadata<'static>) -> Interest { - match self { - Some(ref inner) => inner.register_callsite(metadata), - None => Interest::always(), - } - } - - #[inline] - fn enabled(&self, metadata: &Metadata<'_>, ctx: Context<'_, S>) -> bool { - match self { - Some(ref inner) => inner.enabled(metadata, ctx), - None => true, - } - } - - #[inline] - fn max_level_hint(&self) -> Option<LevelFilter> { - match self { - Some(ref inner) => inner.max_level_hint(), - None => None, - } - } - - #[inline] - fn on_record(&self, span: &span::Id, values: &span::Record<'_>, ctx: Context<'_, S>) { - if let Some(ref inner) = self { - inner.on_record(span, values, ctx); - } - } - - #[inline] - fn on_follows_from(&self, span: &span::Id, follows: &span::Id, ctx: Context<'_, S>) { - if let Some(ref inner) = self { - inner.on_follows_from(span, follows, ctx); - } - } - - #[inline] - fn on_event(&self, event: &Event<'_>, ctx: Context<'_, S>) { - if let Some(ref inner) = self { - inner.on_event(event, ctx); - } - } - - #[inline] - fn on_enter(&self, id: &span::Id, ctx: Context<'_, S>) { - if let Some(ref inner) = self { - inner.on_enter(id, ctx); - } - } - - #[inline] - fn on_exit(&self, id: &span::Id, ctx: Context<'_, S>) { - if let Some(ref inner) = self { - inner.on_exit(id, ctx); - } - } - - #[inline] - fn on_close(&self, id: span::Id, ctx: Context<'_, S>) { - if let Some(ref inner) = self { - inner.on_close(id, ctx); - } - } - - #[inline] - fn on_id_change(&self, old: &span::Id, new: &span::Id, ctx: Context<'_, S>) { - if let Some(ref inner) = self { - inner.on_id_change(old, new, ctx) - } - } - - #[doc(hidden)] - #[inline] - unsafe fn downcast_raw(&self, id: TypeId) -> Option<*const ()> { - if id == TypeId::of::<Self>() { - Some(self as *const _ as *const ()) - } else { - self.as_ref().and_then(|inner| inner.downcast_raw(id)) - } - } -} - -feature! { - #![any(feature = "std", feature = "alloc")] - - macro_rules! layer_impl_body { - () => { - #[inline] - fn on_layer(&mut self, subscriber: &mut S) { - self.deref_mut().on_layer(subscriber); - } - - #[inline] - fn on_new_span(&self, attrs: &span::Attributes<'_>, id: &span::Id, ctx: Context<'_, S>) { - self.deref().on_new_span(attrs, id, ctx) - } - - #[inline] - fn register_callsite(&self, metadata: &'static Metadata<'static>) -> Interest { - self.deref().register_callsite(metadata) - } - - #[inline] - fn enabled(&self, metadata: &Metadata<'_>, ctx: Context<'_, S>) -> bool { - self.deref().enabled(metadata, ctx) - } - - #[inline] - fn max_level_hint(&self) -> Option<LevelFilter> { - self.deref().max_level_hint() - } - - #[inline] - fn on_record(&self, span: &span::Id, values: &span::Record<'_>, ctx: Context<'_, S>) { - self.deref().on_record(span, values, ctx) - } - - #[inline] - fn on_follows_from(&self, span: &span::Id, follows: &span::Id, ctx: Context<'_, S>) { - self.deref().on_follows_from(span, follows, ctx) - } - - #[inline] - fn on_event(&self, event: &Event<'_>, ctx: Context<'_, S>) { - self.deref().on_event(event, ctx) - } - - #[inline] - fn on_enter(&self, id: &span::Id, ctx: Context<'_, S>) { - self.deref().on_enter(id, ctx) - } - - #[inline] - fn on_exit(&self, id: &span::Id, ctx: Context<'_, S>) { - self.deref().on_exit(id, ctx) - } - - #[inline] - fn on_close(&self, id: span::Id, ctx: Context<'_, S>) { - self.deref().on_close(id, ctx) - } - - #[inline] - fn on_id_change(&self, old: &span::Id, new: &span::Id, ctx: Context<'_, S>) { - self.deref().on_id_change(old, new, ctx) - } - - #[doc(hidden)] - #[inline] - unsafe fn downcast_raw(&self, id: TypeId) -> Option<*const ()> { - self.deref().downcast_raw(id) - } - }; - } - - impl<L, S> Layer<S> for Box<L> - where - L: Layer<S>, - S: Subscriber, - { - layer_impl_body! {} - } - - impl<S> Layer<S> for Box<dyn Layer<S> + Send + Sync> - where - S: Subscriber, - { - layer_impl_body! {} - } -} - -// === impl SubscriberExt === - -impl<S: Subscriber> crate::sealed::Sealed for S {} -impl<S: Subscriber> SubscriberExt for S {} - -// === impl Identity === - -impl<S: Subscriber> Layer<S> for Identity {} - -impl Identity { - /// Returns a new `Identity` layer. - pub fn new() -> Self { - Self { _p: () } - } -} |