Add Subscribe::event_enabled to conditionally dis/enable events based on fields

tracing-core/src/collect.rs

@@ -57,6 +57,9 @@ use core::ptr::NonNull;
 ///   See also the [documentation on the callsite registry][cs-reg] for details
 ///   on [`register_callsite`].
 ///
+/// - [`event_enabled`] is called once before every [`event`] is recorded. This
+///   can be used to implement filtering on events once their field values are
+///   known but before any processing is done in `event`.
 /// - [`clone_span`] is called every time a span ID is cloned, and [`try_close`]
 ///   is called when a span ID is dropped. By default, these functions do
 ///   nothing. However, they can be used to implement reference counting for
@@ -72,6 +75,8 @@ use core::ptr::NonNull;
 /// [`clone_span`]: Collect::clone_span
 /// [`try_close`]: Collect::try_close
 /// [cs-reg]: crate::callsite#registering-callsites
+/// [`event`]: Collect::event
+/// [`event_enabled`]: Collect::event_enabled
 pub trait Collect: 'static {
     // === Span registry methods ==============================================
 
@@ -288,6 +293,17 @@ pub trait Collect: 'static {
     /// follow from _b_), it may silently do nothing.
     fn record_follows_from(&self, span: &span::Id, follows: &span::Id);
 
+    /// Determine if an [`Event`] should be recorded.
+    ///
+    /// By default, this returns `true` and collectors can filter events in
+    /// [`event`][Self::event] without any penalty. However, when `event` is
+    /// more complicated, this can be used to determine if `event` should be
+    /// called at all, separating out the decision from the processing.
+    fn event_enabled(&self, event: &Event<'_>) -> bool {
+        let _ = event;
+        true
+    }
+
     /// Records that an [`Event`] has occurred.
     ///
     /// This method will be invoked when an Event is constructed by
@@ -685,6 +701,11 @@ impl Collect for alloc::boxed::Box<dyn Collect + Send + Sync + 'static> {
         self.as_ref().record_follows_from(span, follows)
     }
 
+    #[inline]
+    fn event_enabled(&self, event: &Event<'_>) -> bool {
+        self.as_ref().event_enabled(event)
+    }
+
     #[inline]
     fn event(&self, event: &Event<'_>) {
         self.as_ref().event(event)
@@ -756,6 +777,11 @@ impl Collect for alloc::sync::Arc<dyn Collect + Send + Sync + 'static> {
         self.as_ref().record_follows_from(span, follows)
     }
 
