logo
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 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

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

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

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

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

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

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.

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.

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

Formats the value using the given formatter. Read more

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

Formats the value using the given formatter. Read more

Performs the conversion.

The associated error which can be returned from parsing.

Parses a string s to return a value of this type. 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

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

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

Performs late initialization when attaching a Layer to a Subscriber. 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 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

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

Performs the conversion.

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more

Instruments this type with the current Span, returning an Instrumented wrapper. Read more

Performs the conversion.

Converts the given value to a String. 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.

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more