attributes: support adding arbitrary fields to the instrument macro

tracing-attributes/src/lib.rs

@@ -86,6 +86,14 @@ use syn::{
 /// - 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 valid
+/// Rust identifier, nested (dotted) field names are not supported.
+///
+/// Note that overlap between the names of fields and (non-skipped) arguments will result in a
+/// compile error.
+///
 /// # Examples
 /// Instrumenting a function:
 /// ```
@@ -127,6 +135,16 @@ use syn::{
 /// }
 /// ```
 ///
+/// To add an additional context to the span, you can pass key-value pairs to `fields`:
+///
+/// ```
+/// # use tracing_attributes::instrument;
+/// #[instrument(fields(foo="bar", id=1, show=true))]
+/// fn my_function(arg: usize) {
+///     // ...
+/// }
+/// ```
+///
 /// If `tracing_futures` is specified as a dependency in `Cargo.toml`,
 /// `async fn`s may also be instrumented:
 ///