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.
Sometimes there is need to create Directives programmatically, e.g. from a different kind of logging config or to set more complicated defaults.
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 Directives 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 as we need it in the builder. But we wrapped the current implementation instead of exposing it so that we can freely change/extend it in the future.
Cavets
as we now can create filters which can not be represented with the parser (without making a breaking change to the parsing format) we no longer have the guarantee that a Display <=> FromStr round trip works
Out of Scope
currently the only way to add build Directives is by using EnvFilter::add_directive, which means there always is "some" parsed or default directive in the EnvFilter before we can add our directives. We could e.g. impl FromIterator<Directive> for EnvFilter or allow adding directives instead of parsing for building the builder. But that is outside of the scope of this PR.
Motivation
There are some filters which can not be created with the current Directive string repr syntax, like e.g. the strings
bool,1or2.3or 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.Sometimes there is need to create
Directivesprogrammatically, e.g. from a different kind of logging config or to set more complicated defaults.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 stringtrueand booleantrueat the same time, etc.By allowing programmatic creation of
Directives 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
Directive::builder()/DirectiveBuilderValueMatchis now public as we need it in the builder. But we wrapped the current implementation instead of exposing it so that we can freely change/extend it in the future.Cavets
Display <=> FromStrround trip worksOut of Scope
Directivesis by usingEnvFilter::add_directive, which means there always is "some" parsed or default directive in theEnvFilterbefore we can add our directives. We could e.g. implFromIterator<Directive>forEnvFilteror allow adding directives instead of parsing for building the builder. But that is outside of the scope of this PR.Workaround For: #1584, #1181 Fixes: #2507, #404 Refs: #1584, #1181