Tracing

https://docs.rs/tracing/latest/
Admin
Tracing is a framework for instrumenting Rust programs to collect structured, event-based diagnostic...
Tokens:342,025
Snippets:2,711
Trust Score:9.7
Update:1 week ago
Show doc for...
Tokens:
Raw
### Usage examples for the info! macro

Source: https://docs.rs/tracing/latest/src/tracing/macros.rs.html?search=std%3A%3Avec

Examples demonstrating how to use the info! macro with fields and custom targets.

```rust
```rust
use tracing::info;
# // this is so the test will still work in no-std mode
# #[derive(Debug)]
# pub struct Ipv4Addr;
# impl Ipv4Addr { fn new(o1: u8, o2: u8, o3: u8, o4: u8) -> Self { Self } }
# fn main() {
# struct Connection { port: u32, speed: f32 }
use tracing::field;

let addr = Ipv4Addr::new(127, 0, 0, 1);
let conn = Connection { port: 40, speed: 3.20 };

info!(conn.port, "connected to {:?}", addr);
info!(
    target: "connection_events",
    ip = ?addr,
    conn.port,
    ?conn.speed,
);
```
```

--------------------------------

### info! macro usage example with fields and target

Source: https://docs.rs/tracing/latest/src/tracing/macros.rs.html?search=

Example from the info! macro documentation showing how to log an event with a field shorthand (conn.port), a format string with arguments, a custom target, and ?-prefixed fields for debug formatting. The example includes a no-std compatible main function and a custom Ipv4Addr type.

```rust
use tracing::info;
# // this is so the test will still work in no-std mode
# #[derive(Debug)]
# pub struct Ipv4Addr;
# impl Ipv4Addr { fn new(o1: u8, o2: u8, o3: u8, o4: u8) -> Self { Self } }
# fn main() {
# struct Connection { port: u32, speed: f32 }
use tracing::field;

let addr = Ipv4Addr::new(127, 0, 0, 1);
let conn = Connection { port: 40, speed: 3.20 };

info!(conn.port, "connected to {:?}", addr);
info!(
    target: "connection_events",
    ip = ?addr,
    conn.port,
    ?conn.speed,
);
}
```

--------------------------------

### Example usage of tracing::warn! macro

Source: https://docs.rs/tracing/latest/src/tracing/macros.rs.html?search=

Shows how to use the warn! macro with different field syntaxes: shorthand ?input, explicit field assignment, and named field with target. The example is wrapped in a main function and uses the tracing crate.

```rust
use tracing::warn;
# fn main() {

let warn_description = "Invalid Input";
let input = &[0x27, 0x45];

warn!(?input, warning = warn_description);
warn!(
    target: "input_events",
    warning = warn_description,
    "Received warning for input: {:?}", input,
);
warn!(name: "invalid", ?input);
# }

```

--------------------------------

### Span::enter examples

Source: https://docs.rs/tracing/latest/tracing/span/struct.Span.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Examples of entering and exiting spans using the enter method and guards.

```APIDOC
## Span::enter examples

### Description
Examples of entering and exiting spans using the enter method and guards.

### Example 1: Basic enter and drop
```rust
let span = span!(Level::INFO, "my_span");
let guard = span.enter();

// code here is within the span

drop(guard);

// code here is no longer within the span
```

### Example 2: Guard dropped implicitly
```rust
fn my_function() -> String {
    // enter a span for the duration of this function.
    let span = trace_span!("my_function");
    let _enter = span.enter();

    // anything happening in functions we call is still inside the span...
    my_other_function();

    // returning from the function drops the guard, exiting the span.
    return "Hello world".to_owned();
}

fn my_other_function() {
    // ...
}
```

### Example 3: Sub-scopes
```rust
let span = info_span!("my_great_span");

{
    let _enter = span.enter();

    // this event occurs inside the span.
    info!("i'm in the span!");

    // exiting the scope drops the guard, exiting the span.
}

// this event is not inside the span.
info!("i'm outside the span!")
```
```

--------------------------------

### tracing::info usage example

Source: https://docs.rs/tracing/latest/tracing/macro.info.html?search=u32+-%3E+bool

Example usage of the info! macro showing field shorthand, target specification, debug formatting, and event naming.

```rust
use tracing::info;
use tracing::field;

let addr = Ipv4Addr::new(127, 0, 0, 1);
let conn = Connection { port: 40, speed: 3.20 };

info!(conn.port, "connected to {:?}", addr);
info!(
    target: "connection_events",
    ip = ?addr,
    conn.port,
    ?conn.speed,
);
info!(name: "completed", "completed connection to {:?}", addr);
```

--------------------------------

### Async function example

Source: https://docs.rs/tracing/latest/src/tracing/span.rs.html

Example of an asynchronous function where Span::enter should be used with caution.

```rust
# use tracing::info_span;
    # async fn some_other_async_function() {}
    async fn my_async_function() {
```