+    #[inline]
+    fn event_enabled(&self, event: &Event<'_>) -> bool {
+        self.as_ref().event_enabled(event)
+    }
+
     #[inline]
     fn event(&self, event: &Event<'_>) {
         self.as_ref().event(event)

tracing-core/src/dispatch.rs

@@ -682,7 +682,10 @@ impl Dispatch {
     /// [`event`]: super::collect::Collect::event
     #[inline]
     pub fn event(&self, event: &Event<'_>) {
-        self.collector().event(event)
+        let collector = self.collector();
+        if collector.event_enabled(event) {
+            collector.event(event);
+        }
     }
 
     /// Records that a span has been can_enter.

tracing-subscriber/src/fmt/mod.rs

@@ -393,6 +393,11 @@ where
         self.inner.record_follows_from(span, follows)
     }
 
+    #[inline]
+    fn event_enabled(&self, event: &Event<'_>) -> bool {
+        self.inner.event_enabled(event)
+    }
+
     #[inline]
     fn event(&self, event: &Event<'_>) {
         self.inner.event(event);

tracing-subscriber/src/reload.rs

@@ -93,6 +93,11 @@ where
         try_lock!(self.inner.read()).on_follows_from(span, follows, ctx)
     }
 
+    #[inline]
+    fn event_enabled(&self, event: &Event<'_>, ctx: subscribe::Context<'_, C>) -> bool {
+        try_lock!(self.inner.read(), else return false).event_enabled(event, ctx)
+    }
+
     #[inline]
     fn on_event(&self, event: &Event<'_>, ctx: subscribe::Context<'_, C>) {
         try_lock!(self.inner.read()).on_event(event, ctx)

tracing-subscriber/src/subscribe/layered.rs

@@ -138,6 +138,16 @@ where
         self.subscriber.on_follows_from(span, follows, self.ctx());
     }
 
+    fn event_enabled(&self, event: &Event<'_>) -> bool {
+        if self.subscriber.event_enabled(event, self.ctx()) {
+            // if the outer subscriber enables the event, ask the inner collector.
+            self.inner.event_enabled(event)
+        } else {
+            // otherwise, the event is disabled by this subscriber
+            false
+        }
+    }
+
     fn event(&self, event: &Event<'_>) {
         self.inner.event(event);
         self.subscriber.on_event(event, self.ctx());
@@ -280,6 +290,17 @@ where
         self.subscriber.on_follows_from(span, follows, ctx);
     }
 
+    #[inline]
+    fn event_enabled(&self, event: &Event<'_>, ctx: Context<'_, C>) -> bool {
+        if self.subscriber.event_enabled(event, ctx.clone()) {
+            // if the outer subscriber enables the event, ask the inner collector.
+            self.inner.event_enabled(event, ctx)
+        } else {
+            // otherwise, the event is disabled by this subscriber
+            false
+        }
+    }
+
     #[inline]
     fn on_event(&self, event: &Event<'_>, ctx: Context<'_, C>) {
         self.inner.on_event(event, ctx.clone());

tracing-subscriber/src/subscribe/mod.rs

@@ -686,7 +686,31 @@ pub(crate) mod tests;
 /// be composed together with other subscribers to build a [collector]. See the
 /// [module-level documentation](crate::subscribe) for details.
 ///
+/// # 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
+/// subscribers should attempt to provide accurate information as early as
+/// possible. Note that this determines **global** interest for the entire stack
+/// of subscribers; a subscriber that wants to ignore certain events/spans
+/// should just ignore them in the notifications. 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 [`Collect::register_callsite`] for how this behaves.
+/// - [`enabled`], once per emitted event (or span). This is the main point to
+///   (globally) filter events based on their [`Metadata`]. If an event can be
+///   disabled by just its structure, it should be, as this allows 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 subscribers one last chance to say that
+///   an event should be filtered out, now that the event's fields are known.
+///
 /// [collector]: tracing_core::Collect
+/// [`enabled`]: Self::enabled
+/// [`event_enabled`]: Self::event_enabled
+/// [`register_callsite`]: Self::register_callsite
 #[cfg_attr(docsrs, doc(notable_trait))]
 pub trait Subscribe<C>
 where
@@ -827,6 +851,31 @@ where
     // 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<'_, C>) {}
 
+    /// 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 subscriber will be notified about the
+    /// 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 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 `Subscriber`s.
+    ///
+    /// [`on_event`]: Self::on_event
+    /// [`Interest`]: tracing_core::Interest
+    /// [the trait-level documentation]: #filtering-with-subscribers
+    #[inline] // collapse this to a constant please mrs optimizer
+    fn event_enabled(&self, _event: &Event<'_>, _ctx: Context<'_, C>) -> bool {
+        true
+    }
+
     /// Notifies this subscriber that an event has occurred.
     fn on_event(&self, _event: &Event<'_>, _ctx: Context<'_, C>) {}
 
@@ -1455,6 +1504,14 @@ where
         }
     }
 
+    #[inline]
+    fn event_enabled(&self, event: &Event<'_>, ctx: Context<'_, C>) -> bool {
+        match self {
+            Some(ref inner) => inner.event_enabled(event, ctx),
+            None => false,
+        }
+    }
+
     #[inline]
     fn on_event(&self, event: &Event<'_>, ctx: Context<'_, C>) {
         if let Some(ref inner) = self {
@@ -1534,6 +1591,11 @@ macro_rules! subscriber_impl_body {
             self.deref().on_follows_from(span, follows, ctx)
         }
 
+        #[inline]
+        fn event_enabled(&self, event: &Event<'_>, ctx: Context<'_, C>) -> bool {
+            self.deref().event_enabled(event, ctx)
+        }
+
         #[inline]
         fn on_event(&self, event: &Event<'_>, ctx: Context<'_, C>) {
             self.deref().on_event(event, ctx)