Struct tracing_subscriber::filter::EnvFilter
source · [−]pub struct EnvFilter { /* private fields */ }
Expand description
A Layer
which filters spans and events based on a set of filter
directives.
Directives
A filter consists of one or more directives which match on Span
s and Event
s.
Each directive may have a corresponding maximum verbosity level
which
enables (e.g., selects for) spans and events that match. Like log
,
tracing
considers less exclusive levels (like trace
or info
) to be more
verbose than more exclusive levels (like error
or warn
).
The directive syntax is similar to that of env_logger
’s. At a high level, the syntax for directives
consists of several parts:
target[span{field=value}]=level
Each component (target
, span
, field
, value
, and level
) will be covered in turn.
target
matches the event or span’s target. In general, this is the module path and/or crate name. Examples of targetsh2
,tokio::net
, ortide::server
. For more information on targets, please refer toMetadata
’s documentation.span
matches on the span’s name. If aspan
directive is provided alongside atarget
, thespan
directive will match on spans within thetarget
.field
matches on fields within spans. Field names can also be supplied without avalue
and will match on anySpan
orEvent
that has a field with that name. For example:[span{field=\"value\"}]=debug
,[{field}]=trace
.value
matches on the value of a span’s field. If a value is a numeric literal or a bool, it will match only on that value. Otherwise, this filter acts as a regex on thestd::fmt::Debug
output from the value.level
sets a maximum verbosity level accepted by this directive.
Usage Notes
- The portion of the directive which is included within the square brackets is
tracing
-specific. - Any portion of the directive can be omitted.
- The sole exception are the
field
andvalue
directives. If avalue
is provided, afield
must also be provided. However, the converse does not hold, as fields can be matched without a value.
- The sole exception are the
- If only a level is provided, it will set the maximum level for all
Span
s andEvent
s that are not enabled by other filters. - A directive without a level will enable anything that it matches. This is equivalent to
=trace
. - When a crate has a dash in its name, the default target for events will be the crate’s module path as it appears in Rust. This means every dash will be replaced with an underscore.
- A dash in a target will only appear when being specified explicitly:
tracing::info!(target: "target-name", ...);
Examples
tokio::net=info
will enable all spans or events that:- have the
tokio::net
target, - at the level
info
or above.
- have the
my_crate[span_a]=trace
will enable all spans and events that:- are within the
span_a
span or namedspan_a
ifspan_a
has the targetmy_crate
, - at the level
trace
or above.
- are within the
[span_b{name=\"bob\"}]
will enable all spans or event that:- have any target,
- are inside a span named
span_b
, - which has a field named
name
with valuebob
, - at any level.
Implementations
sourceimpl EnvFilter
impl EnvFilter
sourcepub const DEFAULT_ENV: &'static str = "RUST_LOG"
pub const DEFAULT_ENV: &'static str = "RUST_LOG"
RUST_LOG
is the default environment variable used by
EnvFilter::from_default_env
and EnvFilter::try_from_default_env
.
sourcepub fn from_default_env() -> Self
pub fn from_default_env() -> Self
Returns a new EnvFilter
from the value of the RUST_LOG
environment
variable, ignoring any invalid filter directives.
sourcepub fn from_env<A: AsRef<str>>(env: A) -> Self
pub fn from_env<A: AsRef<str>>(env: A) -> Self
Returns a new EnvFilter
from the value of the given environment
variable, ignoring any invalid filter directives.
sourcepub fn new<S: AsRef<str>>(dirs: S) -> Self
pub fn new<S: AsRef<str>>(dirs: S) -> Self
Returns a new EnvFilter
from the directives in the given string,
ignoring any that are invalid.
sourcepub fn try_new<S: AsRef<str>>(dirs: S) -> Result<Self, ParseError>
pub fn try_new<S: AsRef<str>>(dirs: S) -> Result<Self, ParseError>
Returns a new EnvFilter
from the directives in the given string,
or an error if any are invalid.
sourcepub fn try_from_default_env() -> Result<Self, FromEnvError>
pub fn try_from_default_env() -> Result<Self, FromEnvError>
Returns a new EnvFilter
from the value of the RUST_LOG
environment
variable, or an error if the environment variable contains any invalid
filter directives.
sourcepub fn try_from_env<A: AsRef<str>>(env: A) -> Result<Self, FromEnvError>
pub fn try_from_env<A: AsRef<str>>(env: A) -> Result<Self, FromEnvError>
Returns a new EnvFilter
from the value of the given environment
variable, or an error if the environment variable is unset or contains
any invalid filter directives.
sourcepub fn add_directive(self, directive: Directive) -> Self
pub fn add_directive(self, directive: Directive) -> Self
Add a filtering directive to this EnvFilter
.
The added directive will be used in addition to any previously set directives, either added using this method or provided when the filter is constructed.
Filters may be created from LevelFilter
or Level
, which will
enable all traces at or below a certain verbosity level, or
parsed from a string specifying a directive.
If a filter directive is inserted that matches exactly the same spans and events as a previous filter, but sets a different level for those spans and events, the previous directive is overwritten.
Examples
From LevelFilter
:
use tracing_subscriber::filter::{EnvFilter, LevelFilter};
let mut filter = EnvFilter::from_default_env()
.add_directive(LevelFilter::INFO.into());
Or from Level
:
let mut filter = EnvFilter::from_default_env()
.add_directive(Level::INFO.into());
Parsed from a string:
use tracing_subscriber::filter::{EnvFilter, Directive};
let mut filter = EnvFilter::try_from_default_env()?
.add_directive("my_crate::module=trace".parse()?)
.add_directive("my_crate::my_other_module::something=info".parse()?);
Trait Implementations
sourceimpl<S: Subscriber> Layer<S> for EnvFilter
impl<S: Subscriber> Layer<S> for EnvFilter
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 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 new_span(&self, attrs: &Attributes<'_>, id: &Id, _: Context<'_, S>)
fn new_span(&self, attrs: &Attributes<'_>, id: &Id, _: Context<'_, S>)
Notifies this layer that a new span was constructed with the given
Attributes
and Id
. Read more
sourcefn on_record(&self, id: &Id, values: &Record<'_>, _: Context<'_, S>)
fn on_record(&self, id: &Id, values: &Record<'_>, _: Context<'_, S>)
Notifies this layer that a span with the given Id
recorded the given
values
. Read more
sourcefn on_enter(&self, id: &Id, _: Context<'_, S>)
fn on_enter(&self, id: &Id, _: Context<'_, S>)
Notifies this layer that a span with the given ID was entered.
sourcefn on_exit(&self, id: &Id, _: Context<'_, S>)
fn on_exit(&self, id: &Id, _: Context<'_, S>)
Notifies this layer that the span with the given ID was exited.
sourcefn on_close(&self, id: Id, _: Context<'_, S>)
fn on_close(&self, id: Id, _: Context<'_, S>)
Notifies this layer that the span with the given ID has been closed.
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_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
Auto Trait Implementations
impl RefUnwindSafe for EnvFilter
impl Send for EnvFilter
impl Sync for EnvFilter
impl Unpin for EnvFilter
impl UnwindSafe for EnvFilter
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> Instrument for T
impl<T> Instrument for T
sourcefn instrument(self, span: Span) -> Instrumented<Self>
fn instrument(self, span: Span) -> Instrumented<Self>
sourcefn in_current_span(self) -> Instrumented<Self>
fn in_current_span(self) -> Instrumented<Self>
sourceimpl<T> WithSubscriber for T
impl<T> WithSubscriber for T
sourcefn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self> where
S: Into<Dispatch>,
fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self> where
S: Into<Dispatch>,
Attaches the provided Subscriber
to this type, returning a
WithDispatch
wrapper. Read more
sourcefn with_current_subscriber(self) -> WithDispatch<Self>
fn with_current_subscriber(self) -> WithDispatch<Self>
Attaches the current default Subscriber
to this type, returning a
WithDispatch
wrapper. Read more