Better documentation & tests for using `Level` constants for `#[instrument(level = X)]` #2350

jsgf · 2022-10-17T18:23:25Z

Motivation

The #[instrument(level = X)] parameter accepts Level::DEBUG (etc) constants, which seems like the most natural way to
specify it, and more consistent with the other event!/span! macros.

Solution

This PR:

adds tests for specifying level with Level constants
updates the documentation to use Level constants as the preferred/default usage

There are no functional changes to the macros themselves.

I think it's preferable to use the named constants rather than string literals for levels since it makes it easier to see what the options are and catch typos in a more normal way. Also document that the `level` parameter can be named constant, string literal or numeric constant.

davidbarsky · 2022-10-17T18:58:30Z

thanks for doing this, @jsgf! for the failing doc tests, can you add a hidden import to each of the changed doc tests?

hawkw

Thanks for the docs improvements! I noticed a typo and had a couple of very minor documentation suggestions, but other than that, this looks good once CI passes!

tracing-attributes/src/lib.rs

hawkw · 2022-10-17T19:07:30Z

tracing-attributes/src/lib.rs

 /// pub fn my_function() {
 ///     // ...
 /// }
 /// ```
+/// Levels can be specifide either with `Level` constants, literal strings
+/// (`"debug", etc) or numerically (1 - 5).


maybe worth indicating how numbers are mapped to Levels --- maybe with a table, or just mentioning that 5 corresponds to the TRACE level? we could link to the docs here: https://docs.rs/tracing-core/latest/tracing_core/struct.Level.html#comparing-levels

The doc references to `Level` don't resolve because `tracing-attribute` doesn't have a direct dependency on `tracing` - not sure how to resolve right now.

I hope there's a better way to deal with this.

jsgf · 2022-10-19T22:18:21Z

tracing-attributes/Cargo.toml

@@ -37,7 +37,6 @@ proc-macro = true
 proc-macro2 = "1.0.40"
 syn = { version = "1.0.98", default-features = false, features = ["full", "parsing", "printing", "visit", "visit-mut", "clone-impls", "extra-traits", "proc-macro"] }
 quote = "1.0.20"
-tracing-core = { path = "../tracing-core", version = "0.2"} # non-dev just for docs


~~Need to add this back to dev-dependencies.~~ No that wasn't it.

davidbarsky

thanks for these changes!

…2350) This branch adds documentation and tests noting that the `#[instrument]` macro accepts `tracing::Level` directly. Using `tracing::Level` directly allows for IDE autocomplete and earlier detection of typos. The documentation for tracing-attributes was also rewritten to remove the usage of the second-person perspective, making it more consistent with the rest of tracing's documentation. Co-authored-by: David Barsky <me@davidbarsky.com> ; Conflicts: ; tracing-attributes/Cargo.toml ; tracing-attributes/src/lib.rs

@nitnelave

# 0.1.24 (April 24th, 2023) This release of `tracing-attributes` adds support for passing an optional `level` to the `err` and `ret` arguments to `#[instrument]`, allowing the level of the generated return-value event to be overridden. For example, ```rust #[instrument(err(level = "info"))] fn my_great_function() -> Result<(), &'static str> { // ... } ``` will emit an `INFO`-level event if the function returns an `Err`. In addition, this release updates the [`syn`] dependency to v2.x.x. ### Added - `level` argument to `err` and `ret` to override the level of the generated return value event (#2335) - Improved compiler error message when `#[instrument]` is added to a `const fn` (#2418) ### Changed - Updated `syn` dependency to 2.0 (#2516) ### Fixed - Fix `clippy::unreachable` warnings in `#[instrument]`-generated code (#2356) - Removed unused "visit" feature flag from `syn` dependency (#2530) ### Documented - Documented default level for `err` (#2433) - Improved documentation for levels in `#[instrument]` (#2350) Thanks to @nitnelave, @jsgf, @Abhicodes-crypto, @LukeMathWalker, @andrewpollack, @quad, @klensy, @davidpdrsn, and @dbidwell94 for contributign to this release! [`syn`]: https://crates.io/crates/syn

@nitnelave