--------------------------------

### Visit Trait Implementation Example

Source: https://docs.rs/tracing/latest/tracing/field/trait.Visit.html?search=

Example implementation of the Visit trait that writes formatted field values to a string using fmt::Debug.

```APIDOC
## Visit Trait Implementation

### Description
A simple visitor that writes to a string. It formats each recorded value using fmt::Debug and appends the field name and formatted value to the provided string.

### Methods
- record_debug(&mut self, field: &Field, value: &dyn fmt::Debug) - Required method. Records a debug value.
- record_i64(&mut self, field: &Field, value: i64) - Default implementation forwards to record_debug.
- record_u64(&mut self, field: &Field, value: u64) - Default implementation forwards to record_debug.
- record_bool(&mut self, field: &Field, value: bool) - Default implementation forwards to record_debug.
- record_str(&mut self, field: &Field, value: &str) - Default implementation forwards to record_debug.
- record_error(&mut self, field: &Field, value: &(dyn Error + 'static)) - Default implementation forwards to record_debug. Only available when the Rust standard library is present.

### Example Code
```rust
use std::fmt::{self, Write};
use tracing::field::{Value, Visit, Field};

pub struct StringVisitor<'a> {
    string: &'a mut String,
}

impl<'a> Visit for StringVisitor<'a> {
    fn record_debug(&mut self, field: &Field, value: &dyn fmt::Debug) {
        write!(self.string, "{} = {:?}; ", field.name(), value).unwrap();
    }
}
```
```

--------------------------------

### Convert a log crate example to tracing

Source: https://docs.rs/tracing/latest/src/tracing/lib.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Shows a drop-in replacement for the `log` crate's yak-shaving example using `tracing` macros. The `#[tracing::instrument]` attribute creates and enters a span for the function, and events are recorded with `debug!` and `warn!`.

```rust
use std::{error::Error, io};
use tracing::{debug, error, info, span, warn, Level};

// the `#[tracing::instrument]` attribute creates and enters a span
// every time the instrumented function is called. The span is named after the
// the function or method. Parameters passed to the function are recorded as fields.
#[tracing::instrument]
pub fn shave(yak: usize) -> Result<(), Box<dyn Error + 'static>> {
    // this creates an event at the DEBUG level with two fields:
    // - `excitement`, with the key "excitement" and the value "yay!"
    // - `message`, with the key "message" and the value "hello! I'm gonna shave a yak."
    //
    // unlike other fields, `message`'s shorthand initialization is just the string itself.
    debug!(excitement = "yay!", "hello! I'm gonna shave a yak.");
    if yak == 3 {
        warn!("could not locate yak!");
        // note that this is intended to demonstrate `tracing`'s features, not idiomatic
        // error handling! in a library or application, you should consider returning
        // a dedicated `YakError`. libraries like snafu or thiserror make this easy.
    }
}
```

--------------------------------

### event! macro usage examples

Source: https://docs.rs/tracing/latest/tracing/macro.event.html

Examples of using the event! macro with different levels, targets, names, and field formatting.

```rust
use tracing::{event, Level};

let data = (42, "forty-two");
let private_data = "private";
let error = "a bad error";

event!(Level::ERROR, %error, "Received error");
event!(
    target: "app_events",
    Level::WARN,
    private_data,
    ?data,
    "App warning: {}",
    error
);
event!(name: "answer", Level::INFO, the_answer = data.0);
event!(Level::INFO, the_answer = data.0);
```

--------------------------------

### Creating a span and entering it

Source: https://docs.rs/tracing/latest/src/tracing/span.rs.html

Basic example of creating a span with the span! macro and entering it with the enter method.

```rust
# use tracing::{span, Level};
let span = span!(Level::INFO, "my_span");
let guard = span.enter();

// code here is within the span
```

--------------------------------

### enabled!

Source: https://docs.rs/tracing/latest/tracing/macro.enabled.html

Documentation for the `enabled!` macro from the `tracing` crate, including syntax, parameters, and usage examples.

```APIDOC
## enabled!

### Description
Checks whether a span or event is enabled based on the provided metadata. This macro is intended to be used prior to an expensive computation required just for that event, but cannot be done as part of an argument to that event.

### Syntax
```rust
macro_rules! enabled {
    (kind: $kind:expr, target: $target:expr, $lvl:expr, { $($fields:tt)* } ) => { ... };
    (kind: $kind:expr, target: $target:expr, $lvl:expr ) => { ... };
    (target: $target:expr, $lvl:expr ) => { ... };
    (kind: $kind:expr, target: $target:expr, $lvl:expr, $($field:tt)*) => { ... };
    (target: $target:expr, $lvl:expr, $($field:tt)*) => { ... };
    (kind: $kind:expr, $lvl:expr, $($field:tt)*) => { ... };
    (kind: $kind:expr, $lvl:expr) => { ... };
    ($lvl:expr) => { ... };
    ($lvl:expr, $($field:tt)*) => { ... };
}
```

