implement enabled!

tracing-core/src/metadata.rs

@@ -373,6 +373,7 @@ impl<'a> fmt::Debug for Metadata<'a> {
 enum KindInner {
     Event,
     Span,
+    Hint,
 }
 
 impl Kind {
@@ -382,6 +383,11 @@ impl Kind {
     /// `Span` callsite
     pub const SPAN: Kind = Kind(KindInner::Span);
 
+    /// `enabled!` callsite. [`Collect`][`crate::collect::Collect`]s can assume
+    /// this `Kind` means they will never recieve a
+    /// full event with this [`Metadata`].
+    pub const HINT: Kind = Kind(KindInner::Hint);
+
     /// Return true if the callsite kind is `Span`
     pub fn is_span(&self) -> bool {
         matches!(self, Kind(KindInner::Span))
@@ -391,6 +397,11 @@ impl Kind {
     pub fn is_event(&self) -> bool {
         matches!(self, Kind(KindInner::Event))
     }
+
+    /// Return true if the callsite kind is `Hint`
+    pub fn is_hint(&self) -> bool {
+        matches!(self, Kind(KindInner::Hint))
+    }
 }
 
 // ===== impl Level =====

tracing/src/macros.rs

@@ -783,6 +783,123 @@ macro_rules! event {
     );
 }
 
+/// Checks whether a span or event is enabled depending on the provided metadata.
+///
+/// This macro is a specialized tool: it is intended to be used prior
+/// to an expensive computation required *just* for that event, but
+/// *cannot* be done as part of an argument to that event, such as
+/// when multiple events are emitted (e.g., iterating over a collection
+/// and emitting an event for each item).
+///
+/// ## Usage
+///
+/// It is possible for `enabled!` to return a false positive or false negative. This might
+/// occur when a subscriber is using a _more specific_ filter than what was (or could be)
+/// provided to `enabled!`. Below are several examples where this might occur:
+///
+/// - If a subscriber is using a filter which may enable a span or event based
+/// on field names, but `enabled!` is invoked without listing field names,
+/// `enabled!` may return a false negative if a specific field name would
+/// cause the subscriber to enable something that would otherwise be disabled.
+/// - If a subscriber is using a filter which enables or disables specific events by
+/// file path and line number,  a particular event may be enabled/disabled
+/// even if an `enabled!` invocation with the same level, target, and fields
+/// indicated otherwise.
+/// - The subscriber can choose to enable _only_ spans or _only_ events, which `enabled`
+/// will not reflect.
+///
+/// ## Examples
+///
+/// `enabled!()` requires a level argument, an optional `target:`
+/// argument, and an optional set of fields. If the fields are not provided,
+/// they are considered to be unknown. `enabled!` attempts to match the
+/// syntax of `event!()` as closely as possible, which can be seen in the
+/// examples below.
+///
+/// ```rust
+/// use tracing::{enabled, Level};
+///
+/// # fn main() {
+/// // If the underlying collector is interested in recording
+/// // DEBUG-level spans and events, this will evaluate to true.
+/// if enabled!(Level::DEBUG) {
+///     // some expensive work...
+/// }
+///
+/// // If the underlying collector is interested in recording spans and events
+/// // with the target "my_crate" at the level DEBUG, this will evaluate to true.
+/// if enabled!(target: "my_crate", Level::DEBUG) {
+///     // some expensive work...
+/// }
+///
+/// // If the underlying collector is interested in recording spans and events
+/// // with the target "my_crate", at the level DEBUG, and the field name "hello",
+/// // this will evaluate to true.
+/// if enabled!(target: "my_crate", Level::DEBUG, hello) {
+///     // some expensive work...
+/// }
+/// # }
+/// ```
+///
+/// [`log::log_enabled`]: https://docs.rs/log/0.4.14/log/macro.log_enabled.html
+/// [`Targets`]: https://docs.rs/tracing-subscriber/0.3.5/tracing_subscriber/filter/targets/struct.Targets.html
+/// [`filter_fn`]: https://docs.rs/tracing-subscriber/0.3.5/tracing_subscriber/filter/fn.filter_fn.html
+/// [`EnvFilter`]: https://docs.rs/tracing-subscriber/0.3.5/tracing_subscriber/struct.EnvFilter.html
+#[macro_export]
+macro_rules! enabled {
+    (target: $target:expr, $lvl:expr, { $($fields:tt)* } )=> ({
+        if $crate::level_enabled!($lvl) {
+            use $crate::__macro_support::Callsite as _;
+            static CALLSITE: $crate::__macro_support::MacroCallsite = $crate::callsite2! {
+                name: concat!(
+                    "enabled ",
+                    file!(),
+                    ":",
+                    line!()
+                ),
+                kind: $crate::metadata::Kind::EVENT,
+                target: $target,
+                level: $lvl,
+                fields: $($fields)*
+            };
+            let interest = CALLSITE.interest();
+            if !interest.is_never() && CALLSITE.is_enabled(interest)  {
+                let meta = CALLSITE.metadata();
+                $crate::dispatch::get_default(|current| current.enabled(meta))
+            } else {
+                false
+            }
+        } else {
+            false
+        }
+    });
+    // Just target and level
+    (target: $target:expr, $lvl:expr ) => (
+        $crate::enabled!(target: $target, $lvl, { })
+    );
+
+    // These two cases handle fields with no values
+    (target: $target:expr, $lvl:expr, $($field:tt)*) => (
+        $crate::enabled!(
+            target: $target,
+            $lvl,
+            { $($field)*}
+        )
+    );
+    ($lvl:expr, $($field:tt)*) => (
+        $crate::enabled!(
+            target: module_path!(),
+            $lvl,
+            { $($field)*}
+        )
+    );
+
+    // Simplest `enabled!` case
+    ( $lvl:expr ) => (
+        $crate::enabled!(target: module_path!(), $lvl, { })
+    );
+}
+
 /// Constructs an event at the trace level.
 ///
 /// This functions similarly to the [`event!`] macro. See [the top-level

tracing/tests/enabled.rs

@@ -0,0 +1,30 @@
+// liballoc is required because the test subscriber cannot be constructed
+// statically
+#![cfg(feature = "alloc")]
+
+mod support;
+
+use self::support::*;
+use tracing::Level;
+
+#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)]
+#[test]
+fn level_and_target() {
+    let (collector, handle) = collector::mock()
+        .with_filter(|meta| {
+            if meta.target() == "debug_module" {
+                meta.level() <= &Level::DEBUG
+            } else {
+                meta.level() <= &Level::INFO
+            }
+        })
+        .done()
+        .run_with_handle();
+
+    tracing::collect::set_global_default(collector).unwrap();
+
+    assert!(tracing::enabled!(target: "debug_module", Level::DEBUG));
+    assert!(tracing::enabled!(Level::ERROR));
+    assert!(!tracing::enabled!(Level::DEBUG));
+    handle.assert_finished();
+}

tracing/tests/macros.rs

@@ -1,6 +1,6 @@
 #![deny(warnings)]
 use tracing::{
-    callsite, debug, debug_span, error, error_span, event, info, info_span, span, trace,
+    callsite, debug, debug_span, enabled, error, error_span, event, info, info_span, span, trace,
     trace_span, warn, warn_span, Level,
 };
 
@@ -334,6 +334,20 @@ fn event() {
     event!(Level::DEBUG, foo);
 }
 
+#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)]
+#[test]
+fn enabled() {
+    enabled!(Level::DEBUG, foo, bar.baz, quux,);
+    enabled!(Level::DEBUG, message);
+    enabled!(Level::INFO, foo, bar.baz, quux, message,);
+    enabled!(Level::INFO, foo, bar., message,);
+    enabled!(Level::DEBUG, foo);
+
+    enabled!(Level::DEBUG);
+    enabled!(target: "rando", Level::DEBUG);
+    enabled!(target: "rando", Level::DEBUG, field);
+}
+
 #[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)]
 #[test]
 fn locals_with_message() {