Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

tracing-subscriber: correct fmt::init() documentation #2224

Merged
merged 3 commits into from
Jul 28, 2022
Merged

tracing-subscriber: correct fmt::init() documentation #2224

merged 3 commits into from
Jul 28, 2022

Conversation

cgbur
Copy link
Contributor

@cgbur cgbur commented Jul 16, 2022

correct fmt::init() documentation

Previously the documentation for fmt::init() was misleading. It stated that it was shorthand for fmt().init(). This lead to confusion as users would expect the same behavior from both. However fmt::init() would, whether you used the env-filter feature or not, rely on RUST_LOG to set the tracing level. fmt().init() does not do this and it must be set with a specific configuration via with_env_filter.

The documentation has been updated to no longer state that it is 1:1 shorthand for the other. The documentation now specifically points out that you must be using the env-filter feature and gives a correct example to mimic the fmt::init() behavior using fmt().init().

fixes: #2217 #1329

@cgbur
tracing-subscriber: correct fmt::init() documentation
e0f4bef 
Previously the documentation for `fmt::init()` was misleading. It stated
that it was shorthand for `fmt().init()`. This lead to confusion as
users would expect the same behavior from both. However `fmt::init()`
would, whether you used the env-filter feature or not, rely on RUST_LOG
to set the tracing level. `fmt().init()` does not do this and it must be
set with a specific configuration via `with_env_filter`.

The documentation has been updated to no longer state that it is 1:1
shorthand for the other. The documentation now specifically points out
that you must be using the `env-filter` feature and gives a correct
example to mimic the `fmt::init()` behavior using `fmt().init()`.

fixes: tokio-rs#2217 tokio-rs#1329
@cgbur cgbur requested review from hawkw and a team as code owners July 16, 2022 18:15
hawkw
hawkw approved these changes Jul 28, 2022
View reviewed changes
Copy link
Member

@hawkw hawkw left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

one minor suggestion here, but other than that, this looks good. Thank you!

tracing-subscriber/src/fmt/mod.rs Show resolved Hide resolved
tracing-subscriber/src/fmt/mod.rs Show resolved Hide resolved
@hawkw hawkw enabled auto-merge (squash) July 28, 2022 18:42
@hawkw hawkw merged commit b6762da into tokio-rs:v0.1.x Jul 28, 2022
hawkw added a commit that referenced this pull request Oct 6, 2022
@hawkw
subscriber: prepare to release v0.3.16
a92c013 
# 0.3.16 (October 6, 2022)

This release of `tracing-subscriber` fixes a regression introduced in
[v0.3.15][subscriber-0.3.15] where `Option::None`'s `Layer`
implementation would set the max level hint to `OFF`. In addition, it
adds several new APIs, including the `Filter::event_enabled` method for
filtering events based on fields values, and the ability to log internal
errors that occur when writing a log line.