### Parameters
- **$lvl** (expr) - Required - The level of the span or event to check.
- **target** (expr) - Optional - The target of the span or event.
- **kind** (expr) - Optional - The kind of the span or event.
- **$field** (tt) - Optional - Field names to include in the check.

### Examples
```rust
use tracing::{enabled, Level};

if enabled!(Level::DEBUG) {
    // some expensive work...
}
```

```rust
if enabled!(target: "my_crate", Level::DEBUG) {
    // some expensive work...
}
```

```rust
if enabled!(target: "my_crate", Level::DEBUG, hello) {
    // some expensive work...
}
```

### Notes
- `enabled!` queries subscribers with `Metadata` where `is_event` and `is_span` both return `false`.
- It may return false positives or false negatives when a subscriber uses a more specific filter than the metadata provided.
- Use `event_enabled!` or `span_enabled!` to ensure one of these returns true.
```

--------------------------------

### Recording events with event!

Source: https://docs.rs/tracing/latest/src/tracing/macros.rs.html?search=

Examples of using the event! macro with various levels, targets, and field shorthand syntax.

```rust
use tracing::{event, Level};

# fn main() {
let data = (42, "forty-two");
let private_data = "private";
let error = "a bad error";

event!(Level::ERROR, %error, "Received error");
event!(
    target: "app_events",
    Level::WARN,
    private_data,
    ?data,
    "App warning: {}",
    error
);
event!(name: "answer", Level::INFO, the_answer = data.0);
event!(Level::INFO, the_answer = data.0);
# }
```

--------------------------------

### Span Entering and Exiting Examples

Source: https://docs.rs/tracing/latest/tracing/span/struct.Span.html

Examples of entering and exiting spans using guards, including explicit drops and sub-scopes.

```APIDOC
## Span Entering and Exiting Examples

### Description
Examples of entering and exiting spans using guards, including explicit drops and sub-scopes.

### Example: Basic enter and drop
```rust
let span = span!(Level::INFO, "my_span");
let guard = span.enter();

// code here is within the span

drop(guard);

// code here is no longer within the span
```

### Example: Guard dropped at end of function
```rust
fn my_function() -> String {
    // enter a span for the duration of this function.
    let span = trace_span!("my_function");
    let _enter = span.enter();

    // anything happening in functions we call is still inside the span...
    my_other_function();

    // returning from the function drops the guard, exiting the span.
    return "Hello world".to_owned();
}

fn my_other_function() {
    // ...
}
```

### Example: Sub-scope to limit span duration
```rust
let span = info_span!("my_great_span");

{
    let _enter = span.enter();

    // this event occurs inside the span.
    info!("i'm in the span!");

    // exiting the scope drops the guard, exiting the span.
}

// this event is not inside the span.
info!("i'm outside the span!")
```
```

--------------------------------

### Upgrading a WeakDispatch example

Source: https://docs.rs/tracing/latest/tracing/dispatcher/struct.WeakDispatch.html?search=u32+-%3E+bool

Example usage of WeakDispatch::upgrade. It creates a strong Dispatch, downgrades it to a WeakDispatch, and checks that upgrade returns Some while the strong reference exists and None after it is dropped.

```rust
let strong = Dispatch::new(NoSubscriber::default());
let weak = strong.downgrade();

// The strong here keeps it alive, so we can still access the object.
assert!(weak.upgrade().is_some());

drop(strong); // But not any more.
assert!(weak.upgrade().is_none());
```

--------------------------------

### Using the warn! macro

Source: https://docs.rs/tracing/latest/src/tracing/macros.rs.html?search=std%3A%3Avec

Examples of using the warn! macro to log events with fields, custom targets, and names.

```rust
use tracing::warn;
# fn main() {

let warn_description = "Invalid Input";
let input = &[0x27, 0x45];

warn!(?input, warning = warn_description);
warn!(
    target: "input_events",
    warning = warn_description,
    "Received warning for input: {:?}", input,
);
warn!(name: "invalid", ?input);
# }
```

--------------------------------

### tracing::error! usage example

Source: https://docs.rs/tracing/latest/tracing/macro.error.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Example usage of the tracing::error! macro, showing how to log an error with fields, a target, and a name.

```rust
use tracing::error;

let (err_info, port) = ("No connection", 22);

error!(port, error = %err_info);
error!(target: "app_events", "App Error: {}", err_info);
error!({ info = err_info }, "error on port: {}", port);
error!(name: "invalid_input", "Invalid input: {}", err_info);
```

--------------------------------

### Example: Entering and exiting a span with explicit drop

Source: https://docs.rs/tracing/latest/tracing/span/struct.EnteredSpan.html

Shows entering a span, running code within it, and explicitly dropping the guard to exit the span.

```rust
let span = span!(Level::INFO, "my_span");
let guard = span.enter();

