RetroSearch Browse

Home - News ( United States | United Kingdom | Italy | Germany ) - Football scores

Showing content from https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html below:

EnvFilter in tracing_subscriber::filter - Rust

pub struct EnvFilter {  }

Available on crate features env-filter and std only. Expand description

A Layer which filters spans and events based on a set of filter directives.

EnvFilter implements both the Layer and Filter traits, so it may be used for both global filtering and per-layer filtering, respectively. See the documentation on filtering with Layers for details.

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.

§Directives

A filter consists of one or more comma-separated 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 matches the std::fmt::Debug output from the value.
level sets a maximum verbosity level accepted by this directive.

When a field value directive ([{<FIELD NAME>=<FIELD_VALUE>}]=...) matches a value’s std::fmt::Debug output (i.e., the field value in the directive is not a bool, i64, u64, or f64 literal), the matched pattern may be interpreted as either a regular expression or as the precise expected output of the field’s std::fmt::Debug implementation. By default, these filters are interpreted as regular expressions, but this can be disabled using the Builder::with_regex builder method to use precise matching instead.

When field value filters are interpreted as regular expressions, the [regex-automata crate’s regular expression syntax][re-syntax] is supported.

Note: When filters are constructed from potentially untrusted inputs, disabling regular expression matching is strongly recommended.

§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", ...);

§Example Syntax

tokio::net=info will enable all spans or events that:
- have the tokio::net target,
- at the level info or above.
warn,tokio::net=info will enable all spans and events that:
- are at the level warn or above, or
- 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.

§Examples

Parsing an EnvFilter from the default environment variable (RUST_LOG):

use tracing_subscriber::{EnvFilter, fmt, prelude::*};

tracing_subscriber::registry()
    .with(fmt::layer())
    .with(EnvFilter::from_default_env())
    .init();

Parsing an EnvFilter from a user-provided environment variable:

use tracing_subscriber::{EnvFilter, fmt, prelude::*};

tracing_subscriber::registry()
    .with(fmt::layer())
    .with(EnvFilter::from_env("MYAPP_LOG"))
    .init();

Using EnvFilter as a per-layer filter to filter only a single Layer:

use tracing_subscriber::{EnvFilter, fmt, prelude::*};

let filter = EnvFilter::from_default_env();

let filtered_layer = fmt::layer().with_filter(filter);

let unfiltered_layer = tracing_subscriber::registry()
    .with(filtered_layer)
    .with(unfiltered_layer)
    .init();

§Constructing EnvFilters

An EnvFilter is be constructed by parsing a string containing one or more directives. The EnvFilter::new constructor parses an EnvFilter from a string, ignoring any invalid directives, while EnvFilter::try_new returns an error if invalid directives are encountered. Similarly, the EnvFilter::from_env and EnvFilter::try_from_env constructors parse an EnvFilter from the value of the provided environment variable, with lossy and strict validation, respectively.

A builder interface is available to set additional configuration options prior to parsing an EnvFilter. See the Builder type’s documentation for details on the options that can be configured using the builder.

Source § Source

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

Source Source

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

If the environment variable is empty or not set, or if it contains only invalid directives, a default directive enabling the ERROR level is added.