Span creation

emit’s tracing infrastructure is largely concerned with the lifecycle of spans. At the start of a traced operation, a span is created as a SpanGuard, carrying the start time and properties for the eventual Span event that will be emitted at the end.

Spans can be created in a number of ways, depending on the needs of the application.

Using macros

The standard method to create a span is using the #[span] macro on a function definition:

#![allow(unused)]
fn main() {
extern crate emit;
#[emit::span("wait a bit", sleep_ms)]
fn wait_a_bit(sleep_ms: u64) {
    std::thread::sleep(std::time::Duration::from_millis(sleep_ms))
}

wait_a_bit(1200);
}

The same attribute works for async functions too.

The #[span] macro creates an implicit SpanGuard that will be completed when the annotated function returns. You can also use and complete this guard manually. See Manual span completion for details.

Manually

Some applications and frameworks have operation lifecycles that outlive a single function call. In these cases, you can create spans manually using the span_guard! attribute:

#![allow(unused)]
fn main() {
extern crate emit;
let (mut span, frame) = emit::span_guard!("manual span");

frame.call(move || {
    span.start();

    // Your code goes here
})
}

The span type in the above example is a SpanGuard that will complete automatically when it goes out of scope. You can also use and complete this guard manually. See Manual span completion for details.

There are other ways to manually create spans too. See Manual span creation for details.