// code here is within the span

drop(guard);

// code here is no longer within the span
```

--------------------------------

### Visit trait implementation for numeric values

Source: https://docs.rs/tracing/latest/tracing/field/trait.Visit.html

Example of implementing the Visit trait to sum numeric values and ignore others.

```APIDOC
## Visit trait implementation for numeric values

### Description
This example shows a visitor that sums numeric values and ignores all other values.

### Methods
- `record_i64`
- `record_u64`
- `record_debug`

### Parameters
- `field` (&Field) - The field being recorded.
- `value` (i64 or u64) - The numeric value to record.

### Example
```rust
pub struct SumVisitor {
    sum: i64,
}

impl Visit for SumVisitor {
    fn record_i64(&mut self, _field: &Field, value: i64) {
        self.sum += value;
    }

    fn record_u64(&mut self, _field: &Field, value: u64) {
        self.sum += value as i64;
    }

    fn record_debug(&mut self, _field: &Field, _value: &dyn fmt::Debug) {
        // Do nothing
    }
}
```

### Notes
- The `record_error` method is only available when the Rust standard library is present.
```

--------------------------------

### Create a Dispatch from a subscriber

Source: https://docs.rs/tracing/latest/src/tracing/dispatcher.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Shows how to wrap a subscriber in a Dispatch, a cloneable, type-erased reference, before setting it as the default. The example defines a minimal FooSubscriber and creates a Dispatch from it.

```rust
//! Dispatches trace events to [`Subscriber`]s.
//!
//! The _dispatcher_ is the component of the tracing system which is responsible
//! for forwarding trace data from the instrumentation points that generate it
//! to the subscriber that collects it.
//!
//! # Using the Trace Dispatcher
//!
//! Every thread in a program using `tracing` has a _default subscriber_. When
//! events occur, or spans are created, they are dispatched to the thread's
//! current subscriber.
//!
//! ## Setting the Default Subscriber
//!
//! By default, the current subscriber is an empty implementation that does
//! nothing. To use a subscriber implementation, it must be set as the default.
//! There are two methods for doing so: [`with_default`] and
//! [`set_global_default`]. `with_default` sets the default subscriber for the
//! duration of a scope, while `set_global_default` sets a default subscriber
//! for the entire process.
//!
//! To use either of these functions, we must first wrap our subscriber in a
//! [`Dispatch`], a cloneable, type-erased reference to a subscriber. For
//! example:
```rust
# pub struct FooSubscriber;
# use tracing_core::{
#   dispatcher, Event, Metadata,
#   span::{Attributes, Id, Record}
# };
# impl tracing_core::Subscriber for FooSubscriber {
#   fn new_span(&self, _: &Attributes) -> Id { Id::from_u64(0) }
#   fn record(&self, _: &Id, _: &Record) {}
#   fn event(&self, _: &Event) {}
#   fn record_follows_from(&self, _: &Id, _: &Id) {}
#   fn enabled(&self, _: &Metadata) -> bool { false }
#   fn enter(&self, _: &Id) {}
#   fn exit(&self, _: &Id) {}
# }
# impl FooSubscriber { fn new() -> Self { FooSubscriber } }
use dispatcher::Dispatch;

let my_subscriber = FooSubscriber::new();
let my_dispatch = Dispatch::new(my_subscriber);
```
```

--------------------------------

### Subscriber Filtering Example

Source: https://docs.rs/tracing/latest/tracing/struct.Level.html?search=u32+-%3E+bool

Example of implementing a Subscriber that uses LevelFilter to enable spans and events up to a maximum level.

```APIDOC
## Subscriber Filtering Example

### Description
Shows how a Subscriber can implement filtering through a LevelFilter. The enabled method compares the span or event's Level against the configured LevelFilter. The max_level_hint method can be implemented to skip spans and events above a maximum verbosity level.

### Example
```rust
use tracing_core::{span, Event, Level, LevelFilter, Subscriber, Metadata};

#[derive(Debug)]
pub struct MySubscriber {
    /// The most verbose level that this subscriber will enable.
    max_level: LevelFilter,

    // ...
}

impl MySubscriber {
    /// Returns a new `MySubscriber` which will record spans and events up to
    /// `max_level`.
    pub fn with_max_level(max_level: LevelFilter) -> Self {
        Self {
            max_level,
            // ...
        }
    }
}
impl Subscriber for MySubscriber {
    fn enabled(&self, meta: &Metadata<'_>) -> bool {
        // A span or event is enabled if it is at or below the configured
        // maximum level.
        meta.level() <= &self.max_level
    }

    // This optional method returns the most verbose level that this
    // subscriber will enable. Although implementing this method is not
    // *required*, it permits additional optimizations when it is provided,
    // allowing spans and events above the max level to be skipped
    // more efficiently.
    fn max_level_hint(&self) -> Option<LevelFilter> {
        Some(self.max_level)
    }

    // Implement the rest of the subscriber...
    fn new_span(&self, span: &span::Attributes<'_>) -> span::Id {
        // ...
    }

    fn event(&self, event: &Event<'_>) {
        // ...
    }

    // ...
}
```
```

--------------------------------

### Visit Trait Override Example

Source: https://docs.rs/tracing/latest/tracing/field/trait.Visit.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Example of overriding default methods to implement type-specific behavior, such as summing numeric values.

```APIDOC
## Visit Trait Override Example

