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 <me@davidbarsky.com>

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,

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"

tracing-attributes/src/lib.rs

@@ -12,19 +12,19 @@
 //!
 //! ## 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
 //! to automatically create and enter `tracing` [span] when that function is
 //! 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<T, E>` 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<T, E>` 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,19 +271,20 @@ 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(())
 /// }
 /// ```
 ///
 /// 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::<Self>()))]
-///     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::<Bar>()))]`
-/// (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,

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()

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();
+}

tracing-core/src/field.rs

@@ -231,6 +231,7 @@ pub trait Visit {
     /// <strong>Note</strong>: This is only enabled when the Rust standard library is
     /// present.
     /// </pre>
+    /// </div>
     #[cfg(feature = "std")]
     #[cfg_attr(docsrs, doc(cfg(feature = "std")))]
     fn record_error(&mut self, field: &Field, value: &(dyn std::error::Error + 'static)) {

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,

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,

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;

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;

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,

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,

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,

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,

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,

tracing/src/field.rs

@@ -15,6 +15,7 @@ use crate::Metadata;
 /// should be used whenever possible.
 ///
 /// </pre>
+/// </div>
 pub trait AsField: crate::sealed::Sealed {
     /// Attempts to convert `&self` into a `Field` with the specified `metadata`.
     ///

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,