Struct cs_trace::EnvFilter

pub struct EnvFilter { /* fields omitted */ }

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 Spans and Events. 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 targets h2, tokio::net, or tide::server. For more information on targets, please refer to Metadata’s documentation.
• span matches on the span’s name. If a span directive is provided alongside a target, the span directive will match on spans within the target.
• field matches on fields within spans. Field names can also be supplied without a value and will match on any Span or Event 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 the std::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 and value directives. If a value is provided, a field must also be provided. However, the converse does not hold, as fields can be matched without a value.
• If only a level is provided, it will set the maximum level for all Spans and Events 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.
• my_crate[span_a]=trace will enable all spans and events that:
  • are within the span_a span or named span_a if span_a has the target my_crate,
  • at the level trace or above.
• [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 value bob,
  • at any level.

The Targets type implements a similar form of filtering, but without the ability to dynamically enable events based on the current span context, and without filtering on field values. When these features are not required, Targets provides a lighter-weight alternative to EnvFilter.

Implementations

impl EnvFilter

pub const DEFAULT_ENV: &'static str

RUST_LOG is the default environment variable used by EnvFilter::from_default_env and EnvFilter::try_from_default_env.

pub fn from_default_env() -> EnvFilter

Returns a new EnvFilter from the value of the RUST_LOG environment variable, ignoring any invalid filter directives.

pub fn from_env<A>(env: A) -> EnvFilter where
    A: AsRef<str>, 

Returns a new EnvFilter from the value of the given environment variable, ignoring any invalid filter directives.

pub fn new<S>(dirs: S) -> EnvFilter where
    S: AsRef<str>, 

Returns a new EnvFilter from the directives in the given string, ignoring any that are invalid.

pub fn try_new<S>(dirs: S) -> Result<EnvFilter, ParseError> where
    S: AsRef<str>, 

Returns a new EnvFilter from the directives in the given string, or an error if any are invalid.

pub fn try_from_default_env() -> Result<EnvFilter, 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.

pub fn try_from_env<A>(env: A) -> Result<EnvFilter, FromEnvError> where
    A: AsRef<str>, 

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.

pub fn add_directive(self, directive: Directive) -> EnvFilter

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

impl Debug for EnvFilter

pub fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Default for EnvFilter

pub fn default() -> EnvFilter

Returns the “default value” for a type.

impl Display for EnvFilter

pub fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl<S> From<S> for EnvFilter where
    S: AsRef<str>, 

pub fn from(s: S) -> EnvFilter

Performs the conversion.

impl FromStr for EnvFilter

type Err = ParseError

The associated error which can be returned from parsing.

pub fn from_str(spec: &str) -> Result<EnvFilter, <EnvFilter as FromStr>::Err>

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

impl<S> Layer<S> for EnvFilter where
    S: Subscriber, 

pub 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.

pub fn max_level_hint(&self) -> Option<LevelFilter>

pub 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.

pub 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.

pub fn on_record(&self, id: &Id, values: &Record<'_>, Context<'_, S>)

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

pub fn on_enter(&self, id: &Id, Context<'_, S>)

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

pub fn on_exit(&self, id: &Id, Context<'_, S>)

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

pub fn on_close(&self, id: Id, Context<'_, S>)

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

fn on_layer(&mut self, subscriber: &mut S)

Performs late initialization when attaching a Layer to a Subscriber.

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.

fn on_event(&self, _event: &Event<'_>, _ctx: Context<'_, S>)

Notifies this layer that an event has occurred.

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.

fn and_then<L>(self, layer: L) -> Layered<L, Self, S> where
    L: Layer<S>, 

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

fn with_subscriber(self, inner: S) -> Layered<Self, S, S>

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

fn with_filter<F>(self, filter: F) -> Filtered<Self, F, S> where
    F: Filter<S>, 

Combines self with a Filter, returning a Filtered layer.