### Description
This example shows how to override the default implementations of record_i64 and record_u64 to accumulate numeric values, while ignoring other types.

### Example Implementation
```rust
pub struct SumVisitor {
    sum: i64,
}

impl Visit for SumVisitor {
    fn record_i64(&mut self, _field: &Field, value: i64) {
        self.sum += value;
    }

    fn record_u64(&mut self, _field: &Field, value: u64) {
        self.sum += value as i64;
    }

    fn record_debug(&mut self, _field: &Field, _value: &dyn fmt::Debug) {
        // Do nothing
    }
}
```

### Notes
- The visitor keeps a running sum of all numeric values it records.
- It ignores all other values by doing nothing in record_debug.
```

--------------------------------

### Create and enter a span with tracing::span!

Source: https://docs.rs/tracing/latest/tracing/index.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Shows how to create a span using the `span!` macro and enter it with `span.enter()`, which returns a RAII guard that exits the span when dropped. Note the warning: in async code, holding the guard across an await point may produce incorrect traces.

```rust
use tracing::{span, Level};
let span = span!(Level::TRACE, "my_span");
// `enter` returns a RAII guard which, when dropped, exits the span. this
// indicates that we are in the span for the current lexical scope.
let _enter = span.enter();
// perform some work in the context of `my_span`...

```

--------------------------------

### #[instrument]

Source: https://docs.rs/tracing/latest/tracing/attr.instrument.html?search=std%3A%3Avec

Documentation for the `#[instrument]` attribute macro from the `tracing` crate, including its purpose, usage, and available arguments.

```APIDOC
## #[instrument]

### Description
Instruments a function to create and enter a `tracing` span every time the function is called. Unless overridden, a span with the `INFO` level will be generated. The generated span's name will be the name of the function. By default, all arguments to the function are included as fields on the span.

### Usage
Apply the `#[instrument]` attribute macro to a function. The macro is available on the `attributes` crate feature only.

### Parameters
#### Attribute Arguments
- **name** (string literal) - Optional - Overrides the generated span's name. Example: `#[instrument(name = "my_span")]`.
- **target** (string literal) - Optional - Overrides the target of the generated span. The module path is still recorded separately. Example: `#[instrument(target = "my_crate::some_special_target")]`.
- **level** (string literal) - Optional - Overrides the level of the generated span. Level names are not case sensitive. Example: `#[instrument(level = "trace")]`.

### Behavior
- The generated span's name defaults to the function name.
- The default level is `INFO`.
- All function arguments are included as fields on the span by default.
- Arguments implementing the `Value` trait are recorded as fields of that type; other arguments are recorded using `fmt::Debug`.

### Examples
```rust
// The generated span's name will be "my_span" rather than "my_function".
#[instrument(name = "my_span")]
pub fn my_function() {
    // ... do something incredibly interesting and important ...
}
```

```rust
pub mod my_module {
    // The generated span's target will be "my_crate::some_special_target",
    // rather than "my_crate::my_module".
    #[instrument(target = "my_crate::some_special_target")]
    pub fn my_function() {
        // ... all kinds of neat code in here ...
    }
}
```

```rust
// The span's level will be TRACE rather than INFO.
#[instrument(level = "trace")]
pub fn my_function() {
    // ... I have written a truly marvelous implementation of this function,
    // which this example is too narrow to contain ...
}
```
```

--------------------------------

### impl<T> Any for T

Source: https://docs.rs/tracing/latest/tracing/dispatcher/struct.SetGlobalDefaultError.html?search=std%3A%3Avec

Provides the type_id method to get the TypeId of a value.

```APIDOC
## impl<T> Any for T

### Description
Gets the TypeId of self.

### Method
fn type_id(&self) -> TypeId

### Parameters
None

### Returns
TypeId - The TypeId of the value.
```

--------------------------------

### inner_pin_ref

Source: https://docs.rs/tracing/latest/src/tracing/instrument.rs.html

Get a pinned reference to the wrapped type, returning a Pin<&T>.

```APIDOC
## inner_pin_ref

### Description
Get a pinned reference to the wrapped type.

### Method
inner_pin_ref

### Signature
pub fn inner_pin_ref(self: Pin<&Self>) -> Pin<&T>

