A system for filtering/querying structured tracing records.
Very much in-progress. Things are in various states of (non)functional.
Currently only targets filtering events as they are collected. However, I would like to support filtering recorded events as well.
When you construct a Filter type, you determine which kind of filters it
supports. You cannot mix different kinds of filters in one filtering layer.
Note that a complicated filter can slow down your tracing performance, so using a filter from an untrusted (i.e. user) source is typically not recommended. This is particularly important for legacy and query filters, however; because they use regex-automata to implement unbuffered regex filtering, they are vulnerable to unbounded regex compilation time à la [CVE-20222-24713]. Simple filters do not do unbuffered regex evaluation, so instead use the regex crate directly, which has mitigated this issue.
tracing-filter is 99.999% compatible with env_logger's filter syntax. As such, you can write simple filters the way you always have:
warn — filter to only events of level WARN or ERRORmy_app=debug — filter to DEBUG or higher events only from my_appwarn,my_app::module=trace — get warning events and trace my_app::moduleoff — disable all loggingdebug/foo — filter to DEBUG or higher events whose message contains "foo"In general, the syntax is target=level/regex. An event is included if its
target starts with the listed target, its level passes the level filter,
and its message matches regex. With the env_logger crate, the regex string
is a simple substring match if you don't enable the regex feature; with our
simple filters,
This should be 99%† functional in the tracing_filter::simple module.
†: tracing does not allow filtering on events' fields' contents yet. tracing-filter chooses to just siliently ignore the regex filter for the time being (but it does validate the filter).
The filter syntax supported by tracing-subscriber@0.3's EnvFilter, complete
with all of its p̛̭a͖͕ŕ̯̪̥͈̠̙̣s͙̪̮̟͠i̥̞̠n͍̙̭͡g̸̜̤̦̤̳͍ ͓͜ẉ̨̳̠̗̗i̱t͚̹͉̯h̢̩̤̹͙̩͙ ̪̻͈r̻̙̥̭̯̫e̮̭̞̣̮͕̪g҉̦͚̬̖e͇̕x̛͖̣̮̞̜ͅ "peculiarites"; 100% bug-for-bug compatible.
As such, you can use all of the filters that you have been using:
warn — filter to only events of level WARN or ERRORmy_app=debug — filter to DEBUG or higher events only from my_appwarn,my_app::module=trace — get warning events and trace my_app::moduleoff — disable all logging[span]=debug — filter to DEBUG or higher events inside a span named span[{field}] — filter to events with a field field or within a span with name field[{key=val}] — filter to events within a span with field key that matches the regex val[{key=0}] — filter to events within a span with field key that recorded a number that equals 0[{key=true}] — filter to events within a span with field key that recorded a boolean value of truetarget[span] — filter to events within a span with target target and name spanIn general, the syntax is target[span{field=value}]=level.
This should be 100% functional in the tracing_filter::legacy module.
Query filters are tracing-filter's way of selecting events and taking advantage
of tracing's structured events. Query filters are a 99% superset of simple
filters; specifically, for each , separated directive, it's treated as a query
filter if and only if it starts with (; otherwise it is treated as a simple
filter.
This is still undergoing design work.
EnvFilter