From 1604f893958a6357f76c35feab379b9701af0f0e Mon Sep 17 00:00:00 2001 From: Jeremy Fitzhardinge Date: Mon, 17 Oct 2022 11:04:47 -0700 Subject: [PATCH 1/7] Add test for using Level::* constants in #[instrument] --- tracing-attributes/tests/levels.rs | 46 ++++++++++++++++++++++++++++++ 1 file changed, 46 insertions(+) diff --git a/tracing-attributes/tests/levels.rs b/tracing-attributes/tests/levels.rs index 2b34319667..c0db05d8aa 100644 --- a/tracing-attributes/tests/levels.rs +++ b/tracing-attributes/tests/levels.rs @@ -94,3 +94,49 @@ fn numeric_levels() { handle.assert_finished(); } + +#[test] +fn enum_levels() { + #[instrument(level = Level::TRACE)] + fn trace() {} + + #[instrument(level = Level::DEBUG)] + fn debug() {} + + #[instrument(level = tracing::Level::INFO)] + fn info() {} + + #[instrument(level = Level::WARN)] + fn warn() {} + + #[instrument(level = Level::ERROR)] + fn error() {} + let (collector, handle) = collector::mock() + .new_span(span::mock().named("trace").at_level(Level::TRACE)) + .enter(span::mock().named("trace").at_level(Level::TRACE)) + .exit(span::mock().named("trace").at_level(Level::TRACE)) + .new_span(span::mock().named("debug").at_level(Level::DEBUG)) + .enter(span::mock().named("debug").at_level(Level::DEBUG)) + .exit(span::mock().named("debug").at_level(Level::DEBUG)) + .new_span(span::mock().named("info").at_level(Level::INFO)) + .enter(span::mock().named("info").at_level(Level::INFO)) + .exit(span::mock().named("info").at_level(Level::INFO)) + .new_span(span::mock().named("warn").at_level(Level::WARN)) + .enter(span::mock().named("warn").at_level(Level::WARN)) + .exit(span::mock().named("warn").at_level(Level::WARN)) + .new_span(span::mock().named("error").at_level(Level::ERROR)) + .enter(span::mock().named("error").at_level(Level::ERROR)) + .exit(span::mock().named("error").at_level(Level::ERROR)) + .done() + .run_with_handle(); + + with_default(collector, || { + trace(); + debug(); + info(); + warn(); + error(); + }); + + handle.assert_finished(); +} From 8e0def488c3c3e4c095c93b69d85f9d3c0457b55 Mon Sep 17 00:00:00 2001 From: Jeremy Fitzhardinge Date: Mon, 17 Oct 2022 11:14:59 -0700 Subject: [PATCH 2/7] Change examples to use Level constants 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. --- tracing-attributes/src/lib.rs | 9 ++++++--- tracing-attributes/tests/instrument.rs | 2 +- 2 files changed, 7 insertions(+), 4 deletions(-) diff --git a/tracing-attributes/src/lib.rs b/tracing-attributes/src/lib.rs index 269e32522c..7fb514e4f9 100644 --- a/tracing-attributes/src/lib.rs +++ b/tracing-attributes/src/lib.rs @@ -132,11 +132,14 @@ mod expand; /// Setting the level for the generated span: /// ``` /// # use tracing_attributes::instrument; -/// #[instrument(level = "debug")] +/// #[instrument(level = Level::DEBUG)] /// pub fn my_function() { /// // ... /// } /// ``` +/// Levels can be specifide either with `Level` constants, literal strings +/// (`"debug", etc) or numerically (1 - 5). +/// /// Overriding the generated span's name: /// ``` /// # use tracing_attributes::instrument; @@ -235,7 +238,7 @@ mod expand; /// /// ``` /// # use tracing_attributes::instrument; -/// #[instrument(ret(level = "warn"))] +/// #[instrument(ret(level = Level::WARN))] /// fn my_function() -> i32 { /// 42 /// } @@ -271,7 +274,7 @@ mod expand; /// /// ``` /// # use tracing_attributes::instrument; -/// #[instrument(err(level = "info"))] +/// #[instrument(err(level = Level::INFO))] /// fn my_function(arg: usize) -> Result<(), std::io::Error> { /// Ok(()) /// } diff --git a/tracing-attributes/tests/instrument.rs b/tracing-attributes/tests/instrument.rs index 15b258b2ef..f91a1ce63a 100644 --- a/tracing-attributes/tests/instrument.rs +++ b/tracing-attributes/tests/instrument.rs @@ -17,7 +17,7 @@ fn override_everything() { #[instrument(target = "my_target", level = "debug")] fn my_fn() {} - #[instrument(level = "debug", target = "my_target")] + #[instrument(level = Level::DEBUG, target = "my_target")] fn my_other_fn() {} let span = span::mock() From 592fd5780a5afcbe4b352e09579532fc61521abf Mon Sep 17 00:00:00 2001 From: Jeremy Fitzhardinge Date: Mon, 17 Oct 2022 14:52:57 -0700 Subject: [PATCH 3/7] Fix review issues 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. --- tracing-attributes/src/lib.rs | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/tracing-attributes/src/lib.rs b/tracing-attributes/src/lib.rs index 7fb514e4f9..28de099f3d 100644 --- a/tracing-attributes/src/lib.rs +++ b/tracing-attributes/src/lib.rs @@ -132,13 +132,14 @@ mod expand; /// Setting the level for the generated span: /// ``` /// # use tracing_attributes::instrument; +/// # use tracing::Level; /// #[instrument(level = Level::DEBUG)] /// pub fn my_function() { /// // ... /// } /// ``` -/// Levels can be specifide either with `Level` constants, literal strings -/// (`"debug", etc) or numerically (1 - 5). +/// Levels can be specified either with [`Level`] constants, literal strings +/// (`"debug", etc) or numerically (1 - 5, corresponding to [`Level::TRACE`] - [`Level::ERROR`]). /// /// Overriding the generated span's name: /// ``` @@ -238,6 +239,7 @@ mod expand; /// /// ``` /// # use tracing_attributes::instrument; +/// # use tracing::Level; /// #[instrument(ret(level = Level::WARN))] /// fn my_function() -> i32 { /// 42 @@ -274,6 +276,7 @@ mod expand; /// /// ``` /// # use tracing_attributes::instrument; +/// # use tracing::Level; /// #[instrument(err(level = Level::INFO))] /// fn my_function(arg: usize) -> Result<(), std::io::Error> { /// Ok(()) @@ -372,6 +375,7 @@ mod expand; /// [`follows_from`]: https://docs.rs/tracing/latest/tracing/struct.Span.html#method.follows_from /// [`tracing`]: https://github.com/tokio-rs/tracing /// [`fmt::Debug`]: std::fmt::Debug +/// [`Level`]: tracing::Level #[proc_macro_attribute] pub fn instrument( args: proc_macro::TokenStream, From 267455b97592b237e717ca53f856d4d1cbd08082 Mon Sep 17 00:00:00 2001 From: Jeremy Fitzhardinge Date: Mon, 17 Oct 2022 15:03:40 -0700 Subject: [PATCH 4/7] Make tracing-attribute depend on tracing-core just for doc references I hope there's a better way to deal with this. --- tracing-attributes/Cargo.toml | 2 +- tracing-attributes/src/lib.rs | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/tracing-attributes/Cargo.toml b/tracing-attributes/Cargo.toml index 16d0e903e9..fee4f95366 100644 --- a/tracing-attributes/Cargo.toml +++ b/tracing-attributes/Cargo.toml @@ -37,12 +37,12 @@ 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 [dev-dependencies] tracing = { path = "../tracing", version = "0.2" } tracing-mock = { path = "../tracing-mock", features = ["tokio-test"] } tokio-test = "0.4.2" -tracing-core = { path = "../tracing-core", version = "0.2"} tracing-subscriber = { path = "../tracing-subscriber", version = "0.3", features = ["env-filter"] } async-trait = "0.1.56" trybuild = "1.0.64" diff --git a/tracing-attributes/src/lib.rs b/tracing-attributes/src/lib.rs index 28de099f3d..13adc2ff75 100644 --- a/tracing-attributes/src/lib.rs +++ b/tracing-attributes/src/lib.rs @@ -375,7 +375,7 @@ mod expand; /// [`follows_from`]: https://docs.rs/tracing/latest/tracing/struct.Span.html#method.follows_from /// [`tracing`]: https://github.com/tokio-rs/tracing /// [`fmt::Debug`]: std::fmt::Debug -/// [`Level`]: tracing::Level +/// [`Level`]: tracing_core::Level #[proc_macro_attribute] pub fn instrument( args: proc_macro::TokenStream, From cc9cb7fac09f1a8396f7593a37be55154e40f5a6 Mon Sep 17 00:00:00 2001 From: Jeremy Fitzhardinge Date: Mon, 17 Oct 2022 22:17:18 -0700 Subject: [PATCH 5/7] Fix nightly warnings --- tracing-appender/src/lib.rs | 1 - tracing-attributes/src/lib.rs | 1 - tracing-core/src/field.rs | 1 + tracing-core/src/lib.rs | 1 - tracing-error/src/lib.rs | 1 - tracing-flame/src/lib.rs | 4 +--- tracing-futures/src/executor/mod.rs | 2 -- tracing-futures/src/lib.rs | 1 - tracing-log/src/lib.rs | 1 - tracing-serde/src/lib.rs | 1 - tracing-subscriber/src/lib.rs | 1 - tracing-tower/src/lib.rs | 1 - tracing/src/field.rs | 1 + tracing/src/lib.rs | 1 - 14 files changed, 3 insertions(+), 15 deletions(-) diff --git a/tracing-appender/src/lib.rs b/tracing-appender/src/lib.rs index 43f946a486..3bb1016820 100644 --- a/tracing-appender/src/lib.rs +++ b/tracing-appender/src/lib.rs @@ -133,7 +133,6 @@ rust_2018_idioms, unreachable_pub, bad_style, - const_err, dead_code, improper_ctypes, non_shorthand_field_patterns, diff --git a/tracing-attributes/src/lib.rs b/tracing-attributes/src/lib.rs index 13adc2ff75..4e856c899d 100644 --- a/tracing-attributes/src/lib.rs +++ b/tracing-attributes/src/lib.rs @@ -64,7 +64,6 @@ rust_2018_idioms, unreachable_pub, bad_style, - const_err, dead_code, improper_ctypes, non_shorthand_field_patterns, diff --git a/tracing-core/src/field.rs b/tracing-core/src/field.rs index 7b6e2cc6e7..12697fd402 100644 --- a/tracing-core/src/field.rs +++ b/tracing-core/src/field.rs @@ -231,6 +231,7 @@ pub trait Visit { /// Note: This is only enabled when the Rust standard library is /// present. /// + /// #[cfg(feature = "std")] #[cfg_attr(docsrs, doc(cfg(feature = "std")))] fn record_error(&mut self, field: &Field, value: &(dyn std::error::Error + 'static)) { diff --git a/tracing-core/src/lib.rs b/tracing-core/src/lib.rs index 41390c07ad..1ac413d284 100644 --- a/tracing-core/src/lib.rs +++ b/tracing-core/src/lib.rs @@ -146,7 +146,6 @@ rust_2018_idioms, unreachable_pub, bad_style, - const_err, dead_code, improper_ctypes, non_shorthand_field_patterns, diff --git a/tracing-error/src/lib.rs b/tracing-error/src/lib.rs index 6b73773b78..1cbf283ddb 100644 --- a/tracing-error/src/lib.rs +++ b/tracing-error/src/lib.rs @@ -190,7 +190,6 @@ rust_2018_idioms, unreachable_pub, bad_style, - const_err, dead_code, improper_ctypes, non_shorthand_field_patterns, diff --git a/tracing-flame/src/lib.rs b/tracing-flame/src/lib.rs index 0c36f6176c..dea0278b11 100644 --- a/tracing-flame/src/lib.rs +++ b/tracing-flame/src/lib.rs @@ -117,7 +117,6 @@ rust_2018_idioms, unreachable_pub, bad_style, - const_err, dead_code, improper_ctypes, non_shorthand_field_patterns, @@ -134,8 +133,7 @@ while_true )] -pub use error::Error; - +use error::Error; use error::Kind; use once_cell::sync::Lazy; use std::cell::Cell; diff --git a/tracing-futures/src/executor/mod.rs b/tracing-futures/src/executor/mod.rs index 442b523b84..ced3b5a460 100644 --- a/tracing-futures/src/executor/mod.rs +++ b/tracing-futures/src/executor/mod.rs @@ -1,7 +1,5 @@ #[cfg(feature = "futures-01")] mod futures_01; -#[cfg(feature = "futures-01")] -pub use self::futures_01::*; #[cfg(feature = "futures_preview")] mod futures_preview; diff --git a/tracing-futures/src/lib.rs b/tracing-futures/src/lib.rs index 8cf9745036..a2aa677655 100644 --- a/tracing-futures/src/lib.rs +++ b/tracing-futures/src/lib.rs @@ -83,7 +83,6 @@ rust_2018_idioms, unreachable_pub, bad_style, - const_err, dead_code, improper_ctypes, non_shorthand_field_patterns, diff --git a/tracing-log/src/lib.rs b/tracing-log/src/lib.rs index dd407dab47..0200f9f791 100644 --- a/tracing-log/src/lib.rs +++ b/tracing-log/src/lib.rs @@ -109,7 +109,6 @@ rust_2018_idioms, unreachable_pub, bad_style, - const_err, dead_code, improper_ctypes, non_shorthand_field_patterns, diff --git a/tracing-serde/src/lib.rs b/tracing-serde/src/lib.rs index 186c976ad1..1721ac3087 100644 --- a/tracing-serde/src/lib.rs +++ b/tracing-serde/src/lib.rs @@ -153,7 +153,6 @@ rust_2018_idioms, unreachable_pub, bad_style, - const_err, dead_code, improper_ctypes, non_shorthand_field_patterns, diff --git a/tracing-subscriber/src/lib.rs b/tracing-subscriber/src/lib.rs index e05a914600..3b8a5c77ab 100644 --- a/tracing-subscriber/src/lib.rs +++ b/tracing-subscriber/src/lib.rs @@ -150,7 +150,6 @@ rust_2018_idioms, unreachable_pub, bad_style, - const_err, dead_code, improper_ctypes, non_shorthand_field_patterns, diff --git a/tracing-tower/src/lib.rs b/tracing-tower/src/lib.rs index 1909440029..41ec704970 100644 --- a/tracing-tower/src/lib.rs +++ b/tracing-tower/src/lib.rs @@ -10,7 +10,6 @@ rust_2018_idioms, unreachable_pub, bad_style, - const_err, dead_code, improper_ctypes, non_shorthand_field_patterns, diff --git a/tracing/src/field.rs b/tracing/src/field.rs index 40937f01d4..55467ebd82 100644 --- a/tracing/src/field.rs +++ b/tracing/src/field.rs @@ -15,6 +15,7 @@ use crate::Metadata; /// should be used whenever possible. /// /// +/// pub trait AsField: crate::sealed::Sealed { /// Attempts to convert `&self` into a `Field` with the specified `metadata`. /// diff --git a/tracing/src/lib.rs b/tracing/src/lib.rs index e5b0bc8484..77b15e0fe1 100644 --- a/tracing/src/lib.rs +++ b/tracing/src/lib.rs @@ -930,7 +930,6 @@ rust_2018_idioms, unreachable_pub, bad_style, - const_err, dead_code, improper_ctypes, non_shorthand_field_patterns, From 4f9585be3f50640171372e9c238d15fc68f4e5ec Mon Sep 17 00:00:00 2001 From: David Barsky Date: Wed, 19 Oct 2022 14:33:32 -0400 Subject: [PATCH 6/7] fixup docs --- tracing-attributes/Cargo.toml | 1 - tracing-attributes/src/lib.rs | 58 ++++++++++------------------------- 2 files changed, 17 insertions(+), 42 deletions(-) diff --git a/tracing-attributes/Cargo.toml b/tracing-attributes/Cargo.toml index fee4f95366..4ef87a7c5f 100644 --- a/tracing-attributes/Cargo.toml +++ b/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 [dev-dependencies] tracing = { path = "../tracing", version = "0.2" } diff --git a/tracing-attributes/src/lib.rs b/tracing-attributes/src/lib.rs index 4e856c899d..ebd1604e07 100644 --- a/tracing-attributes/src/lib.rs +++ b/tracing-attributes/src/lib.rs @@ -12,11 +12,11 @@ //! //! ## Usage //! -//! First, add this to your `Cargo.toml`: +//! In the `Cargo.toml`: //! //! ```toml //! [dependencies] -//! tracing-attributes = "0.1.11" +//! tracing = "0.1" //! ``` //! //! The [`#[instrument]`][instrument] attribute can now be added to a function @@ -24,7 +24,8 @@ //! called. For example: //! //! ``` -//! use tracing_attributes::instrument; +//! # use tracing_attributes as tracing; +//! use tracing::instrument; //! //! #[instrument] //! pub fn my_function(my_arg: usize) { @@ -107,10 +108,10 @@ mod expand; /// - multiple argument names can be passed to `skip`. /// - arguments passed to `skip` do _not_ need to implement `fmt::Debug`. /// -/// You can also pass additional fields (key-value pairs with arbitrary data) -/// to the generated span. This is achieved using the `fields` argument on the -/// `#[instrument]` macro. You can use a string, integer or boolean literal as -/// a value for each field. The name of the field must be a single valid Rust +/// Additional fields (key-value pairs with arbitrary data) can be passed to +/// to the generated span through the `fields` argument on the +/// `#[instrument]` macro. Strings, integers or boolean literals are accepted values +/// for each field. The name of the field must be a single valid Rust /// identifier, nested (dotted) field names are not supported. /// /// Note that overlap between the names of fields and (non-skipped) arguments @@ -138,7 +139,7 @@ mod expand; /// } /// ``` /// Levels can be specified either with [`Level`] constants, literal strings -/// (`"debug", etc) or numerically (1 - 5, corresponding to [`Level::TRACE`] - [`Level::ERROR`]). +/// (e.g., `"debug"`, `"info"`) or numerically (1—5, corresponding to [`Level::TRACE`]—[`Level::ERROR`]). /// /// Overriding the generated span's name: /// ``` @@ -210,7 +211,7 @@ mod expand; /// } /// ``` /// -/// To add an additional context to the span, you can pass key-value pairs to `fields`: +/// To add additional context to the span, pass key-value pairs to `fields`: /// /// ``` /// # use tracing_attributes::instrument; @@ -260,8 +261,8 @@ mod expand; /// } /// ``` /// -/// If the function returns a `Result` and `E` implements `std::fmt::Display`, you can add -/// `err` or `err(Display)` to emit error events when the function returns `Err`: +/// If the function returns a `Result` and `E` implements `std::fmt::Display`, adding +/// `err` or `err(Display)` will emit error events when the function returns `Err`: /// /// ``` /// # use tracing_attributes::instrument; @@ -271,7 +272,7 @@ mod expand; /// } /// ``` /// -/// Similarly, you can override the level of the `err` event: +/// Similarly, overriding the level of the `err` event : /// /// ``` /// # use tracing_attributes::instrument; @@ -284,7 +285,7 @@ mod expand; /// /// By default, error values will be recorded using their `std::fmt::Display` implementations. /// If an error implements `std::fmt::Debug`, it can be recorded using its `Debug` implementation -/// instead, by writing `err(Debug)`: +/// instead by writing `err(Debug)`: /// /// ``` /// # use tracing_attributes::instrument; @@ -343,38 +344,13 @@ mod expand; /// } /// ``` /// -/// Note than on `async-trait` <= 0.1.43, references to the `Self` -/// type inside the `fields` argument were only allowed when the instrumented -/// function is a method (i.e., the function receives `self` as an argument). -/// For example, this *used to not work* because the instrument function -/// didn't receive `self`: -/// ``` -/// # use tracing::instrument; -/// use async_trait::async_trait; -/// -/// #[async_trait] -/// pub trait Bar { -/// async fn bar(); -/// } -/// -/// #[derive(Debug)] -/// struct BarImpl(usize); -/// -/// #[async_trait] -/// impl Bar for BarImpl { -/// #[instrument(fields(tmp = std::any::type_name::()))] -/// async fn bar() {} -/// } -/// ``` -/// Instead, you should manually rewrite any `Self` types as the type for -/// which you implement the trait: `#[instrument(fields(tmp = std::any::type_name::()))]` -/// (or maybe you can just bump `async-trait`). -/// /// [span]: https://docs.rs/tracing/latest/tracing/span/index.html /// [`follows_from`]: https://docs.rs/tracing/latest/tracing/struct.Span.html#method.follows_from /// [`tracing`]: https://github.com/tokio-rs/tracing /// [`fmt::Debug`]: std::fmt::Debug -/// [`Level`]: tracing_core::Level +/// [`Level`]: https://docs.rs/tracing/latest/tracing/struct.Level.html +/// [`Level::TRACE`]: https://docs.rs/tracing/latest/tracing/struct.Level.html#associatedconstant.TRACE +/// [`Level::ERROR`]: https://docs.rs/tracing/latest/tracing/struct.Level.html#associatedconstant.ERROR #[proc_macro_attribute] pub fn instrument( args: proc_macro::TokenStream, From 5bbab29d4452f165f1a80d6badf8d60139872626 Mon Sep 17 00:00:00 2001 From: Jeremy Fitzhardinge Date: Wed, 26 Oct 2022 09:26:03 -0700 Subject: [PATCH 7/7] doc fix fix --- tracing-attributes/src/lib.rs | 1 - 1 file changed, 1 deletion(-) diff --git a/tracing-attributes/src/lib.rs b/tracing-attributes/src/lib.rs index ebd1604e07..79acabe62b 100644 --- a/tracing-attributes/src/lib.rs +++ b/tracing-attributes/src/lib.rs @@ -24,7 +24,6 @@ //! called. For example: //! //! ``` -//! # use tracing_attributes as tracing; //! use tracing::instrument; //! //! #[instrument]