### Parameters
- **self** (Pin<&Self>) - Required - A pinned reference to the Instrumented instance.

### Returns
- **Pin<&T>** - A pinned reference to the wrapped value.

```

--------------------------------

### record_all! macro usage

Source: https://docs.rs/tracing/latest/src/tracing/macros.rs.html?search=

Demonstrates how to use the record_all! macro to record fields for an existing span. The macro supports % for Display and ? for Debug implementations.

```rust
# use tracing::{field, info_span, record_all};
let span = info_span!("my span", field1 = field::Empty, field2 = field::Empty, field3 = field::Empty).entered();
record_all!(span, field1 = ?"1", field2 = %"2", field3 = 3);
```

--------------------------------

### inner_pin_mut

Source: https://docs.rs/tracing/latest/src/tracing/instrument.rs.html

Get a pinned mutable reference to the wrapped type, returning a Pin<&mut T>.

```APIDOC
## inner_pin_mut

### Description
Get a pinned mutable reference to the wrapped type.

### Method
inner_pin_mut

### Signature
pub fn inner_pin_mut(self: Pin<&mut Self>) -> Pin<&mut T>

### Parameters
- **self** (Pin<&mut Self>) - Required - A pinned mutable reference to the Instrumented instance.

### Returns
- **Pin<&mut T>** - A pinned mutable reference to the wrapped value.

```

--------------------------------

### Recording span fields

Source: https://docs.rs/tracing/latest/src/tracing/span.rs.html

Example of creating a span with an empty field and recording its value later.

```rust
use tracing::{trace_span, field};

// Create a span with two fields: `greeting`, with the value "hello world", and
// `parting`, without a value.
```

--------------------------------

### Create and enter a span

Source: https://docs.rs/tracing/latest/index.html

Demonstrates creating a span and using the enter method to return a RAII guard for the current lexical scope.

```rust
use tracing::{span, Level};
let span = span!(Level::TRACE, "my_span");
// `enter` returns a RAII guard which, when dropped, exits the span. this
// indicates that we are in the span for the current lexical scope.
let _enter = span.enter();
// perform some work in the context of `my_span`...
```

--------------------------------

### Get the current span with current

Source: https://docs.rs/tracing/latest/src/tracing/span.rs.html

Returns a handle to the span currently considered active by the subscriber.

```rust
pub fn current() -> Span {
        dispatcher::get_default(|dispatch| {
            if let Some((id, meta)) = dispatch.current_span().into_inner() {
                let id = dispatch.clone_span(&id);
                Self {
                    inner: Some(Inner::new(id, dispatch)),
                    meta: Some(meta),
                }
            } else {
                Self::none()
            }
        })
    }
```

--------------------------------

### Constructing trace events

Source: https://docs.rs/tracing/latest/src/tracing/macros.rs.html?search=

Demonstrates how to use the trace! macro to log events with fields, targets, and custom messages. The macro supports shorthand field syntax and explicit target specification.

```rust
use tracing::trace;
# #[derive(Debug, Copy, Clone)] struct Position { x: f32, y: f32 }
# impl Position {
# const ORIGIN: Self = Self { x: 0.0, y: 0.0 };
# fn dist(&self, other: Position) -> f32 {
#    let x = (other.x - self.x).exp2(); let y = (self.y - other.y).exp2();
#    (x + y).sqrt()
# }
# }
# fn main() {
let pos = Position { x: 3.234, y: -1.223 };
let origin_dist = pos.dist(Position::ORIGIN);

trace!(position = ?pos, ?origin_dist);
trace!(
    target: "app_events",
    position = ?pos,
    "x is {} and y is {}",
    if pos.x >= 0.0 { "positive" } else { "negative" },
    if pos.y >= 0.0 { "positive" } else { "negative" }
);
trace!(name: "completed", position = ?pos);
# }
```

--------------------------------

### Macro: info

Source: https://docs.rs/tracing/latest/tracing?search=

Constructs an event at the info level.

```APIDOC
## Macro: info

### Description
Constructs an event at the info level.

### Usage
Use this macro to create and record an event with the info verbosity level.

### Parameters
- **target** (string literal) - Optional - The target for the event.
- **parent** (span) - Optional - The parent span for the event.
- **fields** (key-value pairs) - Optional - Fields to record with the event.

### Example
```rust
tracing::info!("informational message");
```
```

--------------------------------

### Equivalent using enter() with let-binding

Source: https://docs.rs/tracing/latest/src/tracing/span.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Shows the equivalent code using `Span::enter` with a `let`-binding, as an alternative to `entered()`.

```rust
# use tracing::info_span;
let span = info_span!("something_interesting");
let _e = span.enter();
```

--------------------------------

### Record a span using span! macro

Source: https://docs.rs/tracing/latest/index.html

Construct a span and use the enter method to record that the span has been entered, returning a guard that exits the span when dropped.

```rust
use tracing::{span, Level};
// Construct a new span named "my span" with trace log level.
let span = span!(Level::TRACE, "my span");

