Macro enabled

macro_rules! enabled {
    (kind: $kind:expr, target: $target:expr, $lvl:expr, { $($fields:tt)* } ) => { ... };
    (kind: $kind:expr, target: $target:expr, $lvl:expr ) => { ... };
    (target: $target:expr, $lvl:expr ) => { ... };
    (kind: $kind:expr, target: $target:expr, $lvl:expr, $($field:tt)*) => { ... };
    (target: $target:expr, $lvl:expr, $($field:tt)*) => { ... };
    (kind: $kind:expr, $lvl:expr, $($field:tt)*) => { ... };
    (kind: $kind:expr, $lvl:expr) => { ... };
    ($lvl:expr) => { ... };
    ($lvl:expr, $($field:tt)*) => { ... };
}

Checks whether a span or event is enabled based 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

Collectors can make filtering decisions based all the data included in a span or event’s Metadata. This means that it is possible for enabled! to return a false positive (indicating that something would be enabled when it actually would not be) or a false negative (indicating that something would be disabled when it would actually be enabled).

This occurs when a subscriber is using a more specific filter than the metadata provided to the enabled! macro. Some situations that can result in false positives or false negatives include:

• If a collector 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 collector to enable something that would otherwise be disabled.
• If a collector 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 collector can choose to enable only spans or only events, which enabled will not reflect.

enabled!() requires a level argument, an optional target: argument, and an optional set of field names. 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.

Examples

If the current collector is interested in recording DEBUG-level spans and events in the current file and module path, this will evaluate to true:

use tracing::{enabled, Level};

if enabled!(Level::DEBUG) {
    // some expensive work...
}

If the current collector is interested in recording spans and events in the current file and module path, with the target “my_crate”, and at the level DEBUG, this will evaluate to true:

if enabled!(target: "my_crate", Level::DEBUG) {
    // some expensive work...
}

If the current collector is interested in recording spans and events in the current file and module path, with the target “my_crate”, at the level DEBUG, and with a field named “hello”, this will evaluate to true:

if enabled!(target: "my_crate", Level::DEBUG, hello) {
    // some expensive work...
}

Alternatives

enabled! queries subscribers with Metadata where is_event and is_span both return false. Alternatively, use event_enabled! or span_enabled! to ensure one of these returns true.