diff options
Diffstat (limited to 'vendor/tracing-subscriber/src/layer')
| -rw-r--r-- | vendor/tracing-subscriber/src/layer/context.rs | 434 | ||||
| -rw-r--r-- | vendor/tracing-subscriber/src/layer/layered.rs | 554 | ||||
| -rw-r--r-- | vendor/tracing-subscriber/src/layer/mod.rs | 1891 | ||||
| -rw-r--r-- | vendor/tracing-subscriber/src/layer/tests.rs | 308 |
4 files changed, 3187 insertions, 0 deletions
diff --git a/vendor/tracing-subscriber/src/layer/context.rs b/vendor/tracing-subscriber/src/layer/context.rs new file mode 100644 index 000000000..46254994f --- /dev/null +++ b/vendor/tracing-subscriber/src/layer/context.rs @@ -0,0 +1,434 @@ +use tracing_core::{metadata::Metadata, span, subscriber::Subscriber, Event}; + +use crate::registry::{self, LookupSpan, SpanRef}; + +#[cfg(all(feature = "registry", feature = "std"))] +use crate::{filter::FilterId, registry::Registry}; +/// Represents information about the current context provided to [`Layer`]s by the +/// wrapped [`Subscriber`]. +/// +/// To access [stored data] keyed by a span ID, implementors of the `Layer` +/// trait should ensure that the `Subscriber` type parameter is *also* bound by the +/// [`LookupSpan`]: +/// +/// ```rust +/// use tracing::Subscriber; +/// use tracing_subscriber::{Layer, registry::LookupSpan}; +/// +/// pub struct MyLayer; +/// +/// impl<S> Layer<S> for MyLayer +/// where +/// S: Subscriber + for<'a> LookupSpan<'a>, +/// { +/// // ... +/// } +/// ``` +/// +/// [`Layer`]: super::Layer +/// [`Subscriber`]: tracing_core::Subscriber +/// [stored data]: crate::registry::SpanRef +/// [`LookupSpan`]: crate::registry::LookupSpan +#[derive(Debug)] +pub struct Context<'a, S> { + subscriber: Option<&'a S>, + /// The bitmask of all [`Filtered`] layers that currently apply in this + /// context. If there is only a single [`Filtered`] wrapping the layer that + /// produced this context, then this is that filter's ID. Otherwise, if we + /// are in a nested tree with multiple filters, this is produced by + /// [`and`]-ing together the [`FilterId`]s of each of the filters that wrap + /// the current layer. + /// + /// [`Filtered`]: crate::filter::Filtered + /// [`FilterId`]: crate::filter::FilterId + /// [`and`]: crate::filter::FilterId::and + #[cfg(all(feature = "registry", feature = "std"))] + filter: FilterId, +} + +// === impl Context === + +impl<'a, S> Context<'a, S> +where + S: Subscriber, +{ + pub(super) fn new(subscriber: &'a S) -> Self { + Self { + subscriber: Some(subscriber), + + #[cfg(feature = "registry")] + filter: FilterId::none(), + } + } + + /// Returns the wrapped subscriber's view of the current span. + #[inline] + pub fn current_span(&self) -> span::Current { + self.subscriber + .map(Subscriber::current_span) + // TODO: this would be more correct as "unknown", so perhaps + // `tracing-core` should make `Current::unknown()` public? + .unwrap_or_else(span::Current::none) + } + + /// Returns whether the wrapped subscriber would enable the current span. + #[inline] + pub fn enabled(&self, metadata: &Metadata<'_>) -> bool { + self.subscriber + .map(|subscriber| subscriber.enabled(metadata)) + // If this context is `None`, we are registering a callsite, so + // return `true` so that the layer does not incorrectly assume that + // the inner subscriber has disabled this metadata. + // TODO(eliza): would it be more correct for this to return an `Option`? + .unwrap_or(true) + } + + /// Records the provided `event` with the wrapped subscriber. + /// + /// # Notes + /// + /// - The subscriber is free to expect that the event's callsite has been + /// [registered][register], and may panic or fail to observe the event if this is + /// not the case. The `tracing` crate's macros ensure that all events are + /// registered, but if the event is constructed through other means, the + /// user is responsible for ensuring that [`register_callsite`][register] + /// has been called prior to calling this method. + /// - This does _not_ call [`enabled`] on the inner subscriber. If the + /// caller wishes to apply the wrapped subscriber's filter before choosing + /// whether to record the event, it may first call [`Context::enabled`] to + /// check whether the event would be enabled. This allows `Layer`s to + /// elide constructing the event if it would not be recorded. + /// + /// [register]: tracing_core::subscriber::Subscriber::register_callsite() + /// [`enabled`]: tracing_core::subscriber::Subscriber::enabled() + /// [`Context::enabled`]: Context::enabled() + #[inline] + pub fn event(&self, event: &Event<'_>) { + if let Some(subscriber) = self.subscriber { + subscriber.event(event); + } + } + + /// Returns a [`SpanRef`] for the parent span of the given [`Event`], if + /// it has a parent. + /// + /// If the event has an explicitly overridden parent, this method returns + /// a reference to that span. If the event's parent is the current span, + /// this returns a reference to the current span, if there is one. If this + /// returns `None`, then either the event's parent was explicitly set to + /// `None`, or the event's parent was defined contextually, but no span + /// is currently entered. + /// + /// Compared to [`Context::current_span`] and [`Context::lookup_current`], + /// this respects overrides provided by the [`Event`]. + /// + /// Compared to [`Event::parent`], this automatically falls back to the contextual + /// span, if required. + /// + /// ```rust + /// use tracing::{Event, Subscriber}; + /// use tracing_subscriber::{ + /// layer::{Context, Layer}, + /// prelude::*, + /// registry::LookupSpan, + /// }; + /// + /// struct PrintingLayer; + /// impl<S> Layer<S> for PrintingLayer + /// where + /// S: Subscriber + for<'lookup> LookupSpan<'lookup>, + /// { + /// fn on_event(&self, event: &Event, ctx: Context<S>) { + /// let span = ctx.event_span(event); + /// println!("Event in span: {:?}", span.map(|s| s.name())); + /// } + /// } + /// + /// tracing::subscriber::with_default(tracing_subscriber::registry().with(PrintingLayer), || { + /// tracing::info!("no span"); + /// // Prints: Event in span: None + /// + /// let span = tracing::info_span!("span"); + /// tracing::info!(parent: &span, "explicitly specified"); + /// // Prints: Event in span: Some("span") + /// + /// let _guard = span.enter(); + /// tracing::info!("contextual span"); + /// // Prints: Event in span: Some("span") + /// }); + /// ``` + /// + /// <pre class="ignore" style="white-space:normal;font:inherit;"> + /// <strong>Note</strong>: This requires the wrapped subscriber to + /// implement the <a href="../registry/trait.LookupSpan.html"><code> + /// LookupSpan</code></a> trait. See the documentation on + /// <a href="./struct.Context.html"><code>Context</code>'s + /// declaration</a> for details. + /// </pre> + #[inline] + pub fn event_span(&self, event: &Event<'_>) -> Option<SpanRef<'_, S>> + where + S: for<'lookup> LookupSpan<'lookup>, + { + if event.is_root() { + None + } else if event.is_contextual() { + self.lookup_current() + } else { + // TODO(eliza): this should handle parent IDs + event.parent().and_then(|id| self.span(id)) + } + } + + /// Returns metadata for the span with the given `id`, if it exists. + /// + /// If this returns `None`, then no span exists for that ID (either it has + /// closed or the ID is invalid). + #[inline] + pub fn metadata(&self, id: &span::Id) -> Option<&'static Metadata<'static>> + where + S: for<'lookup> LookupSpan<'lookup>, + { + let span = self.span(id)?; + Some(span.metadata()) + } + + /// Returns [stored data] for the span with the given `id`, if it exists. + /// + /// If this returns `None`, then no span exists for that ID (either it has + /// closed or the ID is invalid). + /// + /// <pre class="ignore" style="white-space:normal;font:inherit;"> + /// <strong>Note</strong>: This requires the wrapped subscriber to + /// implement the <a href="../registry/trait.LookupSpan.html"><code> + /// LookupSpan</code></a> trait. See the documentation on + /// <a href="./struct.Context.html"><code>Context</code>'s + /// declaration</a> for details. + /// </pre> + /// + /// [stored data]: crate::registry::SpanRef + #[inline] + pub fn span(&self, id: &span::Id) -> Option<registry::SpanRef<'_, S>> + where + S: for<'lookup> LookupSpan<'lookup>, + { + let span = self.subscriber.as_ref()?.span(id)?; + + #[cfg(all(feature = "registry", feature = "std"))] + return span.try_with_filter(self.filter); + + #[cfg(not(feature = "registry"))] + Some(span) + } + + /// Returns `true` if an active span exists for the given `Id`. + /// + /// <pre class="ignore" style="white-space:normal;font:inherit;"> + /// <strong>Note</strong>: This requires the wrapped subscriber to + /// implement the <a href="../registry/trait.LookupSpan.html"><code> + /// LookupSpan</code></a> trait. See the documentation on + /// <a href="./struct.Context.html"><code>Context</code>'s + /// declaration</a> for details. + /// </pre> + #[inline] + pub fn exists(&self, id: &span::Id) -> bool + where + S: for<'lookup> LookupSpan<'lookup>, + { + self.subscriber.as_ref().and_then(|s| s.span(id)).is_some() + } + + /// Returns [stored data] for the span that the wrapped subscriber considers + /// to be the current. + /// + /// If this returns `None`, then we are not currently within a span. + /// + /// <pre class="ignore" style="white-space:normal;font:inherit;"> + /// <strong>Note</strong>: This requires the wrapped subscriber to + /// implement the <a href="../registry/trait.LookupSpan.html"><code> + /// LookupSpan</code></a> trait. See the documentation on + /// <a href="./struct.Context.html"><code>Context</code>'s + /// declaration</a> for details. + /// </pre> + /// + /// [stored data]: crate::registry::SpanRef + #[inline] + pub fn lookup_current(&self) -> Option<registry::SpanRef<'_, S>> + where + S: for<'lookup> LookupSpan<'lookup>, + { + let subscriber = *self.subscriber.as_ref()?; + let current = subscriber.current_span(); + let id = current.id()?; + let span = subscriber.span(id); + debug_assert!( + span.is_some(), + "the subscriber should have data for the current span ({:?})!", + id, + ); + + // If we found a span, and our per-layer filter enables it, return that + // span! + #[cfg(all(feature = "registry", feature = "std"))] + { + if let Some(span) = span?.try_with_filter(self.filter) { + Some(span) + } else { + // Otherwise, the span at the *top* of the stack is disabled by + // per-layer filtering, but there may be additional spans in the stack. + // + // Currently, `LookupSpan` doesn't have a nice way of exposing access to + // the whole span stack. However, if we can downcast the innermost + // subscriber to a a `Registry`, we can iterate over its current span + // stack. + // + // TODO(eliza): when https://github.com/tokio-rs/tracing/issues/1459 is + // implemented, change this to use that instead... + self.lookup_current_filtered(subscriber) + } + } + + #[cfg(not(feature = "registry"))] + span + } + + /// Slow path for when the current span is disabled by PLF and we have a + /// registry. + // This is called by `lookup_current` in the case that per-layer filtering + // is in use. `lookup_current` is allowed to be inlined, but this method is + // factored out to prevent the loop and (potentially-recursive) subscriber + // downcasting from being inlined if `lookup_current` is inlined. + #[inline(never)] + #[cfg(all(feature = "registry", feature = "std"))] + fn lookup_current_filtered<'lookup>( + &self, + subscriber: &'lookup S, + ) -> Option<registry::SpanRef<'lookup, S>> + where + S: LookupSpan<'lookup>, + { + let registry = (subscriber as &dyn Subscriber).downcast_ref::<Registry>()?; + registry + .span_stack() + .iter() + .find_map(|id| subscriber.span(id)?.try_with_filter(self.filter)) + } + + /// Returns an iterator over the [stored data] for all the spans in the + /// current context, starting with the specified span and ending with the + /// root of the trace tree and ending with the current span. + /// + /// <pre class="ignore" style="white-space:normal;font:inherit;"> + /// <strong>Note</strong>: Compared to <a href="#method.scope"><code>scope</code></a> this + /// returns the spans in reverse order (from leaf to root). Use + /// <a href="../registry/struct.Scope.html#method.from_root"><code>Scope::from_root</code></a> + /// in case root-to-leaf ordering is desired. + /// </pre> + /// + /// <pre class="ignore" style="white-space:normal;font:inherit;"> + /// <strong>Note</strong>: This requires the wrapped subscriber to + /// implement the <a href="../registry/trait.LookupSpan.html"><code> + /// LookupSpan</code></a> trait. See the documentation on + /// <a href="./struct.Context.html"><code>Context</code>'s + /// declaration</a> for details. + /// </pre> + /// + /// [stored data]: crate::registry::SpanRef + pub fn span_scope(&self, id: &span::Id) -> Option<registry::Scope<'_, S>> + where + S: for<'lookup> LookupSpan<'lookup>, + { + Some(self.span(id)?.scope()) + } + + /// Returns an iterator over the [stored data] for all the spans in the + /// current context, starting with the parent span of the specified event, + /// and ending with the root of the trace tree and ending with the current span. + /// + /// <pre class="ignore" style="white-space:normal;font:inherit;"> + /// <strong>Note</strong>: Compared to <a href="#method.scope"><code>scope</code></a> this + /// returns the spans in reverse order (from leaf to root). Use + /// <a href="../registry/struct.Scope.html#method.from_root"><code>Scope::from_root</code></a> + /// in case root-to-leaf ordering is desired. + /// </pre> + /// + /// <pre class="ignore" style="white-space:normal;font:inherit;"> + /// <strong>Note</strong>: This requires the wrapped subscriber to + /// implement the <a href="../registry/trait.LookupSpan.html"><code> + /// LookupSpan</code></a> trait. See the documentation on + /// <a href="./struct.Context.html"><code>Context</code>'s + /// declaration</a> for details. + /// </pre> + /// + /// [stored data]: crate::registry::SpanRef + pub fn event_scope(&self, event: &Event<'_>) -> Option<registry::Scope<'_, S>> + where + S: for<'lookup> LookupSpan<'lookup>, + { + Some(self.event_span(event)?.scope()) + } + + #[cfg(all(feature = "registry", feature = "std"))] + pub(crate) fn with_filter(self, filter: FilterId) -> Self { + // If we already have our own `FilterId`, combine it with the provided + // one. That way, the new `FilterId` will consider a span to be disabled + // if it was disabled by the given `FilterId` *or* any `FilterId`s for + // layers "above" us in the stack. + // + // See the doc comment for `FilterId::and` for details. + let filter = self.filter.and(filter); + Self { filter, ..self } + } + + #[cfg(all(feature = "registry", feature = "std"))] + pub(crate) fn is_enabled_for(&self, span: &span::Id, filter: FilterId) -> bool + where + S: for<'lookup> LookupSpan<'lookup>, + { + self.is_enabled_inner(span, filter).unwrap_or(false) + } + + #[cfg(all(feature = "registry", feature = "std"))] + pub(crate) fn if_enabled_for(self, span: &span::Id, filter: FilterId) -> Option<Self> + where + S: for<'lookup> LookupSpan<'lookup>, + { + if self.is_enabled_inner(span, filter)? { + Some(self.with_filter(filter)) + } else { + None + } + } + + #[cfg(all(feature = "registry", feature = "std"))] + fn is_enabled_inner(&self, span: &span::Id, filter: FilterId) -> Option<bool> + where + S: for<'lookup> LookupSpan<'lookup>, + { + Some(self.span(span)?.is_enabled_for(filter)) + } +} + +impl<'a, S> Context<'a, S> { + pub(crate) fn none() -> Self { + Self { + subscriber: None, + + #[cfg(feature = "registry")] + filter: FilterId::none(), + } + } +} + +impl<'a, S> Clone for Context<'a, S> { + #[inline] + fn clone(&self) -> Self { + let subscriber = self.subscriber.as_ref().copied(); + Context { + subscriber, + + #[cfg(all(feature = "registry", feature = "std"))] + filter: self.filter, + } + } +} diff --git a/vendor/tracing-subscriber/src/layer/layered.rs b/vendor/tracing-subscriber/src/layer/layered.rs new file mode 100644 index 000000000..f09c58c97 --- /dev/null +++ b/vendor/tracing-subscriber/src/layer/layered.rs @@ -0,0 +1,554 @@ +use tracing_core::{metadata::Metadata, span, Dispatch, Event, Interest, LevelFilter, Subscriber}; + +use crate::{ + filter, + layer::{Context, Layer}, + registry::LookupSpan, +}; +#[cfg(all(feature = "registry", feature = "std"))] +use crate::{filter::FilterId, registry::Registry}; +use core::{ + any::{Any, TypeId}, + cmp, fmt, + marker::PhantomData, +}; + +/// A [`Subscriber`] composed of a `Subscriber` wrapped by one or more +/// [`Layer`]s. +/// +/// [`Layer`]: crate::Layer +/// [`Subscriber`]: tracing_core::Subscriber +#[derive(Clone)] +pub struct Layered<L, I, S = I> { + /// The layer. + layer: L, + + /// The inner value that `self.layer` was layered onto. + /// + /// If this is also a `Layer`, then this `Layered` will implement `Layer`. + /// If this is a `Subscriber`, then this `Layered` will implement + /// `Subscriber` instead. + inner: I, + + // These booleans are used to determine how to combine `Interest`s and max + // level hints when per-layer filters are in use. + /// Is `self.inner` a `Registry`? + /// + /// If so, when combining `Interest`s, we want to "bubble up" its + /// `Interest`. + inner_is_registry: bool, + + /// Does `self.layer` have per-layer filters? + /// + /// This will be true if: + /// - `self.inner` is a `Filtered`. + /// - `self.inner` is a tree of `Layered`s where _all_ arms of those + /// `Layered`s have per-layer filters. + /// + /// Otherwise, if it's a `Layered` with one per-layer filter in one branch, + /// but a non-per-layer-filtered layer in the other branch, this will be + /// _false_, because the `Layered` is already handling the combining of + /// per-layer filter `Interest`s and max level hints with its non-filtered + /// `Layer`. + has_layer_filter: bool, + + /// Does `self.inner` have per-layer filters? + /// + /// This is determined according to the same rules as + /// `has_layer_filter` above. + inner_has_layer_filter: bool, + _s: PhantomData<fn(S)>, +} + +// === impl Layered === + +impl<L, S> Layered<L, S> +where + L: Layer<S>, + S: Subscriber, +{ + /// Returns `true` if this [`Subscriber`] is the same type as `T`. + pub fn is<T: Any>(&self) -> bool { + self.downcast_ref::<T>().is_some() + } + + /// Returns some reference to this [`Subscriber`] value if it is of type `T`, + /// or `None` if it isn't. + pub fn downcast_ref<T: Any>(&self) -> Option<&T> { + unsafe { + let raw = self.downcast_raw(TypeId::of::<T>())?; + if raw.is_null() { + None + } else { + Some(&*(raw as *const T)) + } + } + } +} + +impl<L, S> Subscriber for Layered<L, S> +where + L: Layer<S>, + S: Subscriber, +{ + fn register_callsite(&self, metadata: &'static Metadata<'static>) -> Interest { + self.pick_interest(self.layer.register_callsite(metadata), || { + self.inner.register_callsite(metadata) + }) + } + + fn enabled(&self, metadata: &Metadata<'_>) -> bool { + if self.layer.enabled(metadata, self.ctx()) { + // if the outer layer enables the callsite metadata, ask the subscriber. + self.inner.enabled(metadata) + } else { + // otherwise, the callsite is disabled by the layer + + // If per-layer filters are in use, and we are short-circuiting + // (rather than calling into the inner type), clear the current + // per-layer filter `enabled` state. + #[cfg(feature = "registry")] + filter::FilterState::clear_enabled(); + + false + } + } + + fn max_level_hint(&self) -> Option<LevelFilter> { + self.pick_level_hint( + self.layer.max_level_hint(), + self.inner.max_level_hint(), + super::subscriber_is_none(&self.inner), + ) + } + + fn new_span(&self, span: &span::Attributes<'_>) -> span::Id { + let id = self.inner.new_span(span); + self.layer.on_new_span(span, &id, self.ctx()); + id + } + + fn record(&self, span: &span::Id, values: &span::Record<'_>) { + self.inner.record(span, values); + self.layer.on_record(span, values, self.ctx()); + } + + fn record_follows_from(&self, span: &span::Id, follows: &span::Id) { + self.inner.record_follows_from(span, follows); + self.layer.on_follows_from(span, follows, self.ctx()); + } + + fn event_enabled(&self, event: &Event<'_>) -> bool { + if self.layer.event_enabled(event, self.ctx()) { + // if the outer layer enables the event, ask the inner subscriber. + self.inner.event_enabled(event) + } else { + // otherwise, the event is disabled by this layer + false + } + } + + fn event(&self, event: &Event<'_>) { + self.inner.event(event); + self.layer.on_event(event, self.ctx()); + } + + fn enter(&self, span: &span::Id) { + self.inner.enter(span); + self.layer.on_enter(span, self.ctx()); + } + + fn exit(&self, span: &span::Id) { + self.inner.exit(span); + self.layer.on_exit(span, self.ctx()); + } + + fn clone_span(&self, old: &span::Id) -> span::Id { + let new = self.inner.clone_span(old); + if &new != old { + self.layer.on_id_change(old, &new, self.ctx()) + }; + new + } + + #[inline] + fn drop_span(&self, id: span::Id) { + self.try_close(id); + } + + fn try_close(&self, id: span::Id) -> bool { + #[cfg(all(feature = "registry", feature = "std"))] + let subscriber = &self.inner as &dyn Subscriber; + #[cfg(all(feature = "registry", feature = "std"))] + let mut guard = subscriber + .downcast_ref::<Registry>() + .map(|registry| registry.start_close(id.clone())); + if self.inner.try_close(id.clone()) { + // If we have a registry's close guard, indicate that the span is + // closing. + #[cfg(all(feature = "registry", feature = "std"))] + { + if let Some(g) = guard.as_mut() { + g.set_closing() + }; + } + + self.layer.on_close(id, self.ctx()); + true + } else { + false + } + } + + #[inline] + fn current_span(&self) -> span::Current { + self.inner.current_span() + } + + #[doc(hidden)] + unsafe fn downcast_raw(&self, id: TypeId) -> Option<*const ()> { + // Unlike the implementation of `Layer` for `Layered`, we don't have to + // handle the "magic PLF downcast marker" here. If a `Layered` + // implements `Subscriber`, we already know that the `inner` branch is + // going to contain something that doesn't have per-layer filters (the + // actual root `Subscriber`). Thus, a `Layered` that implements + // `Subscriber` will always be propagating the root subscriber's + // `Interest`/level hint, even if it includes a `Layer` that has + // per-layer filters, because it will only ever contain layers where + // _one_ child has per-layer filters. + // + // The complex per-layer filter detection logic is only relevant to + // *trees* of layers, which involve the `Layer` implementation for + // `Layered`, not *lists* of layers, where every `Layered` implements + // `Subscriber`. Of course, a linked list can be thought of as a + // degenerate tree...but luckily, we are able to make a type-level + // distinction between individual `Layered`s that are definitely + // list-shaped (their inner child implements `Subscriber`), and + // `Layered`s that might be tree-shaped (the inner child is also a + // `Layer`). + + // If downcasting to `Self`, return a pointer to `self`. + if id == TypeId::of::<Self>() { + return Some(self as *const _ as *const ()); + } + + self.layer + .downcast_raw(id) + .or_else(|| self.inner.downcast_raw(id)) + } +} + +impl<S, A, B> Layer<S> for Layered<A, B, S> +where + A: Layer<S>, + B: Layer<S>, + S: Subscriber, +{ + fn on_register_dispatch(&self, subscriber: &Dispatch) { + self.layer.on_register_dispatch(subscriber); + self.inner.on_register_dispatch(subscriber); + } + + fn on_layer(&mut self, subscriber: &mut S) { + self.layer.on_layer(subscriber); + self.inner.on_layer(subscriber); + } + + fn register_callsite(&self, metadata: &'static Metadata<'static>) -> Interest { + self.pick_interest(self.layer.register_callsite(metadata), || { + self.inner.register_callsite(metadata) + }) + } + + fn enabled(&self, metadata: &Metadata<'_>, ctx: Context<'_, S>) -> bool { + if self.layer.enabled(metadata, ctx.clone()) { + // if the outer subscriber enables the callsite metadata, ask the inner layer. + self.inner.enabled(metadata, ctx) + } else { + // otherwise, the callsite is disabled by this layer + false + } + } + + fn max_level_hint(&self) -> Option<LevelFilter> { + self.pick_level_hint( + self.layer.max_level_hint(), + self.inner.max_level_hint(), + super::layer_is_none(&self.inner), + ) + } + + #[inline] + fn on_new_span(&self, attrs: &span::Attributes<'_>, id: &span::Id, ctx: Context<'_, S>) { + self.inner.on_new_span(attrs, id, ctx.clone()); + self.layer.on_new_span(attrs, id, ctx); + } + + #[inline] + fn on_record(&self, span: &span::Id, values: &span::Record<'_>, ctx: Context<'_, S>) { + self.inner.on_record(span, values, ctx.clone()); + self.layer.on_record(span, values, ctx); + } + + #[inline] + fn on_follows_from(&self, span: &span::Id, follows: &span::Id, ctx: Context<'_, S>) { + self.inner.on_follows_from(span, follows, ctx.clone()); + self.layer.on_follows_from(span, follows, ctx); + } + + #[inline] + fn event_enabled(&self, event: &Event<'_>, ctx: Context<'_, S>) -> bool { + if self.layer.event_enabled(event, ctx.clone()) { + // if the outer layer enables the event, ask the inner subscriber. + self.inner.event_enabled(event, ctx) + } else { + // otherwise, the event is disabled by this layer + false + } + } + + #[inline] + fn on_event(&self, event: &Event<'_>, ctx: Context<'_, S>) { + self.inner.on_event(event, ctx.clone()); + self.layer.on_event(event, ctx); + } + + #[inline] + fn on_enter(&self, id: &span::Id, ctx: Context<'_, S>) { + self.inner.on_enter(id, ctx.clone()); + self.layer.on_enter(id, ctx); + } + + #[inline] + fn on_exit(&self, id: &span::Id, ctx: Context<'_, S>) { + self.inner.on_exit(id, ctx.clone()); + self.layer.on_exit(id, ctx); + } + + #[inline] + fn on_close(&self, id: span::Id, ctx: Context<'_, S>) { + self.inner.on_close(id.clone(), ctx.clone()); + self.layer.on_close(id, ctx); + } + + #[inline] + fn on_id_change(&self, old: &span::Id, new: &span::Id, ctx: Context<'_, S>) { + self.inner.on_id_change(old, new, ctx.clone()); + self.layer.on_id_change(old, new, ctx); + } + + #[doc(hidden)] + unsafe fn downcast_raw(&self, id: TypeId) -> Option<*const ()> { + match id { + // If downcasting to `Self`, return a pointer to `self`. + id if id == TypeId::of::<Self>() => Some(self as *const _ as *const ()), + + // Oh, we're looking for per-layer filters! + // + // This should only happen if we are inside of another `Layered`, + // and it's trying to determine how it should combine `Interest`s + // and max level hints. + // + // In that case, this `Layered` should be considered to be + // "per-layer filtered" if *both* the outer layer and the inner + // layer/subscriber have per-layer filters. Otherwise, this `Layered + // should *not* be considered per-layer filtered (even if one or the + // other has per layer filters). If only one `Layer` is per-layer + // filtered, *this* `Layered` will handle aggregating the `Interest` + // and level hints on behalf of its children, returning the + // aggregate (which is the value from the &non-per-layer-filtered* + // child). + // + // Yes, this rule *is* slightly counter-intuitive, but it's + // necessary due to a weird edge case that can occur when two + // `Layered`s where one side is per-layer filtered and the other + // isn't are `Layered` together to form a tree. If we didn't have + // this rule, we would actually end up *ignoring* `Interest`s from + // the non-per-layer-filtered layers, since both branches would + // claim to have PLF. + // + // If you don't understand this...that's fine, just don't mess with + // it. :) + id if filter::is_plf_downcast_marker(id) => { + self.layer.downcast_raw(id).and(self.inner.downcast_raw(id)) + } + + // Otherwise, try to downcast both branches normally... + _ => self + .layer + .downcast_raw(id) + .or_else(|| self.inner.downcast_raw(id)), + } + } +} + +impl<'a, L, S> LookupSpan<'a> for Layered<L, S> +where + S: Subscriber + LookupSpan<'a>, +{ + type Data = S::Data; + + fn span_data(&'a self, id: &span::Id) -> Option<Self::Data> { + self.inner.span_data(id) + } + + #[cfg(all(feature = "registry", feature = "std"))] + fn register_filter(&mut self) -> FilterId { + self.inner.register_filter() + } +} + +impl<L, S> Layered<L, S> +where + S: Subscriber, +{ + fn ctx(&self) -> Context<'_, S> { + Context::new(&self.inner) + } +} + +impl<A, B, S> Layered<A, B, S> +where + A: Layer<S>, + S: Subscriber, +{ + pub(super) fn new(layer: A, inner: B, inner_has_layer_filter: bool) -> Self { + #[cfg(all(feature = "registry", feature = "std"))] + let inner_is_registry = TypeId::of::<S>() == TypeId::of::<crate::registry::Registry>(); + + #[cfg(not(all(feature = "registry", feature = "std")))] + let inner_is_registry = false; + + let inner_has_layer_filter = inner_has_layer_filter || inner_is_registry; + let has_layer_filter = filter::layer_has_plf(&layer); + Self { + layer, + inner, + has_layer_filter, + inner_has_layer_filter, + inner_is_registry, + _s: PhantomData, + } + } + + fn pick_interest(&self, outer: Interest, inner: impl FnOnce() -> Interest) -> Interest { + if self.has_layer_filter { + return inner(); + } + + // If the outer layer has disabled the callsite, return now so that + // the inner layer/subscriber doesn't get its hopes up. + if outer.is_never() { + // If per-layer filters are in use, and we are short-circuiting + // (rather than calling into the inner type), clear the current + // per-layer filter interest state. + #[cfg(feature = "registry")] + filter::FilterState::take_interest(); + + return outer; + } + + // The `inner` closure will call `inner.register_callsite()`. We do this + // before the `if` statement to ensure that the inner subscriber is + // informed that the callsite exists regardless of the outer layer's + // filtering decision. + let inner = inner(); + if outer.is_sometimes() { + // if this interest is "sometimes", return "sometimes" to ensure that + // filters are reevaluated. + return outer; + } + + // If there is a per-layer filter in the `inner` stack, and it returns + // `never`, change the interest to `sometimes`, because the `outer` + // layer didn't return `never`. This means that _some_ layer still wants + // to see that callsite, even though the inner stack's per-layer filter + // didn't want it. Therefore, returning `sometimes` will ensure + // `enabled` is called so that the per-layer filter can skip that + // span/event, while the `outer` layer still gets to see it. + if inner.is_never() && self.inner_has_layer_filter { + return Interest::sometimes(); + } + + // otherwise, allow the inner subscriber or collector to weigh in. + inner + } + + fn pick_level_hint( + &self, + outer_hint: Option<LevelFilter>, + inner_hint: Option<LevelFilter>, + inner_is_none: bool, + ) -> Option<LevelFilter> { + if self.inner_is_registry { + return outer_hint; + } + + if self.has_layer_filter && self.inner_has_layer_filter { + return Some(cmp::max(outer_hint?, inner_hint?)); + } + + if self.has_layer_filter && inner_hint.is_none() { + return None; + } + + if self.inner_has_layer_filter && outer_hint.is_none() { + return None; + } + + // If the layer is `Option::None`, then we + // want to short-circuit the layer underneath, if it + // returns `None`, to override the `None` layer returning + // `Some(OFF)`, which should ONLY apply when there are + // no other layers that return `None`. Note this + // `None` does not == `Some(TRACE)`, it means + // something more like: "whatever all the other + // layers agree on, default to `TRACE` if none + // have an opinion". We also choose do this AFTER + // we check for per-layer filters, which + // have their own logic. + // + // Also note that this does come at some perf cost, but + // this function is only called on initialization and + // subscriber reloading. + if super::layer_is_none(&self.layer) { + return cmp::max(outer_hint, Some(inner_hint?)); + } + + // Similarly, if the layer on the inside is `None` and it returned an + // `Off` hint, we want to override that with the outer hint. + if inner_is_none && inner_hint == Some(LevelFilter::OFF) { + return outer_hint; + } + + cmp::max(outer_hint, inner_hint) + } +} + +impl<A, B, S> fmt::Debug for Layered<A, B, S> +where + A: fmt::Debug, + B: fmt::Debug, +{ + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + #[cfg(all(feature = "registry", feature = "std"))] + let alt = f.alternate(); + let mut s = f.debug_struct("Layered"); + // These additional fields are more verbose and usually only necessary + // for internal debugging purposes, so only print them if alternate mode + // is enabled. + + #[cfg(all(feature = "registry", feature = "std"))] + { + if alt { + s.field("inner_is_registry", &self.inner_is_registry) + .field("has_layer_filter", &self.has_layer_filter) + .field("inner_has_layer_filter", &self.inner_has_layer_filter); + } + } + + s.field("layer", &self.layer) + .field("inner", &self.inner) + .finish() + } +} diff --git a/vendor/tracing-subscriber/src/layer/mod.rs b/vendor/tracing-subscriber/src/layer/mod.rs new file mode 100644 index 000000000..bdc154301 --- /dev/null +++ b/vendor/tracing-subscriber/src/layer/mod.rs @@ -0,0 +1,1891 @@ +//! 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. +//! +//! ## Runtime Configuration With `Layer`s +//! +//! 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`] implementation 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; +//! 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)); +//! layer.with(subscriber) +//! } else { +//! layer +//! }; +//! +//! 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; +//! 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(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(()) } +//! ``` +//! +//! If a [`Layer`] may be one of several different types, note that [`Box<dyn +//! Layer<S> + Send + Sync>` implements `Layer`][box-impl]. +//! This may be used to erase the type of a [`Layer`]. +//! +//! For example, a function that configures a [`Layer`] to log to one of +//! several outputs might return a `Box<dyn Layer<S> + Send + Sync + 'static>`: +//! ``` +//! use tracing_subscriber::{ +//! Layer, +//! registry::LookupSpan, +//! prelude::*, +//! }; +//! use std::{path::PathBuf, fs::File, io}; +//! +//! /// Configures whether logs are emitted to a file, to stdout, or to stderr. +//! pub enum LogConfig { +//! File(PathBuf), +//! Stdout, +//! Stderr, +//! } +//! +//! impl LogConfig { +//! pub fn layer<S>(self) -> Box<dyn Layer<S> + Send + Sync + 'static> +//! where +//! S: tracing_core::Subscriber, +//! for<'a> S: LookupSpan<'a>, +//! { +//! // Shared configuration regardless of where logs are output to. +//! let fmt = tracing_subscriber::fmt::layer() +//! .with_target(true) +//! .with_thread_names(true); +//! +//! // Configure the writer based on the desired log target: +//! match self { +//! LogConfig::File(path) => { +//! let file = File::create(path).expect("failed to create log file"); +//! Box::new(fmt.with_writer(file)) +//! }, +//! LogConfig::Stdout => Box::new(fmt.with_writer(io::stdout)), +//! LogConfig::Stderr => Box::new(fmt.with_writer(io::stderr)), +//! } +//! } +//! } +//! +//! let config = LogConfig::Stdout; +//! tracing_subscriber::registry() +//! .with(config.layer()) +//! .init(); +//! ``` +//! +//! The [`Layer::boxed`] method is provided to make boxing a `Layer` +//! more convenient, but [`Box::new`] may be used as well. +//! +//! When the number of `Layer`s varies at runtime, note that a +//! [`Vec<L> where L: Layer` also implements `Layer`][vec-impl]. This +//! can be used to add a variable number of `Layer`s to a `Subscriber`: +//! +//! ``` +//! use tracing_subscriber::{Layer, prelude::*}; +//! struct MyLayer { +//! // ... +//! } +//! # impl MyLayer { fn new() -> Self { Self {} }} +//! +//! impl<S: tracing_core::Subscriber> Layer<S> for MyLayer { +//! // ... +//! } +//! +//! /// Returns how many layers we need +//! fn how_many_layers() -> usize { +//! // ... +//! # 3 +//! } +//! +//! // Create a variable-length `Vec` of layers +//! let mut layers = Vec::new(); +//! for _ in 0..how_many_layers() { +//! layers.push(MyLayer::new()); +//! } +//! +//! tracing_subscriber::registry() +//! .with(layers) +//! .init(); +//! ``` +//! +//! If a variable number of `Layer` is needed and those `Layer`s have +//! different types, a `Vec` of [boxed `Layer` trait objects][box-impl] may +//! be used. For example: +//! +//! ``` +//! use tracing_subscriber::{filter::LevelFilter, Layer, prelude::*}; +//! use std::fs::File; +//! # fn main() -> Result<(), Box<dyn std::error::Error>> { +//! struct Config { +//! enable_log_file: bool, +//! enable_stdout: bool, +//! enable_stderr: bool, +//! // ... +//! } +//! # impl Config { +//! # fn from_config_file()-> Result<Self, Box<dyn std::error::Error>> { +//! # // don't enable the log file so that the example doesn't actually create it +//! # Ok(Self { enable_log_file: false, enable_stdout: true, enable_stderr: true }) +//! # } +//! # } +//! +//! let cfg = Config::from_config_file()?; +//! +//! // Based on our dynamically loaded config file, create any number of layers: +//! let mut layers = Vec::new(); +//! +//! if cfg.enable_log_file { +//! let file = File::create("myapp.log")?; +//! let layer = tracing_subscriber::fmt::layer() +//! .with_thread_names(true) +//! .with_target(true) +//! .json() +//! .with_writer(file) +//! // Box the layer as a type-erased trait object, so that it can +//! // be pushed to the `Vec`. +//! .boxed(); +//! layers.push(layer); +//! } +//! +//! if cfg.enable_stdout { +//! let layer = tracing_subscriber::fmt::layer() +//! .pretty() +//! .with_filter(LevelFilter::INFO) +//! // Box the layer as a type-erased trait object, so that it can +//! // be pushed to the `Vec`. +//! .boxed(); +//! layers.push(layer); +//! } +//! +//! if cfg.enable_stdout { +//! let layer = tracing_subscriber::fmt::layer() +//! .with_target(false) +//! .with_filter(LevelFilter::WARN) +//! // Box the layer as a type-erased trait object, so that it can +//! // be pushed to the `Vec`. +//! .boxed(); +//! layers.push(layer); +//! } +//! +//! tracing_subscriber::registry() +//! .with(layers) +//! .init(); +//!# Ok(()) } +//! ``` +//! +//! Finally, if the number of layers _changes_ at runtime, a `Vec` of +//! subscribers can be used alongside the [`reload`](crate::reload) module to +//! add or remove subscribers dynamically at runtime. +//! +//! [option-impl]: Layer#impl-Layer<S>-for-Option<L> +//! [box-impl]: Layer#impl-Layer%3CS%3E-for-Box%3Cdyn%20Layer%3CS%3E%20+%20Send%20+%20Sync%3E +//! [vec-impl]: Layer#impl-Layer<S>-for-Vec<L> +//! [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. +//! +//! ### Enabling Interest +//! +//! Whenever an tracing event (or span) is emitted, it goes through a number of +//! steps to determine how and how much it should be processed. The earlier an +//! event is disabled, the less work has to be done to process the event, so +//! `Layer`s that implement filtering should attempt to disable unwanted +//! events as early as possible. In order, each event checks: +//! +//! - [`register_callsite`], once per callsite (roughly: once per time that +//! `event!` or `span!` is written in the source code; this is cached at the +//! callsite). See [`Subscriber::register_callsite`] and +//! [`tracing_core::callsite`] for a summary of how this behaves. +//! - [`enabled`], once per emitted event (roughly: once per time that `event!` +//! or `span!` is *executed*), and only if `register_callsite` regesters an +//! [`Interest::sometimes`]. This is the main customization point to globally +//! filter events based on their [`Metadata`]. If an event can be disabled +//! based only on [`Metadata`], it should be, as this allows the construction +//! of the actual `Event`/`Span` to be skipped. +//! - For events only (and not spans), [`event_enabled`] is called just before +//! processing the event. This gives layers one last chance to say that +//! an event should be filtered out, now that the event's fields are known. +//! +//! ## 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(()) } +//! ``` +//! +//! [`Subscriber`]: tracing_core::subscriber::Subscriber +//! [span IDs]: tracing_core::span::Id +//! [the current span]: Context::current_span +//! [`register_callsite`]: Layer::register_callsite +//! [`enabled`]: Layer::enabled +//! [`event_enabled`]: Layer::event_enabled +//! [`on_enter`]: Layer::on_enter +//! [`Layer::register_callsite`]: Layer::register_callsite +//! [`Layer::enabled`]: Layer::enabled +//! [`Interest::never()`]: tracing_core::subscriber::Interest::never() +//! [`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}, + Dispatch, 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 installing this layer as a + /// [`Subscriber`]. + /// + /// ## Avoiding Memory Leaks + /// + /// `Layer`s should not store the [`Dispatch`] pointing to the [`Subscriber`] + /// that they are a part of. Because the `Dispatch` owns the `Subscriber`, + /// storing the `Dispatch` within the `Subscriber` will create a reference + /// count cycle, preventing the `Dispatch` from ever being dropped. + /// + /// Instead, when it is necessary to store a cyclical reference to the + /// `Dispatch` within a `Layer`, use [`Dispatch::downgrade`] to convert a + /// `Dispatch` into a [`WeakDispatch`]. This type is analogous to + /// [`std::sync::Weak`], and does not create a reference count cycle. A + /// [`WeakDispatch`] can be stored within a subscriber without causing a + /// memory leak, and can be [upgraded] into a `Dispatch` temporarily when + /// the `Dispatch` must be accessed by the subscriber. + /// + /// [`WeakDispatch`]: tracing_core::dispatcher::WeakDispatch + /// [upgraded]: tracing_core::dispatcher::WeakDispatch::upgrade + /// [`Subscriber`]: tracing_core::Subscriber + fn on_register_dispatch(&self, collector: &Dispatch) { + let _ = collector; + } + + /// 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`]: tracing_core::Interest + /// [`Subscriber::register_callsite`]: tracing_core::Subscriber::register_callsite() + /// [`Interest::never()`]: tracing_core::subscriber::Interest::never() + /// [`Interest::always()`]: tracing_core::subscriber::Interest::always() + /// [`self.enabled`]: Layer::enabled() + /// [`Layer::enabled`]: Layer::enabled() + /// [`on_event`]: Layer::on_event() + /// [`on_enter`]: Layer::on_enter() + /// [`on_exit`]: Layer::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`]: tracing_core::Interest + /// [`Subscriber::enabled`]: tracing_core::Subscriber::enabled() + /// [`Layer::register_callsite`]: Layer::register_callsite() + /// [`on_event`]: Layer::on_event() + /// [`on_enter`]: Layer::on_enter() + /// [`on_exit`]: Layer::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>) {} + + /// Called before [`on_event`], to determine if `on_event` should be called. + /// + /// <div class="example-wrap" style="display:inline-block"> + /// <pre class="ignore" style="white-space:normal;font:inherit;"> + /// + /// **Note**: This method determines whether an event is globally enabled, + /// *not* whether the individual `Layer` will be notified about the + /// event. This is intended to be used by `Layer`s that implement + /// filtering for the entire stack. `Layer`s which do not wish to be + /// notified about certain events but do not wish to globally disable them + /// should ignore those events in their [on_event][Self::on_event]. + /// + /// </pre></div> + /// + /// See [the trait-level documentation] for more information on filtering + /// with `Layer`s. + /// + /// [`on_event`]: Self::on_event + /// [`Interest`]: tracing_core::Interest + /// [the trait-level documentation]: #filtering-with-layers + #[inline] // collapse this to a constant please mrs optimizer + fn event_enabled(&self, _event: &Event<'_>, _ctx: Context<'_, S>) -> bool { + true + } + + /// 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`]: tracing_core::Subscriber + 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]: crate::layer#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) + } + + /// Erases the type of this [`Layer`], returning a [`Box`]ed `dyn + /// Layer` trait object. + /// + /// This can be used when a function returns a `Layer` which may be of + /// one of several types, or when a `Layer` subscriber has a very long type + /// signature. + /// + /// # Examples + /// + /// The following example will *not* compile, because the value assigned to + /// `log_layer` may have one of several different types: + /// + /// ```compile_fail + /// # fn main() -> Result<(), Box<dyn std::error::Error>> { + /// use tracing_subscriber::{Layer, filter::LevelFilter, prelude::*}; + /// use std::{path::PathBuf, fs::File, io}; + /// + /// /// Configures whether logs are emitted to a file, to stdout, or to stderr. + /// pub enum LogConfig { + /// File(PathBuf), + /// Stdout, + /// Stderr, + /// } + /// + /// let config = // ... + /// # LogConfig::Stdout; + /// + /// // Depending on the config, construct a layer of one of several types. + /// let log_layer = match config { + /// // If logging to a file, use a maximally-verbose configuration. + /// LogConfig::File(path) => { + /// let file = File::create(path)?; + /// tracing_subscriber::fmt::layer() + /// .with_thread_ids(true) + /// .with_thread_names(true) + /// // Selecting the JSON logging format changes the layer's + /// // type. + /// .json() + /// .with_span_list(true) + /// // Setting the writer to use our log file changes the + /// // layer's type again. + /// .with_writer(file) + /// }, + /// + /// // If logging to stdout, use a pretty, human-readable configuration. + /// LogConfig::Stdout => tracing_subscriber::fmt::layer() + /// // Selecting the "pretty" logging format changes the + /// // layer's type! + /// .pretty() + /// .with_writer(io::stdout) + /// // Add a filter based on the RUST_LOG environment variable; + /// // this changes the type too! + /// .and_then(tracing_subscriber::EnvFilter::from_default_env()), + /// + /// // If logging to stdout, only log errors and warnings. + /// LogConfig::Stderr => tracing_subscriber::fmt::layer() + /// // Changing the writer changes the layer's type + /// .with_writer(io::stderr) + /// // Only log the `WARN` and `ERROR` levels. Adding a filter + /// // changes the layer's type to `Filtered<LevelFilter, ...>`. + /// .with_filter(LevelFilter::WARN), + /// }; + /// + /// tracing_subscriber::registry() + /// .with(log_layer) + /// .init(); + /// # Ok(()) } + /// ``` + /// + /// However, adding a call to `.boxed()` after each match arm erases the + /// layer's type, so this code *does* compile: + /// + /// ``` + /// # fn main() -> Result<(), Box<dyn std::error::Error>> { + /// # use tracing_subscriber::{Layer, filter::LevelFilter, prelude::*}; + /// # use std::{path::PathBuf, fs::File, io}; + /// # pub enum LogConfig { + /// # File(PathBuf), + /// # Stdout, + /// # Stderr, + /// # } + /// # let config = LogConfig::Stdout; + /// let log_layer = match config { + /// LogConfig::File(path) => { + /// let file = File::create(path)?; + /// tracing_subscriber::fmt::layer() + /// .with_thread_ids(true) + /// .with_thread_names(true) + /// .json() + /// .with_span_list(true) + /// .with_writer(file) + /// // Erase the type by boxing the layer + /// .boxed() + /// }, + /// + /// LogConfig::Stdout => tracing_subscriber::fmt::layer() + /// .pretty() + /// .with_writer(io::stdout) + /// .and_then(tracing_subscriber::EnvFilter::from_default_env()) + /// // Erase the type by boxing the layer + /// .boxed(), + /// + /// LogConfig::Stderr => tracing_subscriber::fmt::layer() + /// .with_writer(io::stderr) + /// .with_filter(LevelFilter::WARN) + /// // Erase the type by boxing the layer + /// .boxed(), + /// }; + /// + /// tracing_subscriber::registry() + /// .with(log_layer) + /// .init(); + /// # Ok(()) } + /// ``` + #[cfg(any(feature = "alloc", feature = "std"))] + #[cfg_attr(docsrs, doc(cfg(any(feature = "alloc", feature = "std"))))] + fn boxed(self) -> Box<dyn Layer<S> + Send + Sync + 'static> + where + Self: Sized, + Self: Layer<S> + Send + Sync + 'static, + S: Subscriber, + { + Box::new(self) + } + + #[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() + } + + /// Called before the filtered [`Layer]'s [`on_event`], to determine if + /// `on_event` should be called. + /// + /// This gives a chance to filter events based on their fields. Note, + /// however, that this *does not* override [`enabled`], and is not even + /// called if [`enabled`] returns `false`. + /// + /// ## Default Implementation + /// + /// By default, this method returns `true`, indicating that no events are + /// filtered out based on their fields. + /// + /// [`enabled`]: crate::layer::Filter::enabled + /// [`on_event`]: crate::layer::Layer::on_event + #[inline] // collapse this to a constant please mrs optimizer + fn event_enabled(&self, event: &Event<'_>, cx: &Context<'_, S>) -> bool { + let _ = (event, cx); + true + } + + /// 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 + } + + /// Notifies this filter that a new span was constructed with the given + /// `Attributes` and `Id`. + /// + /// By default, this method does nothing. `Filter` implementations that + /// need to be notified when new spans are created can override this + /// method. + fn on_new_span(&self, attrs: &span::Attributes<'_>, id: &span::Id, ctx: Context<'_, S>) { + let _ = (attrs, id, ctx); + } + + + /// Notifies this filter that a span with the given `Id` recorded the given + /// `values`. + /// + /// By default, this method does nothing. `Filter` implementations that + /// need to be notified when new spans are created can override this + /// method. + fn on_record(&self, id: &span::Id, values: &span::Record<'_>, ctx: Context<'_, S>) { + let _ = (id, values, ctx); + } + + /// Notifies this filter that a span with the given ID was entered. + /// + /// By default, this method does nothing. `Filter` implementations that + /// need to be notified when a span is entered can override this method. + fn on_enter(&self, id: &span::Id, ctx: Context<'_, S>) { + let _ = (id, ctx); + } + + /// Notifies this filter that a span with the given ID was exited. + /// + /// By default, this method does nothing. `Filter` implementations that + /// need to be notified when a span is exited can override this method. + fn on_exit(&self, id: &span::Id, ctx: Context<'_, S>) { + let _ = (id, ctx); + } + + /// Notifies this filter that a span with the given ID has been closed. + /// + /// By default, this method does nothing. `Filter` implementations that + /// need to be notified when a span is closed can override this method. + fn on_close(&self, id: span::Id, ctx: Context<'_, S>) { + let _ = (id, ctx); + } + } +} + +/// 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 === + +#[derive(Clone, Copy)] +pub(crate) struct NoneLayerMarker(()); +static NONE_LAYER_MARKER: NoneLayerMarker = NoneLayerMarker(()); + +/// Is a type implementing `Layer` `Option::<_>::None`? +pub(crate) fn layer_is_none<L, S>(layer: &L) -> bool +where + L: Layer<S>, + S: Subscriber, +{ + unsafe { + // Safety: we're not actually *doing* anything with this pointer --- + // this only care about the `Option`, which is essentially being used + // as a bool. We can rely on the pointer being valid, because it is + // a crate-private type, and is only returned by the `Layer` impl + // for `Option`s. However, even if the layer *does* decide to be + // evil and give us an invalid pointer here, that's fine, because we'll + // never actually dereference it. + layer.downcast_raw(TypeId::of::<NoneLayerMarker>()) + } + .is_some() +} + +/// Is a type implementing `Subscriber` `Option::<_>::None`? +pub(crate) fn subscriber_is_none<S>(subscriber: &S) -> bool +where + S: Subscriber, +{ + unsafe { + // Safety: we're not actually *doing* anything with this pointer --- + // this only care about the `Option`, which is essentially being used + // as a bool. We can rely on the pointer being valid, because it is + // a crate-private type, and is only returned by the `Layer` impl + // for `Option`s. However, even if the subscriber *does* decide to be + // evil and give us an invalid pointer here, that's fine, because we'll + // never actually dereference it. + subscriber.downcast_raw(TypeId::of::<NoneLayerMarker>()) + } + .is_some() +} + +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 => { + // There is no inner layer, so this layer will + // never enable anything. + Some(LevelFilter::OFF) + } + } + } + + #[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 event_enabled(&self, event: &Event<'_>, ctx: Context<'_, S>) -> bool { + match self { + Some(ref inner) => inner.event_enabled(event, ctx), + None => true, + } + } + + #[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 if id == TypeId::of::<NoneLayerMarker>() && self.is_none() { + Some(&NONE_LAYER_MARKER as *const _ as *const ()) + } else { + self.as_ref().and_then(|inner| inner.downcast_raw(id)) + } + } +} + +feature! { + #![any(feature = "std", feature = "alloc")] + #[cfg(not(feature = "std"))] + use alloc::vec::Vec; + + macro_rules! layer_impl_body { + () => { + #[inline] + fn on_register_dispatch(&self, subscriber: &Dispatch) { + self.deref().on_register_dispatch(subscriber); + } + + #[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 event_enabled(&self, event: &Event<'_>, ctx: Context<'_, S>) -> bool { + self.deref().event_enabled(event, 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<S, L> Layer<S> for Vec<L> + where + L: Layer<S>, + S: Subscriber, + { + + fn on_layer(&mut self, subscriber: &mut S) { + for l in self { + l.on_layer(subscriber); + } + } + + fn register_callsite(&self, metadata: &'static Metadata<'static>) -> Interest { + // Return highest level of interest. + let mut interest = Interest::never(); + for l in self { + let new_interest = l.register_callsite(metadata); + if (interest.is_sometimes() && new_interest.is_always()) + || (interest.is_never() && !new_interest.is_never()) + { + interest = new_interest; + } + } + + interest + } + + fn enabled(&self, metadata: &Metadata<'_>, ctx: Context<'_, S>) -> bool { + self.iter().all(|l| l.enabled(metadata, ctx.clone())) + } + + fn event_enabled(&self, event: &Event<'_>, ctx: Context<'_, S>) -> bool { + self.iter().all(|l| l.event_enabled(event, ctx.clone())) + } + + fn on_new_span(&self, attrs: &span::Attributes<'_>, id: &span::Id, ctx: Context<'_, S>) { + for l in self { + l.on_new_span(attrs, id, ctx.clone()); + } + } + + fn max_level_hint(&self) -> Option<LevelFilter> { + // Default to `OFF` if there are no inner layers. + let mut max_level = LevelFilter::OFF; + for l in self { + // NOTE(eliza): this is slightly subtle: if *any* layer + // returns `None`, we have to return `None`, assuming there is + // no max level hint, since that particular layer cannot + // provide a hint. + let hint = l.max_level_hint()?; + max_level = core::cmp::max(hint, max_level); + } + Some(max_level) + } + + fn on_record(&self, span: &span::Id, values: &span::Record<'_>, ctx: Context<'_, S>) { + for l in self { + l.on_record(span, values, ctx.clone()) + } + } + + fn on_follows_from(&self, span: &span::Id, follows: &span::Id, ctx: Context<'_, S>) { + for l in self { + l.on_follows_from(span, follows, ctx.clone()); + } + } + + fn on_event(&self, event: &Event<'_>, ctx: Context<'_, S>) { + for l in self { + l.on_event(event, ctx.clone()); + } + } + + fn on_enter(&self, id: &span::Id, ctx: Context<'_, S>) { + for l in self { + l.on_enter(id, ctx.clone()); + } + } + + fn on_exit(&self, id: &span::Id, ctx: Context<'_, S>) { + for l in self { + l.on_exit(id, ctx.clone()); + } + } + + fn on_close(&self, id: span::Id, ctx: Context<'_, S>) { + for l in self { + l.on_close(id.clone(), ctx.clone()); + } + } + + #[doc(hidden)] + unsafe fn downcast_raw(&self, id: TypeId) -> Option<*const ()> { + // If downcasting to `Self`, return a pointer to `self`. + if id == TypeId::of::<Self>() { + return Some(self as *const _ as *const ()); + } + + // Someone is looking for per-layer filters. But, this `Vec` + // might contain layers with per-layer filters *and* + // layers without filters. It should only be treated as a + // per-layer-filtered layer if *all* its layers have + // per-layer filters. + // XXX(eliza): it's a bummer we have to do this linear search every + // time. It would be nice if this could be cached, but that would + // require replacing the `Vec` impl with an impl for a newtype... + if filter::is_plf_downcast_marker(id) && self.iter().any(|s| s.downcast_raw(id).is_none()) { + return None; + } + + // Otherwise, return the first child of `self` that downcaasts to + // the selected type, if any. + // XXX(eliza): hope this is reasonable lol + self.iter().find_map(|l| l.downcast_raw(id)) + } + } +} + +// === 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: () } + } +} diff --git a/vendor/tracing-subscriber/src/layer/tests.rs b/vendor/tracing-subscriber/src/layer/tests.rs new file mode 100644 index 000000000..d7ad61769 --- /dev/null +++ b/vendor/tracing-subscriber/src/layer/tests.rs @@ -0,0 +1,308 @@ +use super::*; +use tracing_core::subscriber::NoSubscriber; + +#[derive(Debug)] +pub(crate) struct NopLayer; +impl<S: Subscriber> Layer<S> for NopLayer {} + +#[allow(dead_code)] +struct NopLayer2; +impl<S: Subscriber> Layer<S> for NopLayer2 {} + +/// A layer that holds a string. +/// +/// Used to test that pointers returned by downcasting are actually valid. +struct StringLayer(&'static str); +impl<S: Subscriber> Layer<S> for StringLayer {} +struct StringLayer2(&'static str); +impl<S: Subscriber> Layer<S> for StringLayer2 {} + +struct StringLayer3(&'static str); +impl<S: Subscriber> Layer<S> for StringLayer3 {} + +pub(crate) struct StringSubscriber(&'static str); + +impl Subscriber for StringSubscriber { + fn register_callsite(&self, _: &'static Metadata<'static>) -> Interest { + Interest::never() + } + + fn enabled(&self, _: &Metadata<'_>) -> bool { + false + } + + fn new_span(&self, _: &span::Attributes<'_>) -> span::Id { + span::Id::from_u64(1) + } + + fn record(&self, _: &span::Id, _: &span::Record<'_>) {} + fn record_follows_from(&self, _: &span::Id, _: &span::Id) {} + fn event(&self, _: &Event<'_>) {} + fn enter(&self, _: &span::Id) {} + fn exit(&self, _: &span::Id) {} +} + +fn assert_subscriber(_s: impl Subscriber) {} +fn assert_layer<S: Subscriber>(_l: &impl Layer<S>) {} + +#[test] +fn layer_is_subscriber() { + let s = NopLayer.with_subscriber(NoSubscriber::default()); + assert_subscriber(s) +} + +#[test] +fn two_layers_are_subscriber() { + let s = NopLayer + .and_then(NopLayer) + .with_subscriber(NoSubscriber::default()); + assert_subscriber(s) +} + +#[test] +fn three_layers_are_subscriber() { + let s = NopLayer + .and_then(NopLayer) + .and_then(NopLayer) + .with_subscriber(NoSubscriber::default()); + assert_subscriber(s) +} + +#[test] +fn three_layers_are_layer() { + let layers = NopLayer.and_then(NopLayer).and_then(NopLayer); + assert_layer(&layers); + let _ = layers.with_subscriber(NoSubscriber::default()); +} + +#[test] +#[cfg(feature = "alloc")] +fn box_layer_is_layer() { + use alloc::boxed::Box; + let l: Box<dyn Layer<NoSubscriber> + Send + Sync> = Box::new(NopLayer); + assert_layer(&l); + l.with_subscriber(NoSubscriber::default()); +} + +#[test] +fn downcasts_to_subscriber() { + let s = NopLayer + .and_then(NopLayer) + .and_then(NopLayer) + .with_subscriber(StringSubscriber("subscriber")); + let subscriber = + <dyn Subscriber>::downcast_ref::<StringSubscriber>(&s).expect("subscriber should downcast"); + assert_eq!(subscriber.0, "subscriber"); +} + +#[test] +fn downcasts_to_layer() { + let s = StringLayer("layer_1") + .and_then(StringLayer2("layer_2")) + .and_then(StringLayer3("layer_3")) + .with_subscriber(NoSubscriber::default()); + let layer = <dyn Subscriber>::downcast_ref::<StringLayer>(&s).expect("layer 1 should downcast"); + assert_eq!(layer.0, "layer_1"); + let layer = + <dyn Subscriber>::downcast_ref::<StringLayer2>(&s).expect("layer 2 should downcast"); + assert_eq!(layer.0, "layer_2"); + let layer = + <dyn Subscriber>::downcast_ref::<StringLayer3>(&s).expect("layer 3 should downcast"); + assert_eq!(layer.0, "layer_3"); +} + +#[cfg(all(feature = "registry", feature = "std"))] +mod registry_tests { + use super::*; + use crate::registry::LookupSpan; + + #[test] + fn context_event_span() { + use std::sync::{Arc, Mutex}; + let last_event_span = Arc::new(Mutex::new(None)); + + struct RecordingLayer { + last_event_span: Arc<Mutex<Option<&'static str>>>, + } + + impl<S> Layer<S> for RecordingLayer + where + S: Subscriber + for<'lookup> LookupSpan<'lookup>, + { + fn on_event(&self, event: &Event<'_>, ctx: Context<'_, S>) { + let span = ctx.event_span(event); + *self.last_event_span.lock().unwrap() = span.map(|s| s.name()); + } + } + + tracing::subscriber::with_default( + crate::registry().with(RecordingLayer { + last_event_span: last_event_span.clone(), + }), + || { + tracing::info!("no span"); + assert_eq!(*last_event_span.lock().unwrap(), None); + + let parent = tracing::info_span!("explicit"); + tracing::info!(parent: &parent, "explicit span"); + assert_eq!(*last_event_span.lock().unwrap(), Some("explicit")); + + let _guard = tracing::info_span!("contextual").entered(); + tracing::info!("contextual span"); + assert_eq!(*last_event_span.lock().unwrap(), Some("contextual")); + }, + ); + } + + /// Tests for how max-level hints are calculated when combining layers + /// with and without per-layer filtering. + mod max_level_hints { + + use super::*; + use crate::filter::*; + + #[test] + fn mixed_with_unfiltered() { + let subscriber = crate::registry() + .with(NopLayer) + .with(NopLayer.with_filter(LevelFilter::INFO)); + assert_eq!(subscriber.max_level_hint(), None); + } + + #[test] + fn mixed_with_unfiltered_layered() { + let subscriber = crate::registry().with(NopLayer).with( + NopLayer + .with_filter(LevelFilter::INFO) + .and_then(NopLayer.with_filter(LevelFilter::TRACE)), + ); + assert_eq!(dbg!(subscriber).max_level_hint(), None); + } + + #[test] + fn mixed_interleaved() { + let subscriber = crate::registry() + .with(NopLayer) + .with(NopLayer.with_filter(LevelFilter::INFO)) + .with(NopLayer) + .with(NopLayer.with_filter(LevelFilter::INFO)); + assert_eq!(dbg!(subscriber).max_level_hint(), None); + } + + #[test] + fn mixed_layered() { + let subscriber = crate::registry() + .with(NopLayer.with_filter(LevelFilter::INFO).and_then(NopLayer)) + .with(NopLayer.and_then(NopLayer.with_filter(LevelFilter::INFO))); + assert_eq!(dbg!(subscriber).max_level_hint(), None); + } + + #[test] + fn plf_only_unhinted() { + let subscriber = crate::registry() + .with(NopLayer.with_filter(LevelFilter::INFO)) + .with(NopLayer.with_filter(filter_fn(|_| true))); + assert_eq!(dbg!(subscriber).max_level_hint(), None); + } + + #[test] + fn plf_only_unhinted_nested_outer() { + // if a nested tree of per-layer filters has an _outer_ filter with + // no max level hint, it should return `None`. + let subscriber = crate::registry() + .with( + NopLayer + .with_filter(LevelFilter::INFO) + .and_then(NopLayer.with_filter(LevelFilter::WARN)), + ) + .with( + NopLayer + .with_filter(filter_fn(|_| true)) + .and_then(NopLayer.with_filter(LevelFilter::DEBUG)), + ); + assert_eq!(dbg!(subscriber).max_level_hint(), None); + } + + #[test] + fn plf_only_unhinted_nested_inner() { + // If a nested tree of per-layer filters has an _inner_ filter with + // no max-level hint, but the _outer_ filter has a max level hint, + // it should pick the outer hint. This is because the outer filter + // will disable the spans/events before they make it to the inner + // filter. + let subscriber = dbg!(crate::registry().with( + NopLayer + .with_filter(filter_fn(|_| true)) + .and_then(NopLayer.with_filter(filter_fn(|_| true))) + .with_filter(LevelFilter::INFO), + )); + assert_eq!(dbg!(subscriber).max_level_hint(), Some(LevelFilter::INFO)); + } + + #[test] + fn unhinted_nested_inner() { + let subscriber = dbg!(crate::registry() + .with(NopLayer.and_then(NopLayer).with_filter(LevelFilter::INFO)) + .with( + NopLayer + .with_filter(filter_fn(|_| true)) + .and_then(NopLayer.with_filter(filter_fn(|_| true))) + .with_filter(LevelFilter::WARN), + )); + assert_eq!(dbg!(subscriber).max_level_hint(), Some(LevelFilter::INFO)); + } + + #[test] + fn unhinted_nested_inner_mixed() { + let subscriber = dbg!(crate::registry() + .with( + NopLayer + .and_then(NopLayer.with_filter(filter_fn(|_| true))) + .with_filter(LevelFilter::INFO) + ) + .with( + NopLayer + .with_filter(filter_fn(|_| true)) + .and_then(NopLayer.with_filter(filter_fn(|_| true))) + .with_filter(LevelFilter::WARN), + )); + assert_eq!(dbg!(subscriber).max_level_hint(), Some(LevelFilter::INFO)); + } + + #[test] + fn plf_only_picks_max() { + let subscriber = crate::registry() + .with(NopLayer.with_filter(LevelFilter::WARN)) + .with(NopLayer.with_filter(LevelFilter::DEBUG)); + assert_eq!(dbg!(subscriber).max_level_hint(), Some(LevelFilter::DEBUG)); + } + + #[test] + fn many_plf_only_picks_max() { + let subscriber = crate::registry() + .with(NopLayer.with_filter(LevelFilter::WARN)) + .with(NopLayer.with_filter(LevelFilter::DEBUG)) + .with(NopLayer.with_filter(LevelFilter::INFO)) + .with(NopLayer.with_filter(LevelFilter::ERROR)); + assert_eq!(dbg!(subscriber).max_level_hint(), Some(LevelFilter::DEBUG)); + } + + #[test] + fn nested_plf_only_picks_max() { + let subscriber = crate::registry() + .with( + NopLayer.with_filter(LevelFilter::INFO).and_then( + NopLayer + .with_filter(LevelFilter::WARN) + .and_then(NopLayer.with_filter(LevelFilter::DEBUG)), + ), + ) + .with( + NopLayer + .with_filter(LevelFilter::INFO) + .and_then(NopLayer.with_filter(LevelFilter::ERROR)), + ); + assert_eq!(dbg!(subscriber).max_level_hint(), Some(LevelFilter::DEBUG)); + } + } +} |