tracing-attributes: document skip in #[instrument] (#468)

Authored-By: David Barsky <[email protected]>

Author: davidbarsky

tracing-attributes/Cargo.toml

@@ -44,6 +44,7 @@ quote = "1"
 
 [dev-dependencies]
 tracing = "0.1"
+tracing-futures = "0.2"
 
 [badges]
 azure-devops = { project = "tracing/tracing", pipeline = "tokio-rs.tracing", build = "1" }

tracing-attributes/src/lib.rs

@@ -75,8 +75,15 @@ use syn::{
 /// Instruments a function to create and enter a `tracing` [span] every time
 /// the function is called.
 ///
-/// The generated span's name will be the name of the function, and any
-/// arguments to that function will be recorded as fields using `fmt::Debug`.
+/// The generated span's name will be the name of the function. Any arguments
+/// to that function will be recorded as fields using [`fmt::Debug`]. To skip
+/// recording a function's or method's argument, pass the argument's name
+/// to the `skip` argument on the `#[instrument]` macro. For example,
+/// `skip` can be used when an argument to an instrumented function does
+/// not implement [`fmt::Debug`], or to exclude an argument with a verbose
+/// or costly Debug implementation. Note that:
+/// - multiple argument names can be passed to `skip`.
+/// - arguments passed to `skip` do _not_ need to implement `fmt::Debug`.
 ///
 /// # Examples
 /// Instrumenting a function:
@@ -110,14 +117,24 @@ use syn::{
 /// # fn main() {}
 /// ```
 ///
-/// When the `async-await` feature flag is enabled, `async fn`s may also be
-/// instrumented:
+/// To skip recording an argument, pass the argument's name to the `skip`:
 ///
-/// ```compile_fail
-/// // this currently only compiles on nightly.
-/// #![feature(async-await)]
+/// ```
 /// # use tracing_attributes::instrument;
+/// struct NonDebug;
+///
+/// #[instrument(skip(non_debug))]
+/// fn my_function(arg: usize, non_debug: NonDebug) {
+///     // ...
+/// }
+/// # fn main() {}
+/// ```
+///
+/// If `tracing_futures` is specified as a dependency in `Cargo.toml`,
+/// `async fn`s may also be instrumented:
 ///
+/// ```
+/// # use tracing_attributes::instrument;
 /// #[instrument]
 /// pub async fn my_function() -> Result<(), ()> {
 ///     // ...
@@ -126,13 +143,9 @@ use syn::{
 /// # fn main() {}
 /// ```
 ///
-/// # Notes
-/// - All argument types must implement `fmt::Debug`
-/// - When using `#[instrument]` on an `async fn`, the `tracing_futures` must
-///   also be specified as a dependency in `Cargo.toml`.
-///
 /// [span]: https://docs.rs/tracing/0.1.5/tracing/span/index.html
 /// [`tracing`]: https://github.com/tokio-rs/tracing
+/// [`fmt::Debug`]: https://doc.rust-lang.org/std/fmt/trait.Debug.html
 #[proc_macro_attribute]
 pub fn instrument(args: TokenStream, item: TokenStream) -> TokenStream {
     let input: ItemFn = syn::parse_macro_input!(item as ItemFn);