logo
pub struct Targets(_);
Expand description

A filter that enables or disables spans and events based on their target and level.

Targets are typically equal to the Rust module path of the code where the span or event was recorded, although they may be overridden.

This type can be used for both per-layer filtering (using its Filter implementation) and global filtering (using its Layer implementation).

See the documentation on filtering with layers for details.

Filtering With Targets

A Targets filter consists of one or more target prefixes, paired with LevelFilters. If a span or event’s target begins with one of those prefixes, and its level is at or below the LevelFilter enabled for that prefix, then the span or event will be enabled.

This is similar to the behavior implemented by the env_logger crate in the log ecosystem.

The EnvFilter type also provided by this crate is very similar to Targets, but is capable of a more sophisticated form of filtering where events may also be enabled or disabled based on the span they are recorded in. Targets can be thought of as a lighter-weight form of EnvFilter that can be used instead when this dynamic filtering is not required.

Examples

A Targets filter can be constructed by programmatically adding targets and levels to enable:

use tracing_subscriber::{filter, prelude::*};
use tracing_core::Level;

let filter = filter::Targets::new()
    // Enable the `INFO` level for anything in `my_crate`
    .with_target("my_crate", Level::INFO)
    // Enable the `DEBUG` level for a specific module.
    .with_target("my_crate::interesting_module", Level::DEBUG);

// Build a new subscriber with the `fmt` layer using the `Targets`
// filter we constructed above.
tracing_subscriber::registry()
    .with(tracing_subscriber::fmt::layer())
    .with(filter)
    .init();

LevelFilter::OFF can be used to disable a particular target:

use tracing_subscriber::filter::{Targets, LevelFilter};
use tracing_core::Level;

let filter = Targets::new()
    .with_target("my_crate", Level::INFO)
    // Disable all traces from `annoying_module`.
    .with_target("my_crate::annoying_module", LevelFilter::OFF);

Alternatively, Targets implements std::str::FromStr, allowing it to be parsed from a comma-delimited list of target=level pairs. For example:

use tracing_subscriber::filter;
use tracing_core::Level;

let filter = "my_crate=info,my_crate::interesting_module=trace,other_crate=debug"
    .parse::<filter::Targets>()?;

// The parsed filter is identical to a filter constructed using `with_target`:
assert_eq!(
    filter,
    filter::Targets::new()
        .with_target("my_crate", Level::INFO)
        .with_target("my_crate::interesting_module", Level::TRACE)
        .with_target("other_crate", Level::DEBUG)
);

This is particularly useful when the list of enabled targets is configurable by the user at runtime.

The Targets filter can be used as a per-layer filter and as a global filter:

use tracing_subscriber::{
    fmt,
    filter::{Targets, LevelFilter},
    prelude::*,
};
use tracing_core::Level;
use std::{sync::Arc, fs::File};

// A layer that logs events to stdout using the human-readable "pretty"
// format.
let stdout_log = fmt::layer().pretty();

// A layer that logs events to a file, using the JSON format.
let file = File::create("debug_log.json")?;
let debug_log = fmt::layer()
    .with_writer(Arc::new(file))
    .json();

tracing_subscriber::registry()
    // Only log INFO and above to stdout, unless the span or event
    // has the `my_crate::cool_module` target prefix.
    .with(stdout_log
        .with_filter(
            Targets::default()
                .with_target("my_crate::cool_module", Level::DEBUG)
                .with_default(Level::INFO)
       )
    )
    // Log everything enabled by the global filter to `debug_log.json`.
    .with(debug_log)
    // Configure a global filter for the whole subscriber stack. This will
    // control what spans and events are recorded by both the `debug_log`
    // and the `stdout_log` layers, and `stdout_log` will *additionally* be
    // filtered by its per-layer filter.
    .with(
        Targets::default()
            .with_target("my_crate", Level::TRACE)
            .with_target("other_crate", Level::INFO)
            .with_target("other_crate::annoying_module", LevelFilter::OFF)
            .with_target("third_crate", Level::DEBUG)
    ).init();

Implementations

Returns a new Targets filter.

This filter will enable no targets. Call with_target or with_targets to add enabled targets, and with_default to change the default level enabled for spans and events that didn’t match any of the provided targets.

Enables spans and events with targets starting with the provided target prefix if they are at or below the provided LevelFilter.

Examples
use tracing_subscriber::filter;
use tracing_core::Level;

let filter = filter::Targets::new()
    // Enable the `INFO` level for anything in `my_crate`
    .with_target("my_crate", Level::INFO)
    // Enable the `DEBUG` level for a specific module.
    .with_target("my_crate::interesting_module", Level::DEBUG);

LevelFilter::OFF can be used to disable a particular target:

use tracing_subscriber::filter::{Targets, LevelFilter};
use tracing_core::Level;

let filter = Targets::new()
    .with_target("my_crate", Level::INFO)
    // Disable all traces from `annoying_module`.
    .with_target("my_crate::interesting_module", LevelFilter::OFF);

Adds targets from an iterator of target-LevelFilter pairs to this filter.

Examples
use tracing_subscriber::filter;
use tracing_core::Level;

