[][src]Macro tracing::span

macro_rules! span {
    (target: $target:expr, parent: $parent:expr, $lvl:expr, $name:expr) => { ... };
    (target: $target:expr, parent: $parent:expr, $lvl:expr, $name:expr, $($fields:tt)*) => { ... };
    (target: $target:expr, $lvl:expr, $name:expr, $($fields:tt)*) => { ... };
    (target: $target:expr, parent: $parent:expr, $lvl:expr, $name:expr) => { ... };
    (parent: $parent:expr, $lvl:expr,  $name:expr, $($fields:tt)*) => { ... };
    (parent: $parent:expr, $lvl:expr, $name:expr) => { ... };
    (target: $target:expr, $lvl:expr, $name:expr, $($fields:tt)*) => { ... };
    (target: $target:expr, $lvl:expr, $name:expr) => { ... };
    ($lvl:expr, $name:expr, $($fields:tt)*) => { ... };
    ($lvl:expr, $name:expr) => { ... };
}

Constructs a new span.

Examples

Creating a new span:

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:

This example deliberately fails to 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.