| //! A `Layer` that enables or disables spans and events based on a set of |
| //! filtering directives. |
| |
| // these are publicly re-exported, but the compiler doesn't realize |
| // that for some reason. |
| #[allow(unreachable_pub)] |
| pub use self::{builder::Builder, directive::Directive, field::BadName as BadFieldName}; |
| mod builder; |
| mod directive; |
| mod field; |
| |
| use crate::{ |
| filter::LevelFilter, |
| layer::{Context, Layer}, |
| sync::RwLock, |
| }; |
| use directive::ParseError; |
| use std::{cell::RefCell, collections::HashMap, env, error::Error, fmt, str::FromStr}; |
| use thread_local::ThreadLocal; |
| use tracing_core::{ |
| callsite, |
| field::Field, |
| span, |
| subscriber::{Interest, Subscriber}, |
| Metadata, |
| }; |
| |
| /// A [`Layer`] which filters spans and events based on a set of filter |
| /// directives. |
| /// |
| /// `EnvFilter` implements both the [`Layer`](#impl-Layer<S>) and [`Filter`] traits, so it may |
| /// be used for both [global filtering][global] and [per-layer filtering][plf], |
| /// respectively. See [the documentation on filtering with `Layer`s][filtering] |
| /// 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 [`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: |
| /// |
| /// ```text |
| /// 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](Builder::with_regex) 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 `Span`s and `Event`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", ...);` |
| /// |
| /// ## 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](EnvFilter::from_default_env) (`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](EnvFilter::from_env): |
| /// |
| /// ``` |
| /// 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][plf] to filter only a single |
| /// [`Layer`]: |
| /// |
| /// ``` |
| /// use tracing_subscriber::{EnvFilter, fmt, prelude::*}; |
| /// |
| /// // Parse an `EnvFilter` configuration from the `RUST_LOG` |
| /// // environment variable. |
| /// let filter = EnvFilter::from_default_env(); |
| /// |
| /// // Apply the filter to this layer *only*. |
| /// let filtered_layer = fmt::layer().with_filter(filter); |
| /// |
| /// // Some other layer, whose output we don't want to filter. |
| /// let unfiltered_layer = // ... |
| /// # fmt::layer(); |
| /// |
| /// tracing_subscriber::registry() |
| /// .with(filtered_layer) |
| /// .with(unfiltered_layer) |
| /// .init(); |
| /// ``` |
| /// # Constructing `EnvFilter`s |
| /// |
| /// 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](EnvFilter::builder) interface is available to set additional |
| /// configuration options prior to parsing an `EnvFilter`. See the [`Builder` |
| /// type's documentation](Builder) for details on the options that can be |
| /// configured using the builder. |
| /// |
| /// [`Span`]: tracing_core::span |
| /// [fields]: tracing_core::Field |
| /// [`Event`]: tracing_core::Event |
| /// [`level`]: tracing_core::Level |
| /// [`Metadata`]: tracing_core::Metadata |
| /// [`Targets`]: crate::filter::Targets |
| /// [`env_logger`]: https://crates.io/crates/env_logger |
| /// [`Filter`]: #impl-Filter<S> |
| /// [global]: crate::layer#global-filtering |
| /// [plf]: crate::layer#per-layer-filtering |
| /// [filtering]: crate::layer#filtering-with-layers |
| #[cfg_attr(docsrs, doc(cfg(all(feature = "env-filter", feature = "std"))))] |
| #[derive(Debug)] |
| pub struct EnvFilter { |
| statics: directive::Statics, |
| dynamics: directive::Dynamics, |
| has_dynamics: bool, |
| by_id: RwLock<HashMap<span::Id, directive::SpanMatcher>>, |
| by_cs: RwLock<HashMap<callsite::Identifier, directive::CallsiteMatcher>>, |
| scope: ThreadLocal<RefCell<Vec<LevelFilter>>>, |
| regex: bool, |
| } |
| |
| type FieldMap<T> = HashMap<Field, T>; |
| |
| /// Indicates that an error occurred while parsing a `EnvFilter` from an |
| /// environment variable. |
| #[cfg_attr(docsrs, doc(cfg(all(feature = "env-filter", feature = "std"))))] |
| #[derive(Debug)] |
| pub struct FromEnvError { |
| kind: ErrorKind, |
| } |
| |
| #[derive(Debug)] |
| enum ErrorKind { |
| Parse(ParseError), |
| Env(env::VarError), |
| } |
| |
| impl EnvFilter { |
| /// `RUST_LOG` is the default environment variable used by |
| /// [`EnvFilter::from_default_env`] and [`EnvFilter::try_from_default_env`]. |
| /// |
| /// [`EnvFilter::from_default_env`]: EnvFilter::from_default_env() |
| /// [`EnvFilter::try_from_default_env`]: EnvFilter::try_from_default_env() |
| pub const DEFAULT_ENV: &'static str = "RUST_LOG"; |
| |
| // === constructors, etc === |
| |
| /// Returns a [builder] that can be used to configure a new [`EnvFilter`] |
| /// instance. |
| /// |
| /// The [`Builder`] type is used to set additional configurations, such as |
| /// [whether regular expressions are enabled](Builder::with_regex) or [the |
| /// default directive](Builder::with_default_directive) before parsing an |
| /// [`EnvFilter`] from a string or environment variable. |
| /// |
| /// [builder]: https://rust-unofficial.github.io/patterns/patterns/creational/builder.html |
| pub fn builder() -> Builder { |
| Builder::default() |
| } |
| |
| /// 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. |
| /// |
| /// To set additional configuration options prior to parsing the filter, use |
| /// the [`Builder`] type instead. |
| /// |
| /// This function is equivalent to the following: |
| /// |
| /// ```rust |
| /// use tracing_subscriber::filter::{EnvFilter, LevelFilter}; |
| /// |
| /// # fn docs() -> EnvFilter { |
| /// EnvFilter::builder() |
| /// .with_default_directive(LevelFilter::ERROR.into()) |
| /// .from_env_lossy() |
| /// # } |
| /// ``` |
| /// |
| /// [`ERROR`]: tracing::Level::ERROR |
| pub fn from_default_env() -> Self { |
| Self::builder() |
| .with_default_directive(LevelFilter::ERROR.into()) |
| .from_env_lossy() |
| } |
| |
| /// Returns a new `EnvFilter` from the value of the given 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. |
| /// |
| /// To set additional configuration options prior to parsing the filter, use |
| /// the [`Builder`] type instead. |
| /// |
| /// This function is equivalent to the following: |
| /// |
| /// ```rust |
| /// use tracing_subscriber::filter::{EnvFilter, LevelFilter}; |
| /// |
| /// # fn docs() -> EnvFilter { |
| /// # let env = ""; |
| /// EnvFilter::builder() |
| /// .with_default_directive(LevelFilter::ERROR.into()) |
| /// .with_env_var(env) |
| /// .from_env_lossy() |
| /// # } |
| /// ``` |
| /// |
| /// [`ERROR`]: tracing::Level::ERROR |
| pub fn from_env<A: AsRef<str>>(env: A) -> Self { |
| Self::builder() |
| .with_default_directive(LevelFilter::ERROR.into()) |
| .with_env_var(env.as_ref()) |
| .from_env_lossy() |
| } |
| |
| /// Returns a new `EnvFilter` from the directives in the given string, |
| /// ignoring any that are invalid. |
| /// |
| /// If the string is empty or contains only invalid directives, a default |
| /// directive enabling the [`ERROR`] level is added. |
| /// |
| /// To set additional configuration options prior to parsing the filter, use |
| /// the [`Builder`] type instead. |
| /// |
| /// This function is equivalent to the following: |
| /// |
| /// ```rust |
| /// use tracing_subscriber::filter::{EnvFilter, LevelFilter}; |
| /// |
| /// # fn docs() -> EnvFilter { |
| /// # let directives = ""; |
| /// EnvFilter::builder() |
| /// .with_default_directive(LevelFilter::ERROR.into()) |
| /// .parse_lossy(directives) |
| /// # } |
| /// ``` |
| /// |
| /// [`ERROR`]: tracing::Level::ERROR |
| pub fn new<S: AsRef<str>>(directives: S) -> Self { |
| Self::builder() |
| .with_default_directive(LevelFilter::ERROR.into()) |
| .parse_lossy(directives) |
| } |
| |
| /// Returns a new `EnvFilter` from the directives in the given string, |
| /// or an error if any are invalid. |
| /// |
| /// If the string is empty, a default directive enabling the [`ERROR`] level |
| /// is added. |
| /// |
| /// To set additional configuration options prior to parsing the filter, use |
| /// the [`Builder`] type instead. |
| /// |
| /// This function is equivalent to the following: |
| /// |
| /// ```rust |
| /// use tracing_subscriber::filter::{EnvFilter, LevelFilter}; |
| /// |
| /// # fn docs() -> Result<EnvFilter, tracing_subscriber::filter::ParseError> { |
| /// # let directives = ""; |
| /// EnvFilter::builder() |
| /// .with_default_directive(LevelFilter::ERROR.into()) |
| /// .parse(directives) |
| /// # } |
| /// ``` |
| /// |
| /// [`ERROR`]: tracing::Level::ERROR |
| pub fn try_new<S: AsRef<str>>(dirs: S) -> Result<Self, directive::ParseError> { |
| Self::builder().parse(dirs) |
| } |
| |
| /// Returns a new `EnvFilter` from the value of the `RUST_LOG` environment |
| /// variable, or an error if the environment variable is unset or contains |
| /// any invalid filter directives. |
| /// |
| /// To set additional configuration options prior to parsing the filter, use |
| /// the [`Builder`] type instead. |
| /// |
| /// This function is equivalent to the following: |
| /// |
| /// ```rust |
| /// use tracing_subscriber::EnvFilter; |
| /// |
| /// # fn docs() -> Result<EnvFilter, tracing_subscriber::filter::FromEnvError> { |
| /// EnvFilter::builder().try_from_env() |
| /// # } |
| /// ``` |
| pub fn try_from_default_env() -> Result<Self, FromEnvError> { |
| Self::builder().try_from_env() |
| } |
| |
| /// 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. |
| /// |
| /// To set additional configuration options prior to parsing the filter, use |
| /// the [`Builder`] type instead. |
| /// |
| /// This function is equivalent to the following: |
| /// |
| /// ```rust |
| /// use tracing_subscriber::EnvFilter; |
| /// |
| /// # fn docs() -> Result<EnvFilter, tracing_subscriber::filter::FromEnvError> { |
| /// # let env = ""; |
| /// EnvFilter::builder().with_env_var(env).try_from_env() |
| /// # } |
| /// ``` |
| pub fn try_from_env<A: AsRef<str>>(env: A) -> Result<Self, FromEnvError> { |
| Self::builder().with_env_var(env.as_ref()).try_from_env() |
| } |
| |
| /// 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. |
| /// |
| /// [`LevelFilter`]: super::LevelFilter |
| /// [`Level`]: tracing_core::Level |
| /// |
| /// # Examples |
| /// |
| /// From [`LevelFilter`]: |
| /// |
| /// ```rust |
| /// use tracing_subscriber::filter::{EnvFilter, LevelFilter}; |
| /// let mut filter = EnvFilter::from_default_env() |
| /// .add_directive(LevelFilter::INFO.into()); |
| /// ``` |
| /// |
| /// Or from [`Level`]: |
| /// |
| /// ```rust |
| /// # use tracing_subscriber::filter::{EnvFilter, LevelFilter}; |
| /// # use tracing::Level; |
| /// let mut filter = EnvFilter::from_default_env() |
| /// .add_directive(Level::INFO.into()); |
| /// ``` |
| /// |
| /// Parsed from a string: |
| /// |
| /// ```rust |
| /// use tracing_subscriber::filter::{EnvFilter, Directive}; |
| /// |
| /// # fn try_mk_filter() -> Result<(), Box<dyn ::std::error::Error>> { |
| /// 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()?); |
| /// # Ok(()) |
| /// # } |
| /// ``` |
| /// In the above example, substitute `my_crate`, `module`, etc. with the |
| /// name your target crate/module is imported with. This might be |
| /// different from the package name in Cargo.toml (`-` is replaced by `_`). |
| /// Example, if the package name in your Cargo.toml is `MY-FANCY-LIB`, then |
| /// the corresponding Rust identifier would be `MY_FANCY_LIB`: |
| pub fn add_directive(mut self, mut directive: Directive) -> Self { |
| if !self.regex { |
| directive.deregexify(); |
| } |
| if let Some(stat) = directive.to_static() { |
| self.statics.add(stat) |
| } else { |
| self.has_dynamics = true; |
| self.dynamics.add(directive); |
| } |
| self |
| } |
| |
| // === filtering methods === |
| |
| /// Returns `true` if this `EnvFilter` would enable the provided `metadata` |
| /// in the current context. |
| /// |
| /// This is equivalent to calling the [`Layer::enabled`] or |
| /// [`Filter::enabled`] methods on `EnvFilter`'s implementations of those |
| /// traits, but it does not require the trait to be in scope. |
| pub fn enabled<S>(&self, metadata: &Metadata<'_>, _: Context<'_, S>) -> bool { |
| let level = metadata.level(); |
| |
| // is it possible for a dynamic filter directive to enable this event? |
| // if not, we can avoid the thread loca'l access + iterating over the |
| // spans in the current scope. |
| if self.has_dynamics && self.dynamics.max_level >= *level { |
| if metadata.is_span() { |
| // If the metadata is a span, see if we care about its callsite. |
| let enabled_by_cs = self |
| .by_cs |
| .read() |
| .ok() |
| .map(|by_cs| by_cs.contains_key(&metadata.callsite())) |
| .unwrap_or(false); |
| if enabled_by_cs { |
| return true; |
| } |
| } |
| |
| let enabled_by_scope = { |
| let scope = self.scope.get_or_default().borrow(); |
| for filter in &*scope { |
| if filter >= level { |
| return true; |
| } |
| } |
| false |
| }; |
| if enabled_by_scope { |
| return true; |
| } |
| } |
| |
| // is it possible for a static filter directive to enable this event? |
| if self.statics.max_level >= *level { |
| // Otherwise, fall back to checking if the callsite is |
| // statically enabled. |
| return self.statics.enabled(metadata); |
| } |
| |
| false |
| } |
| |
| /// Returns an optional hint of the highest [verbosity level][level] that |
| /// this `EnvFilter` will enable. |
| /// |
| /// This is equivalent to calling the [`Layer::max_level_hint`] or |
| /// [`Filter::max_level_hint`] methods on `EnvFilter`'s implementations of those |
| /// traits, but it does not require the trait to be in scope. |
| /// |
| /// [level]: tracing_core::metadata::Level |
| pub fn max_level_hint(&self) -> Option<LevelFilter> { |
| if self.dynamics.has_value_filters() { |
| // If we perform any filtering on span field *values*, we will |
| // enable *all* spans, because their field values are not known |
| // until recording. |
| return Some(LevelFilter::TRACE); |
| } |
| std::cmp::max( |
| self.statics.max_level.into(), |
| self.dynamics.max_level.into(), |
| ) |
| } |
| |
| /// Informs the filter that a new span was created. |
| /// |
| /// This is equivalent to calling the [`Layer::on_new_span`] or |
| /// [`Filter::on_new_span`] methods on `EnvFilter`'s implementations of those |
| /// traits, but it does not require the trait to be in scope. |
| pub fn on_new_span<S>(&self, attrs: &span::Attributes<'_>, id: &span::Id, _: Context<'_, S>) { |
| let by_cs = try_lock!(self.by_cs.read()); |
| if let Some(cs) = by_cs.get(&attrs.metadata().callsite()) { |
| let span = cs.to_span_match(attrs); |
| try_lock!(self.by_id.write()).insert(id.clone(), span); |
| } |
| } |
| |
| /// Informs the filter that the span with the provided `id` was entered. |
| /// |
| /// This is equivalent to calling the [`Layer::on_enter`] or |
| /// [`Filter::on_enter`] methods on `EnvFilter`'s implementations of those |
| /// traits, but it does not require the trait to be in scope. |
| pub fn on_enter<S>(&self, id: &span::Id, _: Context<'_, S>) { |
| // XXX: This is where _we_ could push IDs to the stack instead, and use |
| // that to allow changing the filter while a span is already entered. |
| // But that might be much less efficient... |
| if let Some(span) = try_lock!(self.by_id.read()).get(id) { |
| self.scope.get_or_default().borrow_mut().push(span.level()); |
| } |
| } |
| |
| /// Informs the filter that the span with the provided `id` was exited. |
| /// |
| /// This is equivalent to calling the [`Layer::on_exit`] or |
| /// [`Filter::on_exit`] methods on `EnvFilter`'s implementations of those |
| /// traits, but it does not require the trait to be in scope. |
| pub fn on_exit<S>(&self, id: &span::Id, _: Context<'_, S>) { |
| if self.cares_about_span(id) { |
| self.scope.get_or_default().borrow_mut().pop(); |
| } |
| } |
| |
| /// Informs the filter that the span with the provided `id` was closed. |
| /// |
| /// This is equivalent to calling the [`Layer::on_close`] or |
| /// [`Filter::on_close`] methods on `EnvFilter`'s implementations of those |
| /// traits, but it does not require the trait to be in scope. |
| pub fn on_close<S>(&self, id: span::Id, _: Context<'_, S>) { |
| // If we don't need to acquire a write lock, avoid doing so. |
| if !self.cares_about_span(&id) { |
| return; |
| } |
| |
| let mut spans = try_lock!(self.by_id.write()); |
| spans.remove(&id); |
| } |
| |
| /// Informs the filter that the span with the provided `id` recorded the |
| /// provided field `values`. |
| /// |
| /// This is equivalent to calling the [`Layer::on_record`] or |
| /// [`Filter::on_record`] methods on `EnvFilter`'s implementations of those |
| /// traits, but it does not require the trait to be in scope |
| pub fn on_record<S>(&self, id: &span::Id, values: &span::Record<'_>, _: Context<'_, S>) { |
| if let Some(span) = try_lock!(self.by_id.read()).get(id) { |
| span.record_update(values); |
| } |
| } |
| |
| fn cares_about_span(&self, span: &span::Id) -> bool { |
| let spans = try_lock!(self.by_id.read(), else return false); |
| spans.contains_key(span) |
| } |
| |
| fn base_interest(&self) -> Interest { |
| if self.has_dynamics { |
| Interest::sometimes() |
| } else { |
| Interest::never() |
| } |
| } |
| |
| fn register_callsite(&self, metadata: &'static Metadata<'static>) -> Interest { |
| if self.has_dynamics && metadata.is_span() { |
| // If this metadata describes a span, first, check if there is a |
| // dynamic filter that should be constructed for it. If so, it |
| // should always be enabled, since it influences filtering. |
| if let Some(matcher) = self.dynamics.matcher(metadata) { |
| let mut by_cs = try_lock!(self.by_cs.write(), else return self.base_interest()); |
| by_cs.insert(metadata.callsite(), matcher); |
| return Interest::always(); |
| } |
| } |
| |
| // Otherwise, check if any of our static filters enable this metadata. |
| if self.statics.enabled(metadata) { |
| Interest::always() |
| } else { |
| self.base_interest() |
| } |
| } |
| } |
| |
| impl<S: Subscriber> Layer<S> for EnvFilter { |
| #[inline] |
| fn register_callsite(&self, metadata: &'static Metadata<'static>) -> Interest { |
| EnvFilter::register_callsite(self, metadata) |
| } |
| |
| #[inline] |
| fn max_level_hint(&self) -> Option<LevelFilter> { |
| EnvFilter::max_level_hint(self) |
| } |
| |
| #[inline] |
| fn enabled(&self, metadata: &Metadata<'_>, ctx: Context<'_, S>) -> bool { |
| self.enabled(metadata, ctx) |
| } |
| |
| #[inline] |
| fn on_new_span(&self, attrs: &span::Attributes<'_>, id: &span::Id, ctx: Context<'_, S>) { |
| self.on_new_span(attrs, id, ctx) |
| } |
| |
| #[inline] |
| fn on_record(&self, id: &span::Id, values: &span::Record<'_>, ctx: Context<'_, S>) { |
| self.on_record(id, values, ctx); |
| } |
| |
| #[inline] |
| fn on_enter(&self, id: &span::Id, ctx: Context<'_, S>) { |
| self.on_enter(id, ctx); |
| } |
| |
| #[inline] |
| fn on_exit(&self, id: &span::Id, ctx: Context<'_, S>) { |
| self.on_exit(id, ctx); |
| } |
| |
| #[inline] |
| fn on_close(&self, id: span::Id, ctx: Context<'_, S>) { |
| self.on_close(id, ctx); |
| } |
| } |
| |
| feature! { |
| #![all(feature = "registry", feature = "std")] |
| use crate::layer::Filter; |
| |
| impl<S> Filter<S> for EnvFilter { |
| #[inline] |
| fn enabled(&self, meta: &Metadata<'_>, ctx: &Context<'_, S>) -> bool { |
| self.enabled(meta, ctx.clone()) |
| } |
| |
| #[inline] |
| fn callsite_enabled(&self, meta: &'static Metadata<'static>) -> Interest { |
| self.register_callsite(meta) |
| } |
| |
| #[inline] |
| fn max_level_hint(&self) -> Option<LevelFilter> { |
| EnvFilter::max_level_hint(self) |
| } |
| |
| #[inline] |
| fn on_new_span(&self, attrs: &span::Attributes<'_>, id: &span::Id, ctx: Context<'_, S>) { |
| self.on_new_span(attrs, id, ctx) |
| } |
| |
| #[inline] |
| fn on_record(&self, id: &span::Id, values: &span::Record<'_>, ctx: Context<'_, S>) { |
| self.on_record(id, values, ctx); |
| } |
| |
| #[inline] |
| fn on_enter(&self, id: &span::Id, ctx: Context<'_, S>) { |
| self.on_enter(id, ctx); |
| } |
| |
| #[inline] |
| fn on_exit(&self, id: &span::Id, ctx: Context<'_, S>) { |
| self.on_exit(id, ctx); |
| } |
| |
| #[inline] |
| fn on_close(&self, id: span::Id, ctx: Context<'_, S>) { |
| self.on_close(id, ctx); |
| } |
| } |
| } |
| |
| impl FromStr for EnvFilter { |
| type Err = directive::ParseError; |
| |
| fn from_str(spec: &str) -> Result<Self, Self::Err> { |
| Self::try_new(spec) |
| } |
| } |
| |
| impl<S> From<S> for EnvFilter |
| where |
| S: AsRef<str>, |
| { |
| fn from(s: S) -> Self { |
| Self::new(s) |
| } |
| } |
| |
| impl Default for EnvFilter { |
| fn default() -> Self { |
| Builder::default().from_directives(std::iter::empty()) |
| } |
| } |
| |
| impl fmt::Display for EnvFilter { |
| fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { |
| let mut statics = self.statics.iter(); |
| let wrote_statics = if let Some(next) = statics.next() { |
| fmt::Display::fmt(next, f)?; |
| for directive in statics { |
| write!(f, ",{}", directive)?; |
| } |
| true |
| } else { |
| false |
| }; |
| |
| let mut dynamics = self.dynamics.iter(); |
| if let Some(next) = dynamics.next() { |
| if wrote_statics { |
| f.write_str(",")?; |
| } |
| fmt::Display::fmt(next, f)?; |
| for directive in dynamics { |
| write!(f, ",{}", directive)?; |
| } |
| } |
| Ok(()) |
| } |
| } |
| |
| // ===== impl FromEnvError ===== |
| |
| impl From<directive::ParseError> for FromEnvError { |
| fn from(p: directive::ParseError) -> Self { |
| Self { |
| kind: ErrorKind::Parse(p), |
| } |
| } |
| } |
| |
| impl From<env::VarError> for FromEnvError { |
| fn from(v: env::VarError) -> Self { |
| Self { |
| kind: ErrorKind::Env(v), |
| } |
| } |
| } |
| |
| impl fmt::Display for FromEnvError { |
| fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { |
| match self.kind { |
| ErrorKind::Parse(ref p) => p.fmt(f), |
| ErrorKind::Env(ref e) => e.fmt(f), |
| } |
| } |
| } |
| |
| impl Error for FromEnvError { |
| fn source(&self) -> Option<&(dyn Error + 'static)> { |
| match self.kind { |
| ErrorKind::Parse(ref p) => Some(p), |
| ErrorKind::Env(ref e) => Some(e), |
| } |
| } |
| } |
| |
| #[cfg(test)] |
| mod tests { |
| use super::*; |
| use tracing_core::field::FieldSet; |
| use tracing_core::*; |
| |
| struct NoSubscriber; |
| impl Subscriber for NoSubscriber { |
| #[inline] |
| fn register_callsite(&self, _: &'static Metadata<'static>) -> subscriber::Interest { |
| subscriber::Interest::always() |
| } |
| fn new_span(&self, _: &span::Attributes<'_>) -> span::Id { |
| span::Id::from_u64(0xDEAD) |
| } |
| fn event(&self, _event: &Event<'_>) {} |
| fn record(&self, _span: &span::Id, _values: &span::Record<'_>) {} |
| fn record_follows_from(&self, _span: &span::Id, _follows: &span::Id) {} |
| |
| #[inline] |
| fn enabled(&self, _metadata: &Metadata<'_>) -> bool { |
| true |
| } |
| fn enter(&self, _span: &span::Id) {} |
| fn exit(&self, _span: &span::Id) {} |
| } |
| |
| struct Cs; |
| impl Callsite for Cs { |
| fn set_interest(&self, _interest: Interest) {} |
| fn metadata(&self) -> &Metadata<'_> { |
| unimplemented!() |
| } |
| } |
| |
| #[test] |
| fn callsite_enabled_no_span_directive() { |
| let filter = EnvFilter::new("app=debug").with_subscriber(NoSubscriber); |
| static META: &Metadata<'static> = &Metadata::new( |
| "mySpan", |
| "app", |
| Level::TRACE, |
| None, |
| None, |
| None, |
| FieldSet::new(&[], identify_callsite!(&Cs)), |
| Kind::SPAN, |
| ); |
| |
| let interest = filter.register_callsite(META); |
| assert!(interest.is_never()); |
| } |
| |
| #[test] |
| fn callsite_off() { |
| let filter = EnvFilter::new("app=off").with_subscriber(NoSubscriber); |
| static META: &Metadata<'static> = &Metadata::new( |
| "mySpan", |
| "app", |
| Level::ERROR, |
| None, |
| None, |
| None, |
| FieldSet::new(&[], identify_callsite!(&Cs)), |
| Kind::SPAN, |
| ); |
| |
| let interest = filter.register_callsite(META); |
| assert!(interest.is_never()); |
| } |
| |
| #[test] |
| fn callsite_enabled_includes_span_directive() { |
| let filter = EnvFilter::new("app[mySpan]=debug").with_subscriber(NoSubscriber); |
| static META: &Metadata<'static> = &Metadata::new( |
| "mySpan", |
| "app", |
| Level::TRACE, |
| None, |
| None, |
| None, |
| FieldSet::new(&[], identify_callsite!(&Cs)), |
| Kind::SPAN, |
| ); |
| |
| let interest = filter.register_callsite(META); |
| assert!(interest.is_always()); |
| } |
| |
| #[test] |
| fn callsite_enabled_includes_span_directive_field() { |
| let filter = |
| EnvFilter::new("app[mySpan{field=\"value\"}]=debug").with_subscriber(NoSubscriber); |
| static META: &Metadata<'static> = &Metadata::new( |
| "mySpan", |
| "app", |
| Level::TRACE, |
| None, |
| None, |
| None, |
| FieldSet::new(&["field"], identify_callsite!(&Cs)), |
| Kind::SPAN, |
| ); |
| |
| let interest = filter.register_callsite(META); |
| assert!(interest.is_always()); |
| } |
| |
| #[test] |
| fn callsite_enabled_includes_span_directive_multiple_fields() { |
| let filter = EnvFilter::new("app[mySpan{field=\"value\",field2=2}]=debug") |
| .with_subscriber(NoSubscriber); |
| static META: &Metadata<'static> = &Metadata::new( |
| "mySpan", |
| "app", |
| Level::TRACE, |
| None, |
| None, |
| None, |
| FieldSet::new(&["field"], identify_callsite!(&Cs)), |
| Kind::SPAN, |
| ); |
| |
| let interest = filter.register_callsite(META); |
| assert!(interest.is_never()); |
| } |
| |
| #[test] |
| fn roundtrip() { |
| let f1: EnvFilter = |
| "[span1{foo=1}]=error,[span2{bar=2 baz=false}],crate2[{quux=\"quuux\"}]=debug" |
| .parse() |
| .unwrap(); |
| let f2: EnvFilter = format!("{}", f1).parse().unwrap(); |
| assert_eq!(f1.statics, f2.statics); |
| assert_eq!(f1.dynamics, f2.dynamics); |
| } |
| |
| #[test] |
| fn size_of_filters() { |
| fn print_sz(s: &str) { |
| let filter = s.parse::<EnvFilter>().expect("filter should parse"); |
| println!( |
| "size_of_val({:?})\n -> {}B", |
| s, |
| std::mem::size_of_val(&filter) |
| ); |
| } |
| |
| print_sz("info"); |
| |
| print_sz("foo=debug"); |
| |
| print_sz( |
| "crate1::mod1=error,crate1::mod2=warn,crate1::mod2::mod3=info,\ |
| crate2=debug,crate3=trace,crate3::mod2::mod1=off", |
| ); |
| |
| print_sz("[span1{foo=1}]=error,[span2{bar=2 baz=false}],crate2[{quux=\"quuux\"}]=debug"); |
| |
| print_sz( |
| "crate1::mod1=error,crate1::mod2=warn,crate1::mod2::mod3=info,\ |
| crate2=debug,crate3=trace,crate3::mod2::mod1=off,[span1{foo=1}]=error,\ |
| [span2{bar=2 baz=false}],crate2[{quux=\"quuux\"}]=debug", |
| ); |
| } |
| |
| #[test] |
| fn parse_empty_string() { |
| // There is no corresponding test for [`Builder::parse_lossy`] as failed |
| // parsing does not produce any observable side effects. If this test fails |
| // check that [`Builder::parse_lossy`] is behaving correctly as well. |
| assert!(EnvFilter::builder().parse("").is_ok()); |
| } |
| } |