Skip to content

Commit 110cb08

Browse files
guswynnhawkw
guswynn
and
hawkw
committed
tracing: add span_enabled! and event_enabled! macros (#1900)
## Motivation Closes #1892 ## Solution This branch adds new `span_enabled!` and `event_enabled!` macros. I went withe sharing as much of the macro as possible. The new macros were implemented by adding a `kind:` parameter to `enabled!`, and invoking `enabled!` with the appropriate `kind:` argument. This means in the docs, the macro only shows the `($($rest:tt)*)=> (...)` variant, but I think linking to the `enabled!` docs should be fine. Also, I find the macro pattern part of rustdoc to be very hard to understand, and I think many people dont look at it. Co-authored-by: Eliza Weisman <eliza@buoyant.io>
1 parent bd7755f commit 110cb08

File tree

3 files changed

+174
-13
lines changed

3 files changed

+174
-13
lines changed

‎tracing/src/macros.rs‎

Lines changed: 111 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -807,6 +807,70 @@ macro_rules! event {
807807
);
808808
}
809809

810+
/// Tests whether an event with the specified level and target would be enabled.
811+
///
812+
/// This is similar to [`enabled!`], but queries the current subscriber specifically for
813+
/// an event, whereas [`enabled!`] queries for an event _or_ span.
814+
///
815+
/// See the documentation for [`enabled!]` for more details on using this macro.
816+
/// See also [`span_enabled!`].
817+
///
818+
/// # Examples
819+
///
820+
/// ```rust
821+
/// # use tracing::{event_enabled, Level};
822+
/// if event_enabled!(target: "my_crate", Level::DEBUG) {
823+
/// // some expensive work...
824+
/// }
825+
/// // simpler
826+
/// if event_enabled!(Level::DEBUG) {
827+
/// // some expensive work...
828+
/// }
829+
/// // with fields
830+
/// if event_enabled!(Level::DEBUG, foo_field) {
831+
/// // some expensive work...
832+
/// }
833+
/// ```
834+
///
835+
#[macro_export]
836+
macro_rules! event_enabled {
837+
($($rest:tt)*)=> (
838+
$crate::enabled!(kind: $crate::metadata::Kind::EVENT, $($rest)*)
839+
)
840+
}
841+
842+
/// Tests whether a span with the specified level and target would be enabled.
843+
///
844+
/// This is similar to [`enabled!`], but queries the current subscriber specifically for
845+
/// an event, whereas [`enabled!`] queries for an event _or_ span.
846+
///
847+
/// See the documentation for [`enabled!]` for more details on using this macro.
848+
/// See also [`span_enabled!`].
849+
///
850+
/// # Examples
851+
///
852+
/// ```rust
853+
/// # use tracing::{span_enabled, Level};
854+
/// if span_enabled!(target: "my_crate", Level::DEBUG) {
855+
/// // some expensive work...
856+
/// }
857+
/// // simpler
858+
/// if span_enabled!(Level::DEBUG) {
859+
/// // some expensive work...
860+
/// }
861+
/// // with fields
862+
/// if span_enabled!(Level::DEBUG, foo_field) {
863+
/// // some expensive work...
864+
/// }
865+
/// ```
866+
///
867+
#[macro_export]
868+
macro_rules! span_enabled {
869+
($($rest:tt)*)=> (
870+
$crate::enabled!(kind: $crate::metadata::Kind::SPAN, $($rest)*)
871+
)
872+
}
873+
810874
/// Checks whether a span or event is [enabled] based on the provided [metadata].
811875
///
812876
/// [enabled]: crate::Subscriber::enabled
@@ -884,9 +948,21 @@ macro_rules! event {
884948
/// }
885949
/// ```
886950
///
951+
/// # Alternatives
952+
///
953+
/// `enabled!` queries subscribers with [`Metadata`] where
954+
/// [`is_event`] and [`is_span`] both return `false`. Alternatively,
955+
/// use [`event_enabled!`] or [`span_enabled!`] to ensure one of these
956+
/// returns true.
957+
///
958+
///
959+
/// [`Metadata`]: crate::Metadata
960+
/// [`is_event`]: crate::Metadata::is_event
961+
/// [`is_span`]: crate::Metadata::is_span
962+
///
887963
#[macro_export]
888964
macro_rules! enabled {
889-
(target: $target:expr, $lvl:expr, { $($fields:tt)* } )=> ({
965+
(kind: $kind:expr, target: $target:expr, $lvl:expr, { $($fields:tt)* } )=> ({
890966
if $crate::level_enabled!($lvl) {
891967
use $crate::__macro_support::Callsite as _;
892968
static CALLSITE: $crate::__macro_support::MacroCallsite = $crate::callsite2! {
@@ -896,7 +972,7 @@ macro_rules! enabled {
896972
":",
897973
line!()
898974
),
899-
kind: $crate::metadata::Kind::HINT,
975+
kind: $kind.hint(),
900976
target: $target,
901977
level: $lvl,
902978
fields: $($fields)*
@@ -913,29 +989,57 @@ macro_rules! enabled {
913989
}
914990
});
915991
// Just target and level
992+
(kind: $kind:expr, target: $target:expr, $lvl:expr ) => (
993+
$crate::enabled!(kind: $kind, target: $target, $lvl, { })
994+
);
916995
(target: $target:expr, $lvl:expr ) => (
917-
$crate::enabled!(target: $target, $lvl, { })
996+
$crate::enabled!(kind: $crate::metadata::Kind::HINT, target: $target, $lvl, { })
918997
);
919998

920-
// These two cases handle fields with no values
999+
// These four cases handle fields with no values
1000+
(kind: $kind:expr, target: $target:expr, $lvl:expr, $($field:tt)*) => (
1001+
$crate::enabled!(
1002+
kind: $kind,
1003+
target: $target,
1004+
$lvl,
1005+
{ $($field)*}
1006+
)
1007+
);
9211008
(target: $target:expr, $lvl:expr, $($field:tt)*) => (
9221009
$crate::enabled!(
1010+
kind: $crate::metadata::Kind::HINT,
9231011
target: $target,
9241012
$lvl,
9251013
{ $($field)*}
9261014
)
9271015
);
928-
($lvl:expr, $($field:tt)*) => (
1016+
1017+
// Level and field case
1018+
(kind: $kind:expr, $lvl:expr, $($field:tt)*) => (
9291019
$crate::enabled!(
1020+
kind: $kind,
9301021
target: module_path!(),
9311022
$lvl,
9321023
{ $($field)*}
9331024
)
9341025
);
9351026

9361027
// Simplest `enabled!` case
937-
( $lvl:expr ) => (
938-
$crate::enabled!(target: module_path!(), $lvl, { })
1028+
(kind: $kind:expr, $lvl:expr) => (
1029+
$crate::enabled!(kind: $kind, target: module_path!(), $lvl, { })
1030+
);
1031+
($lvl:expr) => (
1032+
$crate::enabled!(kind: $crate::metadata::Kind::HINT, target: module_path!(), $lvl, { })
1033+
);
1034+
1035+
// Fallthrough from above
1036+
($lvl:expr, $($field:tt)*) => (
1037+
$crate::enabled!(
1038+
kind: $crate::metadata::Kind::HINT,
1039+
target: module_path!(),
1040+
$lvl,
1041+
{ $($field)*}
1042+
)
9391043
);
9401044
}
9411045

‎tracing/tests/enabled.rs‎

Lines changed: 33 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ use tracing_mock::*;
44
#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)]
55
#[test]
66
fn level_and_target() {
7-
let (subscriber, handle) = subscriber::mock()
7+
let subscriber = subscriber::mock()
88
.with_filter(|meta| {
99
if meta.target() == "debug_module" {
1010
meta.level() <= &Level::DEBUG
@@ -13,12 +13,41 @@ fn level_and_target() {
1313
}
1414
})
1515
.done()
16-
.run_with_handle();
16+
.run();
1717

18-
tracing::subscriber::set_global_default(subscriber).unwrap();
18+
let _guard = tracing::subscriber::set_default(subscriber);
1919

2020
assert!(tracing::enabled!(target: "debug_module", Level::DEBUG));
2121
assert!(tracing::enabled!(Level::ERROR));
2222
assert!(!tracing::enabled!(Level::DEBUG));
23-
handle.assert_finished();
23+
}
24+
25+
#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)]
26+
#[test]
27+
fn span_and_event() {
28+
let subscriber = subscriber::mock()
29+
.with_filter(|meta| {
30+
if meta.target() == "debug_module" {
31+
meta.level() <= &Level::DEBUG
32+
} else if meta.is_span() {
33+
meta.level() <= &Level::TRACE
34+
} else if meta.is_event() {
35+
meta.level() <= &Level::DEBUG
36+
} else {
37+
meta.level() <= &Level::INFO
38+
}
39+
})
40+
.done()
41+
.run();
42+
43+
let _guard = tracing::subscriber::set_default(subscriber);
44+
45+
// Ensure that the `_event` and `_span` alternatives work corretly
46+
assert!(!tracing::event_enabled!(Level::TRACE));
47+
assert!(tracing::event_enabled!(Level::DEBUG));
48+
assert!(tracing::span_enabled!(Level::TRACE));
49+
50+
// target variants
51+
assert!(tracing::span_enabled!(target: "debug_module", Level::DEBUG));
52+
assert!(tracing::event_enabled!(target: "debug_module", Level::DEBUG));
2453
}

‎tracing/tests/macros.rs‎

Lines changed: 30 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
#![deny(warnings)]
22
use tracing::{
3-
callsite, debug, debug_span, enabled, error, error_span, event, info, info_span, span, trace,
4-
trace_span, warn, warn_span, Level,
3+
callsite, debug, debug_span, enabled, error, error_span, event, event_enabled, info, info_span,
4+
span, span_enabled, trace, trace_span, warn, warn_span, Level,
55
};
66

77
// Tests that macros work across various invocation syntax.
@@ -348,6 +348,34 @@ fn enabled() {
348348
enabled!(target: "rando", Level::DEBUG, field);
349349
}
350350

351+
#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)]
352+
#[test]
353+
fn span_enabled() {
354+
span_enabled!(Level::DEBUG, foo, bar.baz, quux,);
355+
span_enabled!(Level::DEBUG, message);
356+
span_enabled!(Level::INFO, foo, bar.baz, quux, message,);
357+
span_enabled!(Level::INFO, foo, bar., message,);
358+
span_enabled!(Level::DEBUG, foo);
359+
360+
span_enabled!(Level::DEBUG);
361+
span_enabled!(target: "rando", Level::DEBUG);
362+
span_enabled!(target: "rando", Level::DEBUG, field);
363+
}
364+
365+
#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)]
366+
#[test]
367+
fn event_enabled() {
368+
event_enabled!(Level::DEBUG, foo, bar.baz, quux,);
369+
event_enabled!(Level::DEBUG, message);
370+
event_enabled!(Level::INFO, foo, bar.baz, quux, message,);
371+
event_enabled!(Level::INFO, foo, bar., message,);
372+
event_enabled!(Level::DEBUG, foo);
373+
374+
event_enabled!(Level::DEBUG);
375+
event_enabled!(target: "rando", Level::DEBUG);
376+
event_enabled!(target: "rando", Level::DEBUG, field);
377+
}
378+
351379
#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)]
352380
#[test]
353381
fn locals_with_message() {

0 commit comments

Comments
 (0)