This release also replaces the dependency on the unmaintained
[`ansi-term`] crate with the [`nu-ansi-term`] crate, resolving an
*informational* security advisory ([RUSTSEC-2021-0139] for
[`ansi-term`]'s maintainance status. This increases the minimum
supported Rust version (MSRV) to Rust 1.50+, although the crate should
still compile for the previous MSRV of Rust 1.49+ when the `ansi`
feature is not enabled.

### Fixed

- **layer**: `Option::None`'s `Layer` impl always setting the
  `max_level_hint` to `LevelFilter::OFF` (#2321)
- Compilation with `-Z minimal versions` (#2246)
- **env-filter**: Clarify that disabled level warnings are emitted by
  `tracing-subscriber` (#2285)

### Added

- **fmt**: Log internal errors to `stderr` if writing a log line fails
  (#2102)
- **fmt**: `FmtLayer::log_internal_errors` and
  `FmtSubscriber::log_internal_errors` methods for configuring whether
  internal writer errors are printed to `stderr` (#2102)
- **fmt**: `#[must_use]` attributes on builders to warn if a
  `Subscriber` is configured but not set as the default subscriber
  (#2239)
- **filter**: `Filter::event_enabled` method for filtering an event
  based on its fields (#2245, #2251)
- **filter**: `Targets::default_level` accessor (#2242)

### Changed

- **ansi**: Replaced dependency on unmaintained `ansi-term` crate with
  `nu-ansi-term` ((#2287, fixes informational advisory
  [RUSTSEC-2021-0139])
- `tracing-core`: updated to [0.1.30][core-0.1.30]
- Minimum Supported Rust Version (MSRV) increased to Rust 1.50+ (when
  the `ansi`) feature flag is enabled (#2287)

### Documented

- **fmt**: Correct inaccuracies in `fmt::init` documentation (#2224)
- **filter**: Fix incorrect doc link in `filter::Not` combinator
  (#2249)

Thanks to new contributors @cgbur, @DesmondWillowbrook, @RalfJung, and
@poliorcetics, as well as returning contributors @CAD97, @connec,
@jswrenn, @guswynn, and @bryangarza, for contributing to this release!

[nu-ansi-term]: https://github.com/nushell/nu-ansi-term
[ansi_term]: https://github.com/ogham/rust-ansi-term
[RUSTSEC-2021-0139]: https://rustsec.org/advisories/RUSTSEC-2021-0139.html
[core-0.1.30]: https://github.com/tokio-rs/tracing/releases/tag/tracing-core-0.1.30
[subscriber-0.3.15]: https://github.com/tokio-rs/tracing/releases/tag/tracing-subscriber-0.3.15
@hawkw hawkw mentioned this pull request Oct 6, 2022
Merged
hawkw added a commit that referenced this pull request Oct 6, 2022
@hawkw
subscriber: prepare to release v0.3.16
d1f401a 
# 0.3.16 (October 6, 2022)

This release of `tracing-subscriber` fixes a regression introduced in
[v0.3.15][subscriber-0.3.15] where `Option::None`'s `Layer`
implementation would set the max level hint to `OFF`. In addition, it
adds several new APIs, including the `Filter::event_enabled` method for
filtering events based on fields values, and the ability to log internal
errors that occur when writing a log line.

This release also replaces the dependency on the unmaintained
[`ansi-term`] crate with the [`nu-ansi-term`] crate, resolving an
*informational* security advisory ([RUSTSEC-2021-0139] for
[`ansi-term`]'s maintainance status. This increases the minimum
supported Rust version (MSRV) to Rust 1.50+, although the crate should
still compile for the previous MSRV of Rust 1.49+ when the `ansi`
feature is not enabled.

### Fixed

- **layer**: `Option::None`'s `Layer` impl always setting the
  `max_level_hint` to `LevelFilter::OFF` (#2321)
- Compilation with `-Z minimal versions` (#2246)
- **env-filter**: Clarify that disabled level warnings are emitted by
  `tracing-subscriber` (#2285)

### Added

- **fmt**: Log internal errors to `stderr` if writing a log line fails
  (#2102)
- **fmt**: `FmtLayer::log_internal_errors` and
  `FmtSubscriber::log_internal_errors` methods for configuring whether
  internal writer errors are printed to `stderr` (#2102)
- **fmt**: `#[must_use]` attributes on builders to warn if a
  `Subscriber` is configured but not set as the default subscriber
  (#2239)
- **filter**: `Filter::event_enabled` method for filtering an event
  based on its fields (#2245, #2251)
- **filter**: `Targets::default_level` accessor (#2242)

### Changed

- **ansi**: Replaced dependency on unmaintained `ansi-term` crate with
  `nu-ansi-term` ((#2287, fixes informational advisory
  [RUSTSEC-2021-0139])
- `tracing-core`: updated to [0.1.30][core-0.1.30]
- Minimum Supported Rust Version (MSRV) increased to Rust 1.50+ (when
  the `ansi`) feature flag is enabled (#2287)

### Documented

- **fmt**: Correct inaccuracies in `fmt::init` documentation (#2224)
- **filter**: Fix incorrect doc link in `filter::Not` combinator
  (#2249)

Thanks to new contributors @cgbur, @DesmondWillowbrook, @RalfJung, and
@poliorcetics, as well as returning contributors @CAD97, @connec,
@jswrenn, @guswynn, and @bryangarza, for contributing to this release!

[nu-ansi-term]: https://github.com/nushell/nu-ansi-term
[ansi_term]: https://github.com/ogham/rust-ansi-term
[RUSTSEC-2021-0139]: https://rustsec.org/advisories/RUSTSEC-2021-0139.html
[core-0.1.30]: https://github.com/tokio-rs/tracing/releases/tag/tracing-core-0.1.30
[subscriber-0.3.15]: https://github.com/tokio-rs/tracing/releases/tag/tracing-subscriber-0.3.15
hawkw added a commit that referenced this pull request Oct 6, 2022
@hawkw
subscriber: prepare to release v0.3.16 (#2342)
b28c935 
# 0.3.16 (October 6, 2022)

This release of `tracing-subscriber` fixes a regression introduced in
[v0.3.15][subscriber-0.3.15] where `Option::None`'s `Layer`
implementation would set the max level hint to `OFF`. In addition, it
adds several new APIs, including the `Filter::event_enabled` method for
filtering events based on fields values, and the ability to log internal
errors that occur when writing a log line.

This release also replaces the dependency on the unmaintained
[`ansi-term`] crate with the [`nu-ansi-term`] crate, resolving an
*informational* security advisory ([RUSTSEC-2021-0139] for
[`ansi-term`]'s maintainance status. This increases the minimum
supported Rust version (MSRV) to Rust 1.50+, although the crate should
still compile for the previous MSRV of Rust 1.49+ when the `ansi`
feature is not enabled.

### Fixed

- **layer**: `Option::None`'s `Layer` impl always setting the
  `max_level_hint` to `LevelFilter::OFF` (#2321)
- Compilation with `-Z minimal versions` (#2246)
- **env-filter**: Clarify that disabled level warnings are emitted by
  `tracing-subscriber` (#2285)

### Added

- **fmt**: Log internal errors to `stderr` if writing a log line fails
  (#2102)
- **fmt**: `FmtLayer::log_internal_errors` and
  `FmtSubscriber::log_internal_errors` methods for configuring whether
  internal writer errors are printed to `stderr` (#2102)
- **fmt**: `#[must_use]` attributes on builders to warn if a
  `Subscriber` is configured but not set as the default subscriber
  (#2239)
- **filter**: `Filter::event_enabled` method for filtering an event
  based on its fields (#2245, #2251)
- **filter**: `Targets::default_level` accessor (#2242)

### Changed

- **ansi**: Replaced dependency on unmaintained `ansi-term` crate with
  `nu-ansi-term` ((#2287, fixes informational advisory
  [RUSTSEC-2021-0139])
- `tracing-core`: updated to [0.1.30][core-0.1.30]
- Minimum Supported Rust Version (MSRV) increased to Rust 1.50+ (when
  the `ansi`) feature flag is enabled (#2287)

### Documented

- **fmt**: Correct inaccuracies in `fmt::init` documentation (#2224)
- **filter**: Fix incorrect doc link in `filter::Not` combinator
  (#2249)

Thanks to new contributors @cgbur, @DesmondWillowbrook, @RalfJung, and
@poliorcetics, as well as returning contributors @CAD97, @connec,
@jswrenn, @guswynn, and @bryangarza, for contributing to this release!

[nu-ansi-term]: https://github.com/nushell/nu-ansi-term
[ansi_term]: https://github.com/ogham/rust-ansi-term
[RUSTSEC-2021-0139]: https://rustsec.org/advisories/RUSTSEC-2021-0139.html
[core-0.1.30]: https://github.com/tokio-rs/tracing/releases/tag/tracing-core-0.1.30
[subscriber-0.3.15]: https://github.com/tokio-rs/tracing/releases/tag/tracing-subscriber-0.3.15
@davidbarsky davidbarsky mentioned this pull request Sep 26, 2023
Merged
kaffarell pushed a commit to kaffarell/tracing that referenced this pull request May 22, 2024
@cgbur @hawkw @kaffarell
subscriber: correct fmt::init() documentation (tokio-rs#2224)
41a3524 
## Motivation

Previously the documentation for `fmt::init()` was misleading. It stated
that it was shorthand for `fmt().init()`. This lead to confusion as
users would expect the same behavior from both. However `fmt::init()`
would, whether you used the env-filter feature or not, rely on RUST_LOG
to set the tracing level. `fmt().init()` does not do this and it must be
set with a specific configuration via `with_env_filter`.

## Solution

The documentation has been updated to no longer state that it is 1:1
shorthand for the other. The documentation now specifically points out
that you must be using the `env-filter` feature and gives a correct
example to mimic the `fmt::init()` behavior using `fmt().init()`.

Fixes tokio-rs#2217
Fixes tokio-rs#1329

Co-authored-by: Eliza Weisman <[email protected]>
kaffarell pushed a commit to kaffarell/tracing that referenced this pull request May 22, 2024
@hawkw @kaffarell
subscriber: prepare to release v0.3.16 (tokio-rs#2342)
3149fb1 
# 0.3.16 (October 6, 2022)

This release of `tracing-subscriber` fixes a regression introduced in
[v0.3.15][subscriber-0.3.15] where `Option::None`'s `Layer`
implementation would set the max level hint to `OFF`. In addition, it
adds several new APIs, including the `Filter::event_enabled` method for
filtering events based on fields values, and the ability to log internal
errors that occur when writing a log line.

This release also replaces the dependency on the unmaintained
[`ansi-term`] crate with the [`nu-ansi-term`] crate, resolving an
*informational* security advisory ([RUSTSEC-2021-0139] for
[`ansi-term`]'s maintainance status. This increases the minimum
supported Rust version (MSRV) to Rust 1.50+, although the crate should
still compile for the previous MSRV of Rust 1.49+ when the `ansi`
feature is not enabled.

### Fixed

- **layer**: `Option::None`'s `Layer` impl always setting the
  `max_level_hint` to `LevelFilter::OFF` (tokio-rs#2321)
- Compilation with `-Z minimal versions` (tokio-rs#2246)
- **env-filter**: Clarify that disabled level warnings are emitted by
  `tracing-subscriber` (tokio-rs#2285)

### Added

- **fmt**: Log internal errors to `stderr` if writing a log line fails
  (tokio-rs#2102)
- **fmt**: `FmtLayer::log_internal_errors` and
  `FmtSubscriber::log_internal_errors` methods for configuring whether
  internal writer errors are printed to `stderr` (tokio-rs#2102)
- **fmt**: `#[must_use]` attributes on builders to warn if a
  `Subscriber` is configured but not set as the default subscriber
  (tokio-rs#2239)
- **filter**: `Filter::event_enabled` method for filtering an event
  based on its fields (tokio-rs#2245, tokio-rs#2251)
- **filter**: `Targets::default_level` accessor (tokio-rs#2242)

### Changed

- **ansi**: Replaced dependency on unmaintained `ansi-term` crate with
  `nu-ansi-term` ((tokio-rs#2287, fixes informational advisory
  [RUSTSEC-2021-0139])
- `tracing-core`: updated to [0.1.30][core-0.1.30]
- Minimum Supported Rust Version (MSRV) increased to Rust 1.50+ (when
  the `ansi`) feature flag is enabled (tokio-rs#2287)

### Documented

- **fmt**: Correct inaccuracies in `fmt::init` documentation (tokio-rs#2224)
- **filter**: Fix incorrect doc link in `filter::Not` combinator
  (tokio-rs#2249)

Thanks to new contributors @cgbur, @DesmondWillowbrook, @RalfJung, and
@poliorcetics, as well as returning contributors @CAD97, @connec,
@jswrenn, @guswynn, and @bryangarza, for contributing to this release!

[nu-ansi-term]: https://github.com/nushell/nu-ansi-term
[ansi_term]: https://github.com/ogham/rust-ansi-term
[RUSTSEC-2021-0139]: https://rustsec.org/advisories/RUSTSEC-2021-0139.html
[core-0.1.30]: https://github.com/tokio-rs/tracing/releases/tag/tracing-core-0.1.30
[subscriber-0.3.15]: https://github.com/tokio-rs/tracing/releases/tag/tracing-subscriber-0.3.15
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@hawkw hawkw hawkw approved these changes

Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
2 participants
@cgbur @hawkw