# 0.1.24 (April 24th, 2023) This release of `tracing-attributes` adds support for passing an optional `level` to the `err` and `ret` arguments to `#[instrument]`, allowing the level of the generated return-value event to be overridden. For example, ```rust #[instrument(err(level = "info"))] fn my_great_function() -> Result<(), &'static str> { // ... } ``` will emit an `INFO`-level event if the function returns an `Err`. In addition, this release updates the [`syn`] dependency to v2.x.x. ### Added - `level` argument to `err` and `ret` to override the level of the generated return value event (#2335) - Improved compiler error message when `#[instrument]` is added to a `const fn` (#2418) ### Changed - Updated `syn` dependency to 2.0 (#2516) ### Fixed - Fix `clippy::unreachable` warnings in `#[instrument]`-generated code (#2356) - Removed unused "visit" feature flag from `syn` dependency (#2530) ### Documented - Documented default level for `err` (#2433) - Improved documentation for levels in `#[instrument]` (#2350) Thanks to @nitnelave, @jsgf, @Abhicodes-crypto, @LukeMathWalker, @andrewpollack, @quad, @klensy, @davidpdrsn, and @dbidwell94 for contributign to this release! [`syn`]: https://crates.io/crates/syn

@nitnelave

# 0.1.38 (April 25th, 2023) This `tracing` release changes the `Drop` implementation for `Instrumented` `Future`s so that the attached `Span` is entered when dropping the `Future`. This means that events emitted by the `Future`'s `Drop` implementation will now be recorded within its `Span`. It also adds `#[inline]` hints to methods called in the `event!` macro's expansion, for an improvement in both binary size and performance. Additionally, this release updates the `tracing-attributes` dependency to [v0.1.24][attrs-0.1.24], which updates the [`syn`] dependency to v2.x.x. `tracing-attributes` v0.1.24 also includes improvements to the `#[instrument]` macro; see [the `tracing-attributes` 0.1.24 release notes][attrs-0.1.24] for details. ### Added - `Instrumented` futures will now enter the attached `Span` in their `Drop` implementation, allowing events emitted when dropping the future to occur within the span (#2562) - `#[inline]` attributes for methods called by the `event!` macros, making generated code smaller (#2555) - **attributes**: `level` argument to `#[instrument(err)]` and `#[instrument(ret)]` to override the level of the generated return value event (#2335) - **attributes**: Improved compiler error message when `#[instrument]` is added to a `const fn` (#2418) ### Changed - `tracing-attributes`: updated to [0.1.24][attrs-0.1.24] - Removed unneeded `cfg-if` dependency (#2553) - **attributes**: Updated [`syn`] dependency to 2.0 (#2516) ### Fixed - **attributes**: Fix `clippy::unreachable` warnings in `#[instrument]`-generated code (#2356) - **attributes**: Removed unused "visit" feature flag from `syn` dependency (#2530) ### Documented - **attributes**: Documented default level for `#[instrument(err)]` (#2433) - **attributes**: Improved documentation for levels in `#[instrument]` (#2350) Thanks to @nitnelave, @jsgf, @Abhicodes-crypto, @LukeMathWalker, @andrewpollack, @quad, @klensy, @davidpdrsn, @dbidwell94, @ldm0, @NobodyXu, @ilsv, and @daxpedda for contributing to this release! [`syn`]: https://crates.io/crates/syn [attrs-0.1.24]: https://github.com/tokio-rs/tracing/releases/tag/tracing-attributes-0.1.24

@nitnelave

