diff options
Diffstat (limited to 'vendor/tracing-subscriber/src/layer/context.rs')
| -rw-r--r-- | vendor/tracing-subscriber/src/layer/context.rs | 434 |
1 files changed, 434 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, + } + } +} |