[−][src]Macro tracing::span
Constructs a new span.
Examples
Creating a new span:
#[macro_use] extern crate tracing; use tracing::Level; let span = span!(Level::TRACE, "my span"); let _enter = span.enter(); // do work inside the span...
Recording Fields
Span fields are written using the syntax key = value
.
// construct a new span with two fields: // - "foo", with a value of 42, // - "bar", with the value "false" let my_span = span!(Level::INFO, "my_span", foo = 42, bar = false);
Note that a trailing comma on the final field is valid:
span!( Level::INFO, "my_span", foo = 42, bar = false, );
As shorthand, local variables may be used as field values without an assignment, similar to struct initializers. For example:
let user = "ferris"; span!(Level::TRACE, "login", user); // is equivalent to: span!(Level::TRACE, "login", user = user);
Field names can include dots, but should not be terminated by them:
let user = "ferris"; let email = "ferris@rust-lang.org"; span!(Level::TRACE, "login", user, user.email = email);
Since field names can include dots, fields on local structs can be used using the local variable shorthand:
let user = User { name: "ferris", email: "ferris@rust-lang.org", }; // the span will have the fields `user.name = "ferris"` and // `user.email = "ferris@rust-lang.org"`. span!(Level::TRACE, "login", user.name, user.email);
The ?
sigil is shorthand for field::debug
:
#[derive(Debug)] struct MyStruct { field: &'static str, } let my_struct = MyStruct { field: "Hello world!" }; // `my_struct` will be recorded using its `fmt::Debug` implementation. span!(Level::TRACE, "my span", foo = ?my_struct); // is equivalent to: span!(Level::TRACE, "my span", foo = tracing::field::debug(&my_struct));
The %
character is shorthand for field::display
:
// `my_struct.field` will be recorded using its `fmt::Display` implementation. span!(Level::TRACE, "my span", foo = %my_struct.field); // is equivalent to: span!(Level::TRACE, "my span", foo = tracing::field::display(&my_struct.field));
The %
and ?
sigils may also be used with local variable shorthand:
// `my_struct.field` will be recorded using its `fmt::Display` implementation. let my_span = span!(Level::TRACE, "my span", %my_struct.field);
Note that a span may have up to 32 fields. The following will not compile:
span!( Level::TRACE, "too many fields!", a = 1, b = 2, c = 3, d = 4, e = 5, f = 6, g = 7, h = 8, i = 9, j = 10, k = 11, l = 12, m = 13, n = 14, o = 15, p = 16, q = 17, r = 18, s = 19, t = 20, u = 21, v = 22, w = 23, x = 24, y = 25, z = 26, aa = 27, bb = 28, cc = 29, dd = 30, ee = 31, ff = 32, gg = 33 );
Setting Span Attributes
In addition to the level and name of the span, which are required, the target and parent span may be overridden. For example:
Creating a span with custom target:
span!(target: "app_span", Level::TRACE, "my span");
Creating a span with an explicit parent:
// Create, but do not enter, a span called "foo". let foo = span!(Level::INFO, "foo"); // Create and enter a span called "bar". let bar = span!(Level::INFO, "bar"); let _enter = bar.enter(); // Although we have currently entered "bar", "baz"'s parent span // will be "foo". let baz = span!(parent: &foo, Level::INFO, "baz");
Creating a span without a parent:
let foo = span!(Level::INFO, "foo"); let _enter = foo.enter(); // Although we have currently entered "foo", "bar" will be created // as the root of its own trace tree: let bar = span!(parent: None, Level::INFO, "bar");
Both the parent and target may be overridden simultaenously:
let foo = span!(Level::INFO, "foo"); let bar = span!(target: "bar_events", parent: &foo, Level::INFO, "bar");
By default, the module path to the current Rust module will be used as the target, and the parent will be determined contextually.