let filter = filter::Targets::new()
    .with_targets(vec![
        ("my_crate", Level::INFO),
        ("my_crate::some_module", Level::DEBUG),
        ("my_crate::other_module::cool_stuff", Level::TRACE),
        ("other_crate", Level::WARN)
    ]);

LevelFilter::OFF can be used to disable a particular target:

use tracing_subscriber::filter::{Targets, LevelFilter};
use tracing_core::Level;

let filter = Targets::new()
    .with_target("my_crate", Level::INFO)
    // Disable all traces from `annoying_module`.
    .with_target("my_crate::interesting_module", LevelFilter::OFF);

Sets the default level to enable for spans and events whose targets did not match any of the configured prefixes.

By default, this is LevelFilter::OFF. This means that spans and events will only be enabled if they match one of the configured target prefixes. If this is changed to a different LevelFilter, spans and events with targets that did not match any of the configured prefixes will be enabled if their level is at or below the provided level.

Returns an iterator over the target-LevelFilter pairs in this filter.

The order of iteration is undefined.

Examples
use tracing_subscriber::filter::{Targets, LevelFilter};
use tracing_core::Level;

let filter = Targets::new()
    .with_target("my_crate", Level::INFO)
    .with_target("my_crate::interesting_module", Level::DEBUG);

let mut targets: Vec<_> = filter.iter().collect();
targets.sort();

assert_eq!(targets, vec![
    ("my_crate", LevelFilter::INFO),
    ("my_crate::interesting_module", LevelFilter::DEBUG),
]);

Returns whether a target-Level pair would be enabled by this Targets.

This method can be used with module_path! from std as the target in order to emulate the behavior of the [tracing::event!] and [tracing::span!] macros.

Examples
use tracing_subscriber::filter::{Targets, LevelFilter};
use tracing_core::Level;

let filter = Targets::new()
    .with_target("my_crate", Level::INFO)
    .with_target("my_crate::interesting_module", Level::DEBUG);

assert!(filter.would_enable("my_crate", &Level::INFO));
assert!(!filter.would_enable("my_crate::interesting_module", &Level::TRACE));

Trait Implementations

Returns a copy of the value. Read more

Performs copy-assignment from source. Read more

Formats the value using the given formatter. Read more

Returns the “default value” for a type. Read more

Extends a collection with the contents of an iterator. Read more

🔬 This is a nightly-only experimental API. (extend_one #72631)

Extends a collection with exactly one element.

🔬 This is a nightly-only experimental API. (extend_one #72631)

Reserves capacity in a collection for the given number of additional elements. Read more

Returns true if this layer is interested in a span or event with the given Metadata in the current Context, similarly to Subscriber::enabled. Read more

Returns an Interest indicating whether this layer will always, sometimes, or never be interested in the given Metadata. Read more

Returns an optional hint of the highest verbosity level that this Filter will enable. Read more

Notifies this filter that a new span was constructed with the given Attributes and Id. Read more

Notifies this filter that a span with the given Id recorded the given values. Read more

Notifies this filter that a span with the given ID was entered. Read more

Notifies this filter that a span with the given ID was exited. Read more

Notifies this filter that a span with the given ID has been closed. Read more

Creates a value from an iterator. Read more

The associated error which can be returned from parsing.

Parses a string s to return a value of this type. Read more

The type of the elements being iterated over.

Which kind of iterator are we turning this into?

Creates an iterator from a value. Read more

The type of the elements being iterated over.

Which kind of iterator are we turning this into?

Creates an iterator from a value. Read more

Returns true if this layer is interested in a span or event with the given metadata in the current Context, similarly to Subscriber::enabled. Read more

Registers a new callsite with this layer, returning whether or not the layer is interested in being notified about the callsite, similarly to Subscriber::register_callsite. Read more

Performs late initialization when attaching a Layer to a Subscriber. Read more

Notifies this layer that a new span was constructed with the given Attributes and Id. Read more

Notifies this layer that a span with the given Id recorded the given values. Read more

Notifies this layer that a span with the ID span recorded that it follows from the span with the ID follows. Read more

Notifies this layer that an event has occurred.

Notifies this layer that a span with the given ID was entered.

Notifies this layer that the span with the given ID was exited.

Notifies this layer that the span with the given ID has been closed.

Notifies this layer that a span ID has been cloned, and that the subscriber returned a different ID. Read more

Composes this layer around the given Layer, returning a Layered struct implementing Layer. Read more

Composes this Layer with the given Subscriber, returning a Layered struct that implements Subscriber. Read more

Combines self with a Filter, returning a Filtered layer. Read more

Erases the type of this Layer, returning a Boxed dyn Layer trait object. Read more

This method tests for self and other values to be equal, and is used by ==. Read more

This method tests for !=.

Auto Trait Implementations

Blanket Implementations

Gets the TypeId of self. Read more

Immutably borrows from an owned value. Read more

Mutably borrows from an owned value. Read more

Returns the argument unchanged.

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

The resulting type after obtaining ownership.

Creates owned data from borrowed data, usually by cloning. Read more

🔬 This is a nightly-only experimental API. (toowned_clone_into #41263)

Uses borrowed data to replace owned data, usually by cloning. Read more

The type returned in the event of a conversion error.

Performs the conversion.

The type returned in the event of a conversion error.

Performs the conversion.