From 3258a2bb2ae5f1b3be755bffbaef7ff851ec3b4f Mon Sep 17 00:00:00 2001 From: Jeremy Fitzhardinge Date: Thu, 27 Oct 2022 12:20:11 -0700 Subject: [PATCH] attributes: improve docs; tests for using Levels in `#[instrument]` (#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 --- tracing-appender/src/lib.rs | 1 - tracing-attributes/Cargo.toml | 1 - tracing-attributes/src/lib.rs | 67 +++++++++----------------- tracing-attributes/tests/instrument.rs | 2 +- tracing-attributes/tests/levels.rs | 46 ++++++++++++++++++ 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 - 17 files changed, 74 insertions(+), 59 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/Cargo.toml b/tracing-attributes/Cargo.toml index 16d0e903e9..4ef87a7c5f 100644 --- a/tracing-attributes/Cargo.toml +++ b/tracing-attributes/Cargo.toml @@ -42,7 +42,6 @@ quote = "1.0.20" 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 269e32522c..79acabe62b 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,7 @@ //! called. For example: //! //! ``` -//! use tracing_attributes::instrument; +//! use tracing::instrument; //! //! #[instrument] //! pub fn my_function(my_arg: usize) { @@ -64,7 +64,6 @@ rust_2018_idioms, unreachable_pub, bad_style, - const_err, dead_code, improper_ctypes, non_shorthand_field_patterns, @@ -108,10 +107,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 @@ -132,11 +131,15 @@ mod expand; /// Setting the level for the generated span: /// ``` /// # use tracing_attributes::instrument; -/// #[instrument(level = "debug")] +/// # use tracing::Level; +/// #[instrument(level = Level::DEBUG)] /// pub fn my_function() { /// // ... /// } /// ``` +/// Levels can be specified either with [`Level`] constants, literal strings +/// (e.g., `"debug"`, `"info"`) or numerically (1—5, corresponding to [`Level::TRACE`]—[`Level::ERROR`]). +/// /// Overriding the generated span's name: /// ``` /// # use tracing_attributes::instrument; @@ -207,7 +210,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; @@ -235,7 +238,8 @@ mod expand; /// /// ``` /// # use tracing_attributes::instrument; -/// #[instrument(ret(level = "warn"))] +/// # use tracing::Level; +/// #[instrument(ret(level = Level::WARN))] /// fn my_function() -> i32 { /// 42 /// } @@ -256,8 +260,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; @@ -267,11 +271,12 @@ mod expand; /// } /// ``` /// -/// Similarly, you can override the level of the `err` event: +/// Similarly, overriding the level of the `err` event : /// /// ``` /// # use tracing_attributes::instrument; -/// #[instrument(err(level = "info"))] +/// # use tracing::Level; +/// #[instrument(err(level = Level::INFO))] /// fn my_function(arg: usize) -> Result<(), std::io::Error> { /// Ok(()) /// } @@ -279,7 +284,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; @@ -338,37 +343,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`]: 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, 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() 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(); +} 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,