Update README

Author: CAD97

README.md

@@ -2,10 +2,27 @@
 
 A system for filtering/querying structured tracing records.
 
-Very much in-progress. **Approximately nothing works yet**.
+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.
 
 ## Filters
 
+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](https://lib.rs/crates/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.
+
+[CVE-20222-24713]: https://github.com/rust-lang/regex/security/advisories/GHSA-m5pq-gvj9-9vr8
+
 ### Simple filters
 
 tracing-filter is 99.999% compatible with [env_logger](lib.rs/env_logger)'s
@@ -15,32 +32,63 @@ filter syntax. As such, you can write simple filters the way you always have:
 - `my_app=debug` — filter to `DEBUG` or higher events only from `my_app`
 - `warn,my_app::module=trace` — get warning events and trace `my_app::module`
 - `off` — disable all logging
-- `trace/foo` — get all events whose message contains "`foo`"
+- `debug/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`. The only non-compatible behavior is that to use
-a simple filter, the filter must not start with the character `(`. This only
-impacts log events that specify a custom `target`. Additionally, `/filter` can
-only be used with the `regex` feature; it's ignored otherwise. With the
-env_logger crate, it would be interpreted as a simple substring 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%<sup>†</sup> functional in the `tracing_filter::simple` module.**
+
+<sup>†</sup>: tracing does not allow filtering on events' fields' contents
+[yet](https://github.com/tokio-rs/tracing/pull/2008). tracing-filter chooses to
+just siliently ignore the regex filter for the time being (but it does validate
+the filter).
+
+### Legacy filters
+
+The filter syntax supported by [email protected]'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.
 
-If the filter is a simple filter, it must entirely be a simple filter.
-You may not mix simple filters with query filters.
+As such, you can use all of the filters that you have been using:
+
+- `warn` — filter to only events of level `WARN` or `ERROR`
+- `my_app=debug` — filter to `DEBUG` or higher events only from `my_app`
+- `warn,my_app::module=trace` — get warning events and trace `my_app::module`
+- `off` — 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 `true`
+- `target[span]` — filter to events within a span with target `target` and name `span`
+
+In general, the syntax is `target[span{field=value}]=level`.
+
+**This should be 100% functional in the `tracing_filter::legacy` module.**
 
 ### Query filters
 
 Query filters are tracing-filter's way of selecting events and taking advantage
-of tracing's structured events.
+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.**
 
 ## Why not use tracing-filter?
 
-- tracing-filter doesn't work yet
-- You want compatibility with [email protected]'s `EnvFilter`
-- You don't want to pull in a nonstandard tracing-subscriber layer
+- tracing-filter is highly experimental
+- tracing-filter is not officially supported by the tracing team
+- tracing-filter is not published to crates-io
+- tracing-filter works with the unpublished tracing 0.2.0 ecosystem
 
 ## Why use tracing-filter?
 
-- More configurable than tracing-subscriber@0.2's `EnvFilter`
+- More configurable than tracing-subscriber@0.3's `EnvFilter`
 - You want your runtime filter syntax to work for serialized event queries
 - You like the author and want them to feel proud of themself
+- We have nice [miette](https://lib.rs/miette)-powered errors :smile: