subscriber: add Filtered::filter_mut #1959

tfreiberg-fastly · 2022-02-24T13:04:42Z

Partially fixes #1629 (I think making reload::Handle::reload work with Filtered would be cleaner, but this approach seemed easier to me)

I assumed opening the PR against v0.1.x is correct as I couldn't find the Filtered type in master.

I think it'd be sensible to note the fact that reload::Handle::reload doesn't work with Filtered in the docs somewhere, should I add that?

Motivation

Changing the filter of a Filtered at runtime is currently only possible by replacing it with a new Filtered via the reload::Handle::reload method.
This currently doesn't work as the new Filtered won't receive a FilterId (see #1629).

While it would be desirable to just make that work, it would only be possible via a breaking change (according to Eliza) so this seems like a reasonable (and easy) workaround for now.
(I can't judge whether this method is only useful as a workaround for the bug or if it suits the public API independently)

Solution

Offer mutable access to the Filtered::filter field in the public API. This can be used via the reload::Handle::modify method to change the filter inside the existing Filtered.

hawkw

overall, this looks good to me --- thanks!

i had a couple suggestions for the documentation, and i thought we might as well also add an immutable accessor while we're here.

tracing-subscriber/src/filter/layer_filters/mod.rs

hawkw · 2022-02-24T20:56:16Z

I think it'd be sensible to note the fact that reload::Handle::reload doesn't work with Filtered in the docs somewhere, should I add that?

I would probably recommend adding examples to the reload::Handle documentation showing its use with Filtered, using this method. Then, we can add a note there saying not to use reload::Handle::reload, as well. It would be fine to do that in this branch or in a separate one --- up to you!

tracing-subscriber/src/filter/layer_filters/mod.rs

tfreiberg-fastly · 2022-02-25T14:37:51Z

tracing-subscriber/src/reload.rs

-/// Allows reloading the state of an associated `Layer`.
+/// Allows reloading the state of an associated [`Layer`](crate::layer::Layer).
+///
+/// # Examples


I used the same example, I assume that's fine?

yeah, that's fine!

i might put the examples in the top-level documentation, though --- it looks like most of the existing general usage docs are there, rather than on the individual types in this module. though, honestly, all the documentation here is rather sparse...

do you mean the documentation of the reload module or of the crate? (I moved it to the reload module docs for now)

tfreiberg-fastly · 2022-02-25T14:41:32Z

tracing-subscriber/src/reload.rs

+/// **Warning:** The [`Filtered`](crate::filter::Filtered) type currently can't be changed
+/// at runtime via the [`Handle::reload`] method.
+/// Use the [`Handle::modify`] method to change the filter instead.
+/// (see <https://github.com/tokio-rs/tracing/issues/1629>)


Not sure if you want a link to the issue in there or not, I can remove it

hawkw

some more docs suggestions --- sorry for being picky!

tracing-subscriber/src/filter/layer_filters/mod.rs

hawkw · 2022-02-25T22:56:30Z

tracing-subscriber/src/reload.rs

-/// Allows reloading the state of an associated `Layer`.
+/// Allows reloading the state of an associated [`Layer`](crate::layer::Layer).
+///
+/// # Examples


yeah, that's fine!

i might put the examples in the top-level documentation, though --- it looks like most of the existing general usage docs are there, rather than on the individual types in this module. though, honestly, all the documentation here is rather sparse...

tracing-subscriber/src/reload.rs

hawkw · 2022-02-28T21:03:34Z

tracing-subscriber/src/reload.rs

+/// Reloading a [`Filtered`](crate::filter::Filtered) layer to change the filter at runtime.
+///
+/// ```
+/// # use tracing::info;
+/// # use tracing_subscriber::{filter,fmt,reload,Registry,prelude::*};
+/// # fn main() {
+/// let (filtered_layer, reload_handle) =
+///     reload::Layer::new(fmt::Layer::default().with_filter(filter::LevelFilter::WARN));
+/// #
+/// # // specifying the Registry type is required
+/// # let _: &reload::Handle<filter::Filtered<fmt::Layer<Registry>,
+/// # filter::LevelFilter, Registry>,Registry>
+/// # = &reload_handle;
+/// #
+/// info!("This will be ignored");
+/// reload_handle.modify(|layer| *layer.filter_mut() = filter::LevelFilter::INFO);
+/// info!("This will be logged");
+/// # }
+/// ```


it would be nice to also have an example of reloading a global filtering Layer...i'm surprised we don't have that already. but we should probably add that in a follow-up PR, rather than here.

tracing-subscriber/src/filter/layer_filters/mod.rs

## Motivation Changing the filter of a Filtered at runtime is currently only possible by replacing it with a new Filtered via the reload::Handle's reload method. This currently doesn't work (see tokio-rs#1629). While it would be desirable to just make that work, it would only be possible via a breaking change (according to Eliza). Making it possible to change the filter via the handle's modify method and mutating the inner filter is an easy workaround.

hawkw

Okay, this looks good to me! Thanks for taking the time to address all of my docs nitpicks! :)

tfreiberg-fastly · 2022-03-02T09:41:53Z

thanks for the review and the suggestions!

Missing example was noticed in #1959 (comment) Should the descriptions of the examples distinguish global filtering and per-layer filtering a bit more explicitly? Co-authored-by: Eliza Weisman <eliza@buoyant.io>

Partially fixes #1629 (I think making `reload::Handle::reload` work with `Filtered` would be cleaner, but this approach seemed easier to me) I assumed opening the PR against v0.1.x is correct as I couldn't find the `Filtered` type in master. I think it'd be sensible to note the fact that `reload::Handle::reload` doesn't work with `Filtered` in the docs somewhere, should I add that? ## Motivation Changing the filter of a `Filtered` at runtime is currently only possible by replacing it with a new `Filtered` via the `reload::Handle::reload` method. This currently doesn't work as the new `Filtered` won't receive a `FilterId` (see #1629). While it would be desirable to just make that work, it would only be possible via a breaking change (according to Eliza) so this seems like a reasonable (and easy) workaround for now. (I can't judge whether this method is only useful as a workaround for the bug or if it suits the public API independently) ## Solution Offer mutable access to the `Filtered::filter` field in the public API. This can be used via the `reload::Handle::modify` method to change the filter inside the existing `Filtered`. Fixes #1629

@TimoFreiberg

# 0.3.10 (Apr 1, 2022) This release adds several new features, including a `Filter` implementation and new builder API for `EnvFilter`, support for using a `Vec<L> where L: Layer` as a `Layer`, and a number of smaller API improvements to make working with dynamic and reloadable layers easier. ### Added - **registry**: Implement `Filter` for `EnvFilter`, allowing it to be used with per-layer filtering ([#1983]) - **registry**: `Filter::on_new_span`, `Filter::on_enter`, `Filter::on_exit`, `Filter::on_close` and `Filter::on_record` callbacks to allow `Filter`s to track span states internally ([#1973], [#2017], [#2031]) - **registry**: `Filtered::filter` and `Filtered::filter_mut` accessors ([#1959]) - **registry**: `Filtered::inner` and `Filtered::inner_mut` accessors to borrow the wrapped `Layer` ([#2034]) - **layer**: Implement `Layer` for `Vec<L: Layer>`, to allow composing together a dynamically sized list of `Layer`s ([#2027]) - **layer**: `Layer::boxed` method to make type-erasing `Layer`s easier ([#2026]) - **fmt**: `fmt::Layer::writer` and `fmt::Layer::writer_mut` accessors ([#2034]) - **fmt**: `fmt::Layer::set_ansi` method to allow changing the ANSI formatting configuration at runtime ([#2034]) - **env-filter**: `EnvFilter::builder` to configure a new `EnvFilter` prior to parsing it ([#2035]) - Several documentation fixes and improvements ([#1972], [#1971], [#2023], [#2023]) ### Fixed - **fmt**: `fmt::Layer`'s auto traits no longer depend on the `Subscriber` type parameter's auto traits ([2025]) - **env-filter**: Fixed missing help text when the `ansi` feature is disabled ([#2029]) Thanks to new contributors @TimoFreiberg and @wagenet, as well as @CAD97 for contributing to this release! [#1983]: #1983 [#1973]: #1973 [#2017]: #2017 [#2031]: #2031 [#1959]: #1959 [#2034]: #2034 [#2027]: #2027 [#2026]: #2026 [#2035]: #2035 [#1972]: #1972 [#1971]: #1971 [#2023]: #2023

@TimoFreiberg

# 0.3.10 (Apr 1, 2022) This release adds several new features, including a `Filter` implementation and new builder API for `EnvFilter`, support for using a `Vec<L> where L: Layer` as a `Layer`, and a number of smaller API improvements to make working with dynamic and reloadable layers easier. ### Added - **registry**: Implement `Filter` for `EnvFilter`, allowing it to be used with per-layer filtering ([#1983]) - **registry**: `Filter::on_new_span`, `Filter::on_enter`, `Filter::on_exit`, `Filter::on_close` and `Filter::on_record` callbacks to allow `Filter`s to track span states internally ([#1973], [#2017], [#2031]) - **registry**: `Filtered::filter` and `Filtered::filter_mut` accessors ([#1959]) - **registry**: `Filtered::inner` and `Filtered::inner_mut` accessors to borrow the wrapped `Layer` ([#2034]) - **layer**: Implement `Layer` for `Vec<L: Layer>`, to allow composing together a dynamically sized list of `Layer`s ([#2027]) - **layer**: `Layer::boxed` method to make type-erasing `Layer`s easier ([#2026]) - **fmt**: `fmt::Layer::writer` and `fmt::Layer::writer_mut` accessors ([#2034]) - **fmt**: `fmt::Layer::set_ansi` method to allow changing the ANSI formatting configuration at runtime ([#2034]) - **env-filter**: `EnvFilter::builder` to configure a new `EnvFilter` prior to parsing it ([#2035]) - Several documentation fixes and improvements ([#1972], [#1971], [#2023], [#2023]) ### Fixed - **fmt**: `fmt::Layer`'s auto traits no longer depend on the `Subscriber` type parameter's auto traits ([2025]) - **env-filter**: Fixed missing help text when the `ansi` feature is disabled ([#2029]) Thanks to new contributors @TimoFreiberg and @wagenet, as well as @CAD97 for contributing to this release! [#1983]: #1983 [#1973]: #1973 [#2017]: #2017 [#2031]: #2031 [#1959]: #1959 [#2034]: #2034 [#2027]: #2027 [#2026]: #2026 [#2035]: #2035 [#1972]: #1972 [#1971]: #1971 [#2023]: #2023

@TimoFreiberg

# 0.3.10 (Apr 1, 2022) This release adds several new features, including a `Filter` implementation and new builder API for `EnvFilter`, support for using a `Vec<L> where L: Layer` as a `Layer`, and a number of smaller API improvements to make working with dynamic and reloadable layers easier. ### Added - **registry**: Implement `Filter` for `EnvFilter`, allowing it to be used with per-layer filtering ([#1983]) - **registry**: `Filter::on_new_span`, `Filter::on_enter`, `Filter::on_exit`, `Filter::on_close` and `Filter::on_record` callbacks to allow `Filter`s to track span states internally ([#1973], [#2017], [#2031]) - **registry**: `Filtered::filter` and `Filtered::filter_mut` accessors ([#1959]) - **registry**: `Filtered::inner` and `Filtered::inner_mut` accessors to borrow the wrapped `Layer` ([#2034]) - **layer**: Implement `Layer` for `Vec<L: Layer>`, to allow composing together a dynamically sized list of `Layer`s ([#2027]) - **layer**: `Layer::boxed` method to make type-erasing `Layer`s easier ([#2026]) - **fmt**: `fmt::Layer::writer` and `fmt::Layer::writer_mut` accessors ([#2034]) - **fmt**: `fmt::Layer::set_ansi` method to allow changing the ANSI formatting configuration at runtime ([#2034]) - **env-filter**: `EnvFilter::builder` to configure a new `EnvFilter` prior to parsing it ([#2035]) - Several documentation fixes and improvements ([#1972], [#1971], [#2023], [#2023]) ### Fixed - **fmt**: `fmt::Layer`'s auto traits no longer depend on the `Subscriber` type parameter's auto traits ([2025]) - **env-filter**: Fixed missing help text when the `ansi` feature is disabled ([#2029]) Thanks to new contributors @TimoFreiberg and @wagenet, as well as @CAD97 for contributing to this release! [#1983]: #1983 [#1973]: #1973 [#2017]: #2017 [#2031]: #2031 [#1959]: #1959 [#2034]: #2034 [#2027]: #2027 [#2026]: #2026 [#2035]: #2035 [#1972]: #1972 [#1971]: #1971 [#2023]: #2023

@TimoFreiberg

# 0.3.10 (Apr 1, 2022) This release adds several new features, including a `Filter` implementation and new builder API for `EnvFilter`, support for using a `Vec<L> where L: Layer` as a `Layer`, and a number of smaller API improvements to make working with dynamic and reloadable layers easier. ### Added - **registry**: Implement `Filter` for `EnvFilter`, allowing it to be used with per-layer filtering ([#1983]) - **registry**: `Filter::on_new_span`, `Filter::on_enter`, `Filter::on_exit`, `Filter::on_close` and `Filter::on_record` callbacks to allow `Filter`s to track span states internally ([#1973], [#2017], [#2031]) - **registry**: `Filtered::filter` and `Filtered::filter_mut` accessors ([#1959]) - **registry**: `Filtered::inner` and `Filtered::inner_mut` accessors to borrow the wrapped `Layer` ([#2034]) - **layer**: Implement `Layer` for `Vec<L: Layer>`, to allow composing together a dynamically sized list of `Layer`s ([#2027]) - **layer**: `Layer::boxed` method to make type-erasing `Layer`s easier ([#2026]) - **fmt**: `fmt::Layer::writer` and `fmt::Layer::writer_mut` accessors ([#2034]) - **fmt**: `fmt::Layer::set_ansi` method to allow changing the ANSI formatting configuration at runtime ([#2034]) - **env-filter**: `EnvFilter::builder` to configure a new `EnvFilter` prior to parsing it ([#2035]) - Several documentation fixes and improvements ([#1972], [#1971], [#2023], [#2023]) ### Fixed - **fmt**: `fmt::Layer`'s auto traits no longer depend on the `Subscriber` type parameter's auto traits ([2025]) - **env-filter**: Fixed missing help text when the `ansi` feature is disabled ([#2029]) Thanks to new contributors @TimoFreiberg and @wagenet, as well as @CAD97 for contributing to this release! [#1983]: #1983 [#1973]: #1973 [#2017]: #2017 [#2031]: #2031 [#1959]: #1959 [#2034]: #2034 [#2027]: #2027 [#2026]: #2026 [#2035]: #2035 [#1972]: #1972 [#1971]: #1971 [#2023]: #2023

@TimoFreiberg

# 0.3.10 (Apr 1, 2022) This release adds several new features, including a `Filter` implementation and new builder API for `EnvFilter`, support for using a `Vec<L> where L: Layer` as a `Layer`, and a number of smaller API improvements to make working with dynamic and reloadable layers easier. ### Added - **registry**: Implement `Filter` for `EnvFilter`, allowing it to be used with per-layer filtering ([#1983]) - **registry**: `Filter::on_new_span`, `Filter::on_enter`, `Filter::on_exit`, `Filter::on_close` and `Filter::on_record` callbacks to allow `Filter`s to track span states internally ([#1973], [#2017], [#2031]) - **registry**: `Filtered::filter` and `Filtered::filter_mut` accessors ([#1959]) - **registry**: `Filtered::inner` and `Filtered::inner_mut` accessors to borrow the wrapped `Layer` ([#2034]) - **layer**: Implement `Layer` for `Vec<L: Layer>`, to allow composing together a dynamically sized list of `Layer`s ([#2027]) - **layer**: `Layer::boxed` method to make type-erasing `Layer`s easier ([#2026]) - **fmt**: `fmt::Layer::writer` and `fmt::Layer::writer_mut` accessors ([#2034]) - **fmt**: `fmt::Layer::set_ansi` method to allow changing the ANSI formatting configuration at runtime ([#2034]) - **env-filter**: `EnvFilter::builder` to configure a new `EnvFilter` prior to parsing it ([#2035]) - Several documentation fixes and improvements ([#1972], [#1971], [#2023], [#2023]) ### Fixed - **fmt**: `fmt::Layer`'s auto traits no longer depend on the `Subscriber` type parameter's auto traits ([#2025]) - **env-filter**: Fixed missing help text when the `ansi` feature is disabled ([#2029]) Thanks to new contributors @TimoFreiberg and @wagenet, as well as @CAD97 for contributing to this release! [#1983]: #1983 [#1973]: #1973 [#2017]: #2017 [#2031]: #2031 [#1959]: #1959 [#2034]: #2034 [#2027]: #2027 [#2026]: #2026 [#2035]: #2035 [#1972]: #1972 [#1971]: #1971 [#2023]: #2023 [#2025]: #2025 [#2029]: #2029

Partially fixes tokio-rs#1629 (I think making `reload::Handle::reload` work with `Filtered` would be cleaner, but this approach seemed easier to me) I assumed opening the PR against v0.1.x is correct as I couldn't find the `Filtered` type in master. I think it'd be sensible to note the fact that `reload::Handle::reload` doesn't work with `Filtered` in the docs somewhere, should I add that? ## Motivation Changing the filter of a `Filtered` at runtime is currently only possible by replacing it with a new `Filtered` via the `reload::Handle::reload` method. This currently doesn't work as the new `Filtered` won't receive a `FilterId` (see tokio-rs#1629). While it would be desirable to just make that work, it would only be possible via a breaking change (according to Eliza) so this seems like a reasonable (and easy) workaround for now. (I can't judge whether this method is only useful as a workaround for the bug or if it suits the public API independently) ## Solution Offer mutable access to the `Filtered::filter` field in the public API. This can be used via the `reload::Handle::modify` method to change the filter inside the existing `Filtered`. Fixes tokio-rs#1629

@TimoFreiberg

# 0.3.10 (Apr 1, 2022) This release adds several new features, including a `Filter` implementation and new builder API for `EnvFilter`, support for using a `Vec<L> where L: Layer` as a `Layer`, and a number of smaller API improvements to make working with dynamic and reloadable layers easier. ### Added - **registry**: Implement `Filter` for `EnvFilter`, allowing it to be used with per-layer filtering ([tokio-rs#1983]) - **registry**: `Filter::on_new_span`, `Filter::on_enter`, `Filter::on_exit`, `Filter::on_close` and `Filter::on_record` callbacks to allow `Filter`s to track span states internally ([tokio-rs#1973], [tokio-rs#2017], [tokio-rs#2031]) - **registry**: `Filtered::filter` and `Filtered::filter_mut` accessors ([tokio-rs#1959]) - **registry**: `Filtered::inner` and `Filtered::inner_mut` accessors to borrow the wrapped `Layer` ([tokio-rs#2034]) - **layer**: Implement `Layer` for `Vec<L: Layer>`, to allow composing together a dynamically sized list of `Layer`s ([tokio-rs#2027]) - **layer**: `Layer::boxed` method to make type-erasing `Layer`s easier ([tokio-rs#2026]) - **fmt**: `fmt::Layer::writer` and `fmt::Layer::writer_mut` accessors ([tokio-rs#2034]) - **fmt**: `fmt::Layer::set_ansi` method to allow changing the ANSI formatting configuration at runtime ([tokio-rs#2034]) - **env-filter**: `EnvFilter::builder` to configure a new `EnvFilter` prior to parsing it ([tokio-rs#2035]) - Several documentation fixes and improvements ([tokio-rs#1972], [tokio-rs#1971], [tokio-rs#2023], [tokio-rs#2023]) ### Fixed - **fmt**: `fmt::Layer`'s auto traits no longer depend on the `Subscriber` type parameter's auto traits ([tokio-rs#2025]) - **env-filter**: Fixed missing help text when the `ansi` feature is disabled ([tokio-rs#2029]) Thanks to new contributors @TimoFreiberg and @wagenet, as well as @CAD97 for contributing to this release! [tokio-rs#1983]: tokio-rs#1983 [tokio-rs#1973]: tokio-rs#1973 [tokio-rs#2017]: tokio-rs#2017 [tokio-rs#2031]: tokio-rs#2031 [tokio-rs#1959]: tokio-rs#1959 [tokio-rs#2034]: tokio-rs#2034 [tokio-rs#2027]: tokio-rs#2027 [tokio-rs#2026]: tokio-rs#2026 [tokio-rs#2035]: tokio-rs#2035 [tokio-rs#1972]: tokio-rs#1972 [tokio-rs#1971]: tokio-rs#1971 [tokio-rs#2023]: tokio-rs#2023 [tokio-rs#2025]: tokio-rs#2025 [tokio-rs#2029]: tokio-rs#2029

tfreiberg-fastly requested review from hawkw and a team as code owners February 24, 2022 13:04

tfreiberg-fastly changed the title ~~Add Filtered::filter_mut~~ subscriber: add Filtered::filter_mut Feb 24, 2022

hawkw requested changes Feb 24, 2022

View reviewed changes

tracing-subscriber/src/filter/layer_filters/mod.rs Outdated Show resolved Hide resolved

tracing-subscriber/src/filter/layer_filters/mod.rs Show resolved Hide resolved

tfreiberg-fastly force-pushed the add_filtered_filter_mut branch 3 times, most recently from 283e773 to 7573d2f Compare February 25, 2022 14:41

tfreiberg-fastly commented Feb 25, 2022

View reviewed changes

hawkw reviewed Feb 28, 2022

View reviewed changes

tfreiberg-fastly force-pushed the add_filtered_filter_mut branch from 7573d2f to ddae0e9 Compare March 1, 2022 16:24

hawkw approved these changes Mar 1, 2022

View reviewed changes

hawkw merged commit 4f714f0 into tokio-rs:v0.1.x Mar 1, 2022

hawkw mentioned this pull request Mar 1, 2022

chore: port filters to master #1796

Closed

tfreiberg-fastly deleted the add_filtered_filter_mut branch March 2, 2022 09:41

TimoFreiberg mentioned this pull request Mar 8, 2022

Add example for reloading a global filtering layer #1971

Merged

hawkw mentioned this pull request Apr 1, 2022

subscriber: prepare to release v0.3.10 #2041

Merged

davidbarsky mentioned this pull request Sep 26, 2023

chore: backport roughly a year's worth of changes #2728

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

subscriber: add Filtered::filter_mut #1959

subscriber: add Filtered::filter_mut #1959

tfreiberg-fastly commented Feb 24, 2022 •

edited

hawkw left a comment

hawkw commented Feb 24, 2022

tfreiberg-fastly Feb 25, 2022

hawkw Feb 25, 2022

tfreiberg-fastly Mar 1, 2022 •

edited

tfreiberg-fastly Feb 25, 2022

hawkw left a comment

hawkw Feb 25, 2022

hawkw Feb 28, 2022

hawkw left a comment

tfreiberg-fastly commented Mar 2, 2022

subscriber: add Filtered::filter_mut #1959

subscriber: add Filtered::filter_mut #1959

Conversation

tfreiberg-fastly commented Feb 24, 2022 • edited

Motivation

Solution

hawkw left a comment

Choose a reason for hiding this comment

hawkw commented Feb 24, 2022

tfreiberg-fastly Feb 25, 2022

Choose a reason for hiding this comment

hawkw Feb 25, 2022

Choose a reason for hiding this comment

tfreiberg-fastly Mar 1, 2022 • edited

Choose a reason for hiding this comment

tfreiberg-fastly Feb 25, 2022

Choose a reason for hiding this comment

hawkw left a comment

Choose a reason for hiding this comment

hawkw Feb 25, 2022

Choose a reason for hiding this comment

hawkw Feb 28, 2022

Choose a reason for hiding this comment

hawkw left a comment

Choose a reason for hiding this comment

tfreiberg-fastly commented Mar 2, 2022

tfreiberg-fastly commented Feb 24, 2022 •

edited

tfreiberg-fastly Mar 1, 2022 •

edited