// Enter the span, returning a guard object.
let _enter = span.enter();

// Any trace events that occur before the guard is dropped will occur
// within the span.

// Dropping the guard will exit the span.
```

--------------------------------

### Visit Trait Implementation with Type-Specific Behavior

Source: https://docs.rs/tracing/latest/tracing/field/trait.Visit.html?search=

Example implementation of the Visit trait that only records numeric values and ignores others.

```APIDOC
## Visit Trait Implementation with Type-Specific Behavior

### Description
A visitor that keeps a running sum of all numeric values it records and ignores all other values.

### Methods
- record_i64(&mut self, field: &Field, value: i64) - Adds the value to the sum.
- record_u64(&mut self, field: &Field, value: u64) - Adds the value (as i64) to the sum.
- record_debug(&mut self, field: &Field, value: &dyn fmt::Debug) - Does nothing.

### Example Code
```rust
pub struct SumVisitor {
    sum: i64,
}

impl Visit for SumVisitor {
    fn record_i64(&mut self, _field: &Field, value: i64) {
        self.sum += value;
    }

    fn record_u64(&mut self, _field: &Field, value: u64) {
        self.sum += value as i64;
    }

    fn record_debug(&mut self, _field: &Field, _value: &dyn fmt::Debug) {
        // Do nothing
    }
}
```
```

--------------------------------

### Loop with per-iteration spans

Source: https://docs.rs/tracing/latest/src/tracing/span.rs.html

Example of creating a new span for each iteration of a loop to measure time spent in each individual iteration.

```rust
# use tracing::{Level, span};
# let n = 1u64;
for i in 0..n {
    let span = span!(Level::TRACE, "my_loop", iteration = i);
    let _enter = span.enter();
    // ...
}
```

--------------------------------

### Usage of the debug! macro

Source: https://docs.rs/tracing/latest/src/tracing/macros.rs.html?search=

Demonstrates how to use the debug! macro to log events at the debug level, including field shorthand and custom targets.

```rust
use tracing::debug;
# fn main() {
# #[derive(Debug)] struct Position { x: f32, y: f32 }

let pos = Position { x: 3.234, y: -1.223 };

debug!(?pos.x, ?pos.y);
debug!(target: "app_events", position = ?pos, "New position");
debug!(name: "completed", position = ?pos);
# }
```

--------------------------------

### Loop with a single span

Source: https://docs.rs/tracing/latest/src/tracing/span.rs.html

Example of wrapping an entire loop within a single span to measure total execution time.

```rust
# use tracing::{Level, span};
# let n = 1;
let span = span!(Level::TRACE, "my_loop");
let _enter = span.enter();
for i in 0..n {
    # let _ = i;
    // ...
}
```

--------------------------------

### Instrument functions with tracing::instrument

Source: https://docs.rs/tracing/latest/src/tracing/lib.rs.html

An example of using the instrument attribute to automatically create spans and log events within a function.

```rust
use std::{error::Error, io};
use tracing::{debug, error, info, span, warn, Level};

