subscriber: added builder for filter Directive

Motivation
----------

1. There are some filters which can not be created with the current Directive string repr syntax, like e.g. the strings `bool`, `1` or `2.3` or values containing characters including but not limited to `}],` (for some of this there are partial fixes in other PRS). Furthermore updating the syntax the accommodate this is always a potential braking change, one which also can be subtle to detect.

2. Sometimes there is need to create `Directives` programmatically, e.g. from a different kind of logging config or to set more complicated defaults.

3. We might want to add other matching capabilities in the future which might not be re presentable in the string syntax (or at least entail a braking change). Like e.g. matching fields regex, matching based on `dyn Value`, a field matching the string `true` and boolean `true` at the same time,  etc.

By allowing programmatic creation of `Directive`s we allow downstream users to work around existing issues, experiment with solution to such issues in external crates and in addition set the foundation for adding future matching capabilities in the future.

Solution
--------

- adds `Directive::builder()` / `DirectiveBuilder`
- `ValueMatch` is now public, but wrapped to that we can freely extend and change it without braking changes

Workaround For: tokio-rs#1584, tokio-rs#1181
Fixes: tokio-rs#2507, tokio-rs#404
Refs: tokio-rs#1584, tokio-rs#1181

tracing-subscriber/src/filter/env/directive.rs

@@ -1,16 +1,38 @@
+pub(super) mod builder;
+
 pub(crate) use crate::filter::directive::{FilterVec, ParseError, StaticDirective};
 use crate::filter::{
     directive::{DirectiveSet, Match},
     env::{field, FieldMap},
     level::LevelFilter,
 };
+use builder::Builder;
 use once_cell::sync::Lazy;
 use regex::Regex;
 use std::{cmp::Ordering, fmt, iter::FromIterator, str::FromStr};
 use tracing_core::{span, Level, Metadata};
 
 /// A single filtering directive.
-// TODO(eliza): add a builder for programmatically constructing directives?
+///
+/// Directives apply a [`LevelFilter`] to any matching [span].
+///
+/// A span matches if all of following applies:
+///
+/// - the [target] must start with the directives target prefix, or no target prefix is configured
+/// - the [name] of the [span] must match exactly the configured name, or no name is configured
+/// - all configured [field]s must appear in the [span], it can contain additional [field]s
+/// - if for a [field] a [value] matcher is configured it must match too
+///   - be aware that value matchers for primitives (`bool`, `f64`, `u64`, `i64`) doesn't match primitives recorded
+///     using a debug or display recording (`?` and `%` in [span macros] or [event macros])
+///
+/// [span]: mod@tracing::span
+/// [target]: fn@tracing::Metadata::target
+/// [name]: fn@tracing::Metadata::name
+/// [field]: fn@tracing::Metadata::fields
+/// [value]: tracing#recording-fields
+/// [span macros]: macro@tracing::span
+/// [event macros]: macro@tracing::event
+///
 #[derive(Debug, Eq, PartialEq, Clone)]
 #[cfg_attr(docsrs, doc(cfg(feature = "env-filter")))]
 pub struct Directive {
@@ -36,6 +58,22 @@ pub(crate) struct MatchSet<T> {
 }
 
 impl Directive {
+    /// Returns a [builder] that can be used to configure a new [`Directive`]
+    /// instance.
+    ///
+    /// The [`Builder`] type is used programmatically create a [`Directive`]
+    /// instead of parsing it from a string or the environment. It allows
+    /// creating directives which due to limitations of the syntax for
+    /// environment variables can not be created using the parser.
+    ///
+    /// Conceptually the builder starts with a [`Directive`] equivalent parsing
+    /// `[{}]` as directive, i.e. enable everything at a tracing level.
+    ///
+    /// [builder]: https://rust-unofficial.github.io/patterns/patterns/creational/builder.html
+    pub fn builder() -> Builder {
+        Builder::default()
+    }
+
     pub(super) fn has_name(&self) -> bool {
         self.in_span.is_some()
     }
@@ -110,12 +148,7 @@ impl Directive {
 
     pub(super) fn deregexify(&mut self) {
         for field in &mut self.fields {
-            field.value = match field.value.take() {
-                Some(field::ValueMatch::Pat(pat)) => {
-                    Some(field::ValueMatch::Debug(pat.into_debug_match()))
-                }
-                x => x,
-            }
+            field.value = field.value.take().map(field::ValueMatch::deregexify);
         }
     }
 

tracing-subscriber/src/filter/env/directive/builder.rs

@@ -0,0 +1,102 @@
+use core::fmt::Debug;
+
+use tracing_core::LevelFilter;
+
+use crate::filter::{env::field, ValueMatch};
+
+use super::Directive;
+
+/// A [builder] for constructing new [`Directive`]s.
+///
+/// [builder]: https://rust-unofficial.github.io/patterns/patterns/creational/builder.html
+#[derive(Debug, Clone)]
+#[must_use]
+pub struct Builder {
+    in_span: Option<String>,
+    fields: Vec<field::Match>,
+    target: Option<String>,
+    level: LevelFilter,
+}
+
+// ==== impl Builder ====
+
+impl Builder {
+    /// Sets the [`LevelFilter`] which is applied to any [span] matching the directive.
+    ///
+    /// The matching algorithm is explained in the [`Directive`]s documentation.
+    ///
+    /// [span]: mod@tracing::span
+    pub fn with_level(self, level: impl Into<LevelFilter>) -> Self {
+        Self {
+            level: level.into(),
+            ..self
+        }
+    }
+
+    /// Sets the [target] prefix used for matching directives to spans.
+    ///
+    /// The matching algorithm is explained in the [`Directive`]s documentation.
+    ///
+    /// [target]: fn@tracing::Metadata::target
+    pub fn with_target_prefix(self, prefix: impl Into<String>) -> Self {
+        Self {
+            target: Some(prefix.into()).filter(|target| !target.is_empty()),
+            ..self
+        }
+    }
+
+    /// Sets the [span] used for matching directives to spans.
+    ///
+    /// The matching algorithm is explained in the [`Directive`]s documentation.
+    ///
+    /// [span]: mod@tracing::span
+    pub fn with_span_name(self, name: impl Into<String>) -> Self {
+        Self {
+            in_span: Some(name.into()),
+            ..self
+        }
+    }
+
+    /// Adds a [field] used for matching directives to spans.
+    ///
+    /// Optionally a [value] can be provided, too.
+    ///
+    /// The matching algorithm is explained in the [`Directive`]s documentation.
+    ///
+    /// [field]: fn@tracing::Metadata::fields
+    /// [value]: tracing#recording-fields
+    pub fn with_field(mut self, name: impl Into<String>, value: Option<ValueMatch>) -> Self {
+        self.fields.push(field::Match {
+            name: name.into(),
+            value: value.map(field::ValueMatch::from),
+        });
+        self
+    }
+
+    /// Builds a new [`Directive`].
+    pub fn build(self) -> Directive {
+        let Self {
+            in_span,
+            fields,
+            target,
+            level,
+        } = self;
+        Directive {
+            in_span,
+            fields,
+            target,
+            level,
+        }
+    }
+}
+
+impl Default for Builder {
+    fn default() -> Self {
+        Self {
+            in_span: None,
+            fields: Vec::new(),
+            target: None,
+            level: LevelFilter::TRACE,
+        }
+    }
+}