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
LevelFilter
s. 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
sourceimpl Targets
impl Targets
sourcepub fn new() -> Self
pub fn new() -> Self
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.
sourcepub fn with_target(
self,
target: impl Into<String>,
level: impl Into<LevelFilter>
) -> Self
pub fn with_target(
self,
target: impl Into<String>,
level: impl Into<LevelFilter>
) -> Self
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);
sourcepub fn with_targets<T, L>(
self,
targets: impl IntoIterator<Item = (T, L)>
) -> Self where
String: From<T>,
LevelFilter: From<L>,
pub fn with_targets<T, L>(
self,
targets: impl IntoIterator<Item = (T, L)>
) -> Self where
String: From<T>,
LevelFilter: From<L>,
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);
sourcepub fn with_default(self, level: impl Into<LevelFilter>) -> Self
pub fn with_default(self, level: impl Into<LevelFilter>) -> Self
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.
sourcepub fn iter(&self) -> Iter<'_>ⓘNotable traits for Iter<'a>impl<'a> Iterator for Iter<'a> type Item = (&'a str, LevelFilter);
pub fn iter(&self) -> Iter<'_>ⓘNotable traits for Iter<'a>impl<'a> Iterator for Iter<'a> type Item = (&'a str, LevelFilter);
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),
]);
sourcepub fn would_enable(&self, target: &str, level: &Level) -> bool
pub fn would_enable(&self, target: &str, level: &Level) -> bool
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
sourceimpl<T, L> Extend<(T, L)> for Targets where
T: Into<String>,
L: Into<LevelFilter>,
impl<T, L> Extend<(T, L)> for Targets where
T: Into<String>,
L: Into<LevelFilter>,
sourcefn extend<I: IntoIterator<Item = (T, L)>>(&mut self, iter: I)
fn extend<I: IntoIterator<Item = (T, L)>>(&mut self, iter: I)
Extends a collection with the contents of an iterator. Read more
sourcefn extend_reserve(&mut self, additional: usize)
fn extend_reserve(&mut self, additional: usize)
Reserves capacity in a collection for the given number of additional elements. Read more
sourceimpl<S> Filter<S> for Targets
impl<S> Filter<S> for Targets
sourcefn enabled(&self, metadata: &Metadata<'_>, _: &Context<'_, S>) -> bool
fn enabled(&self, metadata: &Metadata<'_>, _: &Context<'_, S>) -> bool
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
sourcefn callsite_enabled(&self, metadata: &'static Metadata<'static>) -> Interest
fn callsite_enabled(&self, metadata: &'static Metadata<'static>) -> Interest
sourcefn max_level_hint(&self) -> Option<LevelFilter>
fn max_level_hint(&self) -> Option<LevelFilter>
Returns an optional hint of the highest verbosity level that
this Filter
will enable. Read more
sourcefn on_new_span(&self, attrs: &Attributes<'_>, id: &Id, ctx: Context<'_, S>)
fn on_new_span(&self, attrs: &Attributes<'_>, id: &Id, ctx: Context<'_, S>)
Notifies this filter that a new span was constructed with the given
Attributes
and Id
. Read more
sourcefn on_record(&self, id: &Id, values: &Record<'_>, ctx: Context<'_, S>)
fn on_record(&self, id: &Id, values: &Record<'_>, ctx: Context<'_, S>)
Notifies this filter that a span with the given Id
recorded the given
values
. Read more
sourcefn on_enter(&self, id: &Id, ctx: Context<'_, S>)
fn on_enter(&self, id: &Id, ctx: Context<'_, S>)
Notifies this filter that a span with the given ID was entered. Read more
sourceimpl<T, L> FromIterator<(T, L)> for Targets where
T: Into<String>,
L: Into<LevelFilter>,
impl<T, L> FromIterator<(T, L)> for Targets where
T: Into<String>,
L: Into<LevelFilter>,
sourceimpl IntoIterator for Targets
impl IntoIterator for Targets
sourceimpl<'a> IntoIterator for &'a Targets
impl<'a> IntoIterator for &'a Targets
sourceimpl<S> Layer<S> for Targets where
S: Subscriber,
impl<S> Layer<S> for Targets where
S: Subscriber,
sourcefn enabled(&self, metadata: &Metadata<'_>, _: Context<'_, S>) -> bool
fn enabled(&self, metadata: &Metadata<'_>, _: Context<'_, S>) -> bool
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
sourcefn register_callsite(&self, metadata: &'static Metadata<'static>) -> Interest
fn register_callsite(&self, metadata: &'static Metadata<'static>) -> Interest
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
sourcefn on_layer(&mut self, subscriber: &mut S)
fn on_layer(&mut self, subscriber: &mut S)
Performs late initialization when attaching a Layer
to a
Subscriber
. Read more
sourcefn on_new_span(&self, attrs: &Attributes<'_>, id: &Id, ctx: Context<'_, S>)
fn on_new_span(&self, attrs: &Attributes<'_>, id: &Id, ctx: Context<'_, S>)
Notifies this layer that a new span was constructed with the given
Attributes
and Id
. Read more
sourcefn on_record(&self, _span: &Id, _values: &Record<'_>, _ctx: Context<'_, S>)
fn on_record(&self, _span: &Id, _values: &Record<'_>, _ctx: Context<'_, S>)
Notifies this layer that a span with the given Id
recorded the given
values
. Read more
sourcefn on_follows_from(&self, _span: &Id, _follows: &Id, _ctx: Context<'_, S>)
fn on_follows_from(&self, _span: &Id, _follows: &Id, _ctx: Context<'_, S>)
Notifies this layer that a span with the ID span
recorded that it
follows from the span with the ID follows
. Read more
sourcefn on_event(&self, _event: &Event<'_>, _ctx: Context<'_, S>)
fn on_event(&self, _event: &Event<'_>, _ctx: Context<'_, S>)
Notifies this layer that an event has occurred.
sourcefn on_enter(&self, _id: &Id, _ctx: Context<'_, S>)
fn on_enter(&self, _id: &Id, _ctx: Context<'_, S>)
Notifies this layer that a span with the given ID was entered.
sourcefn on_exit(&self, _id: &Id, _ctx: Context<'_, S>)
fn on_exit(&self, _id: &Id, _ctx: Context<'_, S>)
Notifies this layer that the span with the given ID was exited.
sourcefn on_close(&self, _id: Id, _ctx: Context<'_, S>)
fn on_close(&self, _id: Id, _ctx: Context<'_, S>)
Notifies this layer that the span with the given ID has been closed.
sourcefn on_id_change(&self, _old: &Id, _new: &Id, _ctx: Context<'_, S>)
fn on_id_change(&self, _old: &Id, _new: &Id, _ctx: Context<'_, S>)
Notifies this layer that a span ID has been cloned, and that the subscriber returned a different ID. Read more
sourcefn and_then<L>(self, layer: L) -> Layered<L, Self, S> where
L: Layer<S>,
Self: Sized,
fn and_then<L>(self, layer: L) -> Layered<L, Self, S> where
L: Layer<S>,
Self: Sized,
Composes this layer around the given Layer
, returning a Layered
struct implementing Layer
. Read more
sourcefn with_subscriber(self, inner: S) -> Layered<Self, S> where
Self: Sized,
fn with_subscriber(self, inner: S) -> Layered<Self, S> where
Self: Sized,
Composes this Layer
with the given Subscriber
, returning a
Layered
struct that implements Subscriber
. Read more
sourcefn with_filter<F>(self, filter: F) -> Filtered<Self, F, S> where
Self: Sized,
F: Filter<S>,
fn with_filter<F>(self, filter: F) -> Filtered<Self, F, S> where
Self: Sized,
F: Filter<S>,
impl StructuralPartialEq for Targets
Auto Trait Implementations
impl RefUnwindSafe for Targets
impl Send for Targets
impl Sync for Targets
impl Unpin for Targets
impl UnwindSafe for Targets
Blanket Implementations
sourceimpl<T> BorrowMut<T> for T where
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
const: unstable · sourcefn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more
sourceimpl<T> ToOwned for T where
T: Clone,
impl<T> ToOwned for T where
T: Clone,
type Owned = T
type Owned = T
The resulting type after obtaining ownership.
sourcefn clone_into(&self, target: &mut T)
fn clone_into(&self, target: &mut T)
Uses borrowed data to replace owned data, usually by cloning. Read more