// the `#[tracing::instrument]` attribute creates and enters a span
// every time the instrumented function is called. The span is named after the
// the function or method. Parameters passed to the function are recorded as fields.
#[tracing::instrument]
pub fn shave(yak: usize) -> Result<(), Box<dyn Error + 'static>> {
    // this creates an event at the DEBUG level with two fields:
    // - `excitement`, with the key "excitement" and the value "yay!"
    // - `message`, with the key "message" and the value "hello! I'm gonna shave a yak."
    //
    // unlike other fields, `message`'s shorthand initialization is just the string itself.
    debug!(excitement = "yay!", "hello! I'm gonna shave a yak.");
    if yak == 3 {
        warn!("could not locate yak!");
        // note that this is intended to demonstrate `tracing`'s features, not idiomatic
        // error handling! in a library or application, you should consider returning
        // a dedicated `YakError`. libraries like snafu or thiserror make this easy.
```

--------------------------------

### Macro `event!`

Source: https://docs.rs/tracing/latest/tracing/macro.event.html?search=std%3A%3Avec

Documentation for the `event!` macro from the `tracing` crate, including its syntax and parameters.

```APIDOC
## Macro `event!`

### Description
Constructs a new `Event` with a specified `Level` and up to 32 key-value fields. Optionally, a format string and arguments may follow the fields to construct an implicit field named "message".

### Syntax
```rust
macro_rules! event {
    (name: $name:expr, target: $target:expr, parent: $parent:expr, $lvl:expr, { $($fields:tt)* } ) => { ... };
    (name: $name:expr, target: $target:expr, parent: $parent:expr, $lvl:expr, { $($fields:tt)* }, $($arg:tt)+ ) => { ... };
    (name: $name:expr, target: $target:expr, parent: $parent:expr, $lvl:expr, $($k:ident).+ = $($fields:tt)* ) => { ... };
    (name: $name:expr, target: $target:expr, parent: $parent:expr, $lvl:expr, $($arg:tt)+) => { ... };
    (name: $name:expr, target: $target:expr, $lvl:expr, { $($fields:tt)* } ) => { ... };
    (name: $name:expr, target: $target:expr, $lvl:expr, { $($fields:tt)* }, $($arg:tt)+ ) => { ... };
    (name: $name:expr, target: $target:expr, $lvl:expr, $($k:ident).+ = $($fields:tt)* ) => { ... };
    (name: $name:expr, target: $target:expr, $lvl:expr, $($arg:tt)+) => { ... };
    (target: $target:expr, parent: $parent:expr, $lvl:expr, { $($fields:tt)* } ) => { ... };
    (target: $target:expr, parent: $parent:expr, $lvl:expr, { $($fields:tt)* }, $($arg:tt)+ ) => { ... };
    (target: $target:expr, parent: $parent:expr, $lvl:expr, $($k:ident).+ = $($fields:tt)* ) => { ... };
    (target: $target:expr, parent: $parent:expr, $lvl:expr, $($arg:tt)+) => { ... };
    (name: $name:expr, parent: $parent:expr, $lvl:expr, { $($fields:tt)* } ) => { ... };
    (name: $name:expr, parent: $parent:expr, $lvl:expr, { $($fields:tt)* }, $($arg:tt)+ ) => { ... };
    (name: $name:expr, parent: $parent:expr, $lvl:expr, $($k:ident).+ = $($fields:tt)* ) => { ... };
    (name: $name:expr, parent: $parent:expr, $lvl:expr, $($arg:tt)+) => { ... };
    (name: $name:expr, $lvl:expr, { $($fields:tt)* } ) => { ... };
    (name: $name:expr, $lvl:expr, { $($fields:tt)* }, $($arg:tt)+ ) => { ... };
    (name: $name:expr, $lvl:expr, $($k:ident).+ = $($fields:tt)* ) => { ... };
    (name: $name:expr, $lvl:expr, $($arg:tt)+ ) => { ... };
    (target: $target:expr, $lvl:expr, { $($fields:tt)* } ) => { ... };
    (target: $target:expr, $lvl:expr, { $($fields:tt)* }, $($arg:tt)+ ) => { ... };
    (target: $target:expr, $lvl:expr, $($k:ident).+ = $($fields:tt)* ) => { ... };
    (target: $target:expr, $lvl:expr, $($arg:tt)+ ) => { ... };
    (parent: $parent:expr, $lvl:expr, { $($fields:tt)* }, $($arg:tt)+ ) => { ... };
    (parent: $parent:expr, $lvl:expr, $($k:ident).+ = $($field:tt)*) => { ... };
    (parent: $parent:expr, $lvl:expr, ?$($k:ident).+ = $($field:tt)*) => { ... };
    (parent: $parent:expr, $lvl:expr, %$($k:ident).+ = $($field:tt)*) => { ... };
    (parent: $parent:expr, $lvl:expr, $($k:ident).+, $($field:tt)*) => { ... };
    (parent: $parent:expr, $lvl:expr, %$($k:ident).+, $($field:tt)*) => { ... };
    (parent: $parent:expr, $lvl:expr, ?$($k:ident).+, $($field:tt)*) => { ... };
    (parent: $parent:expr, $lvl:expr, $($arg:tt)+ ) => { ... };
    ( $lvl:expr, { $($fields:tt)* }, $($arg:tt)+ ) => { ... };
    ( $lvl:expr, { $($fields:tt)* }, $($arg:tt)+ ) => { ... };
    ($lvl:expr, $($k:ident).+ = $($field:tt)*) => { ... };
    ($lvl:expr, $($k:ident).+, $($field:tt)*) => { ... };
    ($lvl:expr, ?$($k:ident).+, $($field:tt)*) => { ... };
    ($lvl:expr, %$($k:ident).+, $($field:tt)*) => { ... };
    ($lvl:expr, ?$($k:ident).+) => { ... };
    ($lvl:expr, %$($k:ident).+) => { ... };
    ($lvl:expr, $($k:ident).+) => { ... };
    ( $lvl:expr, $($arg:tt)+ ) => { ... };
}
```

### Parameters
- `name` (expr) - Optional - The name of the event.
- `target` (expr) - Optional - The target for the event.
- `parent` (expr) - Optional - The parent span for the event.
- `$lvl` (expr) - Required - The `Level` at which the event is recorded.
- `$($fields:tt)*` - Optional - Key-value fields to be recorded with the event.
- `$($arg:tt)+` - Optional - Format string and arguments used to construct an implicit field named "message".

### Usage
See the top-level documentation for details on the syntax accepted by this macro.
```
Tokens:
Raw