# 0.1.38 (April 25th, 2023) This `tracing` release changes the `Drop` implementation for `Instrumented` `Future`s so that the attached `Span` is entered when dropping the `Future`. This means that events emitted by the `Future`'s `Drop` implementation will now be recorded within its `Span`. It also adds `#[inline]` hints to methods called in the `event!` macro's expansion, for an improvement in both binary size and performance. Additionally, this release updates the `tracing-attributes` dependency to [v0.1.24][attrs-0.1.24], which updates the [`syn`] dependency to v2.x.x. `tracing-attributes` v0.1.24 also includes improvements to the `#[instrument]` macro; see [the `tracing-attributes` 0.1.24 release notes][attrs-0.1.24] for details. ### Added - `Instrumented` futures will now enter the attached `Span` in their `Drop` implementation, allowing events emitted when dropping the future to occur within the span (#2562) - `#[inline]` attributes for methods called by the `event!` macros, making generated code smaller (#2555) - **attributes**: `level` argument to `#[instrument(err)]` and `#[instrument(ret)]` to override the level of the generated return value event (#2335) - **attributes**: Improved compiler error message when `#[instrument]` is added to a `const fn` (#2418) ### Changed - `tracing-attributes`: updated to [0.1.24][attrs-0.1.24] - Removed unneeded `cfg-if` dependency (#2553) - **attributes**: Updated [`syn`] dependency to 2.0 (#2516) ### Fixed - **attributes**: Fix `clippy::unreachable` warnings in `#[instrument]`-generated code (#2356) - **attributes**: Removed unused "visit" feature flag from `syn` dependency (#2530) ### Documented - **attributes**: Documented default level for `#[instrument(err)]` (#2433) - **attributes**: Improved documentation for levels in `#[instrument]` (#2350) Thanks to @nitnelave, @jsgf, @Abhicodes-crypto, @LukeMathWalker, @andrewpollack, @quad, @klensy, @davidpdrsn, @dbidwell94, @ldm0, @NobodyXu, @ilsv, and @daxpedda for contributing to this release! [`syn`]: https://crates.io/crates/syn [attrs-0.1.24]: https://github.com/tokio-rs/tracing/releases/tag/tracing-attributes-0.1.24

…okio-rs#2350) This branch adds documentation and tests noting that the `#[instrument]` macro accepts `tracing::Level` directly. Using `tracing::Level` directly allows for IDE autocomplete and earlier detection of typos. The documentation for tracing-attributes was also rewritten to remove the usage of the second-person perspective, making it more consistent with the rest of tracing's documentation. Co-authored-by: David Barsky <me@davidbarsky.com> ; Conflicts: ; tracing-attributes/Cargo.toml ; tracing-attributes/src/lib.rs

@nitnelave

# 0.1.24 (April 24th, 2023) This release of `tracing-attributes` adds support for passing an optional `level` to the `err` and `ret` arguments to `#[instrument]`, allowing the level of the generated return-value event to be overridden. For example, ```rust #[instrument(err(level = "info"))] fn my_great_function() -> Result<(), &'static str> { // ... } ``` will emit an `INFO`-level event if the function returns an `Err`. In addition, this release updates the [`syn`] dependency to v2.x.x. ### Added - `level` argument to `err` and `ret` to override the level of the generated return value event (tokio-rs#2335) - Improved compiler error message when `#[instrument]` is added to a `const fn` (tokio-rs#2418) ### Changed - Updated `syn` dependency to 2.0 (tokio-rs#2516) ### Fixed - Fix `clippy::unreachable` warnings in `#[instrument]`-generated code (tokio-rs#2356) - Removed unused "visit" feature flag from `syn` dependency (tokio-rs#2530) ### Documented - Documented default level for `err` (tokio-rs#2433) - Improved documentation for levels in `#[instrument]` (tokio-rs#2350) Thanks to @nitnelave, @jsgf, @Abhicodes-crypto, @LukeMathWalker, @andrewpollack, @quad, @klensy, @davidpdrsn, and @dbidwell94 for contributign to this release! [`syn`]: https://crates.io/crates/syn

@nitnelave

