[−][src]Attribute Macro tracing::instrument
#[instrument]
Instruments a function to create and enter a tracing
span every time
the function is called.
By default, the generated span's name will be the name of the function,
the span's target will be the current module path, and the span's level
will be INFO
, although these properties can be overridden. Any arguments
to that function will be recorded as fields using fmt::Debug
.
Overriding Span Attributes
To change the name of the generated span, add a name
argument to the
#[instrument]
macro, followed by an equals sign and a string literal. For
example:
// 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 ... }
To override the target of the generated span, add a target
argument to
the #[instrument]
macro, followed by an equals sign and a string literal
for the new target. The module path is still recorded separately. For
example:
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 ... } }
Finally, to override the level of the generated span, add a level
argument, followed by an equals sign and a string literal with the name of
the desired level. Level names are not case sensitive. For example:
// 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 ... }
Skipping Fields
To skip recording one or more arguments to a function or method, pass
the argument's name inside the skip()
argument on the #[instrument]
macro. This 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 implementfmt::Debug
.
Examples
// This type doesn't implement `fmt::Debug`! struct NonDebug; // `arg` will be recorded, while `non_debug` will not. #[instrument(skip(non_debug))] fn my_function(arg: usize, non_debug: NonDebug) { // ... }
Skipping the self
parameter:
#[derive(Debug)] struct MyType { data: Vec<u8>, // Suppose this buffer is often quite long... } impl MyType { // Suppose we don't want to print an entire kilobyte of `data` // every time this is called... #[instrument(skip(self))] pub fn my_method(&mut self, an_interesting_argument: usize) { // ... do something (hopefully, using all that `data`!) } }
Adding Fields
Additional fields (key-value pairs with arbitrary data) may be added to the
generated span using the fields
argument on the #[instrument]
macro. Any
Rust expression can be used as a field value in this manner. These
expressions will be evaluated at the beginning of the function's body, so
arguments to the function may be used in these expressions. Field names may
also be specified without values. Doing so will result in an empty field
whose value may be recorded later within the function body.
This supports the same field syntax as the span!
and event!
macros.
Note that overlap between the names of fields and (non-skipped) arguments will result in a compile error.
Examples
Adding a new field based on the value of an argument:
// This will record a field named "i" with the value of `i` *and* a field // named "next" with the value of `i` + 1. #[instrument(fields(next = i + 1))] pub fn my_function(i: usize) { // ... }
Recording specific properties of a struct as their own fields:
// This will record the request's URI and HTTP method as their own separate // fields. #[instrument(fields(http.uri = req.uri(), http.method = req.method()))] pub fn handle_request<B>(req: http::Request<B>) -> http::Response<B> { // ... handle the request ... }
This can be used in conjunction with skip
to record only some fields of a
struct:
// Remember the struct with the very large `data` field from the earlier // example? Now it also has a `name`, which we might want to include in // our span. #[derive(Debug)] struct MyType { name: &'static str, data: Vec<u8>, } impl MyType { // This will skip the `data` field, but will include `self.name`, // formatted using `fmt::Display`. #[instrument(skip(self), fields(self.name = %self.name))] pub fn my_method(&mut self, an_interesting_argument: usize) { // ... do something (hopefully, using all that `data`!) } }
Adding an empty field to be recorded later:
// This function does a very interesting and important mathematical calculation. // Suppose we want to record both the inputs to the calculation *and* its result... #[instrument(fields(result))] pub fn do_calculation(input_1: usize, input_2: usize) -> usize { // Rerform the calculation. let result = input_1 + input_2; // Record the result as part of the current span. tracing::Span::current().record("result", &result); // Now, the result will also be included on this event! tracing::info!("calculation complete!"); // ... etc ... }
Examples
Instrumenting a function:
#[instrument] pub fn my_function(my_arg: usize) { // This event will be recorded inside a span named `my_function` with the // field `my_arg`. tracing::info!("inside my_function!"); // ... }
Setting the level for the generated span:
#[instrument(level = "debug")] pub fn my_function() { // ... }
Overriding the generated span's name:
#[instrument(name = "my_name")] pub fn my_function() { // ... }
Overriding the generated span's target:
#[instrument(target = "my_target")] pub fn my_function() { // ... }
To skip recording an argument, pass the argument's name to the skip
:
struct NonDebug; #[instrument(skip(non_debug))] fn my_function(arg: usize, non_debug: NonDebug) { // ... }
To add an additional context to the span, pass key-value pairs to fields
:
#[instrument(fields(foo="bar", id=1, show=true))] fn my_function(arg: usize) { // ... }
If the function returns a Result<T, E>
and E
implements std::fmt::Display
, you can add
err
to emit error events when the function returns Err
:
#[instrument(err)] fn my_function(arg: usize) -> Result<(), std::io::Error> { Ok(()) }
async fn
s may also be instrumented:
#[instrument] pub async fn my_function() -> Result<(), ()> { // ... }
It also works with async-trait (a crate that allows defining async functions in traits, something not currently possible in Rust), and hopefully most libraries that exhibit similar behaviors:
use async_trait::async_trait; #[async_trait] pub trait Foo { async fn foo(&self, arg: usize); } #[derive(Debug)] struct FooImpl(usize); #[async_trait] impl Foo for FooImpl { #[instrument(fields(value = self.0, tmp = std::any::type_name::<Self>()))] async fn foo(&self, arg: usize) {} }
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 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
).