# 0.1.38 (April 25th, 2023) This `tracing` release changes the `Drop` implementation for `Instrumented` `Future`s so that the attached `Span` is entered when dropping the `Future`. This means that events emitted by the `Future`'s `Drop` implementation will now be recorded within its `Span`. It also adds `#[inline]` hints to methods called in the `event!` macro's expansion, for an improvement in both binary size and performance. Additionally, this release updates the `tracing-attributes` dependency to [v0.1.24][attrs-0.1.24], which updates the [`syn`] dependency to v2.x.x. `tracing-attributes` v0.1.24 also includes improvements to the `#[instrument]` macro; see [the `tracing-attributes` 0.1.24 release notes][attrs-0.1.24] for details. ### Added - `Instrumented` futures will now enter the attached `Span` in their `Drop` implementation, allowing events emitted when dropping the future to occur within the span (tokio-rs#2562) - `#[inline]` attributes for methods called by the `event!` macros, making generated code smaller (tokio-rs#2555) - **attributes**: `level` argument to `#[instrument(err)]` and `#[instrument(ret)]` to override the level of the generated return value event (tokio-rs#2335) - **attributes**: Improved compiler error message when `#[instrument]` is added to a `const fn` (tokio-rs#2418) ### Changed - `tracing-attributes`: updated to [0.1.24][attrs-0.1.24] - Removed unneeded `cfg-if` dependency (tokio-rs#2553) - **attributes**: Updated [`syn`] dependency to 2.0 (tokio-rs#2516) ### Fixed - **attributes**: Fix `clippy::unreachable` warnings in `#[instrument]`-generated code (tokio-rs#2356) - **attributes**: Removed unused "visit" feature flag from `syn` dependency (tokio-rs#2530) ### Documented - **attributes**: Documented default level for `#[instrument(err)]` (tokio-rs#2433) - **attributes**: Improved documentation for levels in `#[instrument]` (tokio-rs#2350) Thanks to @nitnelave, @jsgf, @Abhicodes-crypto, @LukeMathWalker, @andrewpollack, @quad, @klensy, @davidpdrsn, @dbidwell94, @ldm0, @NobodyXu, @ilsv, and @daxpedda for contributing to this release! [`syn`]: https://crates.io/crates/syn [attrs-0.1.24]: https://github.com/tokio-rs/tracing/releases/tag/tracing-attributes-0.1.24

jsgf added 2 commits October 17, 2022 11:04

Add test for using Level::* constants in #[instrument]

1604f89

jsgf requested review from hawkw, davidbarsky and a team as code owners October 17, 2022 18:23

hawkw reviewed Oct 17, 2022

View reviewed changes

jsgf added 2 commits October 17, 2022 14:53

Fix review issues

592fd57

The doc references to `Level` don't resolve because `tracing-attribute` doesn't have a direct dependency on `tracing` - not sure how to resolve right now.

Make tracing-attribute depend on tracing-core just for doc references

267455b

I hope there's a better way to deal with this.

jsgf requested review from yaahc and carllerche as code owners October 18, 2022 05:18

jsgf force-pushed the enum-levels branch 2 times, most recently from 803bfed to e7c9b26 Compare October 18, 2022 05:26

Fix nightly warnings

cc9cb7f

jsgf force-pushed the enum-levels branch from e7c9b26 to cc9cb7f Compare October 18, 2022 05:29

fixup docs

4f9585b

jsgf commented Oct 19, 2022

View reviewed changes

doc fix fix

5bbab29

jsgf force-pushed the enum-levels branch from 1770077 to 5bbab29 Compare October 26, 2022 19:36

davidbarsky approved these changes Oct 27, 2022

View reviewed changes

davidbarsky merged commit 3258a2b into tokio-rs:master Oct 27, 2022

jsgf deleted the enum-levels branch October 28, 2022 07:32

hawkw mentioned this pull request Apr 21, 2023

backport a gigantic pile of stuff #2570

Merged

hawkw mentioned this pull request Apr 24, 2023

attributes: prepare to release v0.1.24 #2574

Merged

hawkw mentioned this pull request Apr 25, 2023

tracing: prepare to release v0.1.38 #2575

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

Better documentation & tests for using `Level` constants for `#[instrument(level = X)]` #2350

Better documentation & tests for using `Level` constants for `#[instrument(level = X)]` #2350

jsgf commented Oct 17, 2022

davidbarsky commented Oct 17, 2022

hawkw left a comment

hawkw Oct 17, 2022

jsgf Oct 19, 2022 •

edited

Loading

davidbarsky left a comment

Better documentation & tests for using Level constants for #[instrument(level = X)] #2350

Better documentation & tests for using Level constants for #[instrument(level = X)] #2350

Conversation

jsgf commented Oct 17, 2022

Motivation

Solution

davidbarsky commented Oct 17, 2022

hawkw left a comment

Choose a reason for hiding this comment

hawkw Oct 17, 2022

Choose a reason for hiding this comment

jsgf Oct 19, 2022 • edited Loading

Choose a reason for hiding this comment

davidbarsky left a comment

Choose a reason for hiding this comment

Better documentation & tests for using `Level` constants for `#[instrument(level = X)]` #2350

Better documentation & tests for using `Level` constants for `#[instrument(level = X)]` #2350

jsgf Oct 19, 2022 •

edited

Loading