Macro span

macro_rules! span {
    (parent: $parent:expr, level: $level:expr, $format:expr $(, $($path:ident).+ = $value:expr)* $(,)?) => { ... };
    (parent: $parent:expr, $format:expr $(, $($path:ident).+ = $value:expr)* $(,)?) => { ... };
    (level: $level:expr, $format:expr $(, $($path:ident).+ = $value:expr)* $(,)?) => { ... };
    ($format:expr $(, $($path:ident).+ = $value:expr)* $(,)?) => { ... };
}

Create a new Span. This macro is a simplified version of tracing::span! which accepts a smaller set of possible arguments and syntaxes.

In exchange, the macro automatically adds metadata which leads the span and its fields to present nicely in the Logfire UI.

Syntax

The macro accepts the following syntax:

span!(
   parent: tracing::Span, // optional, can emit this
   level: tracing::Level, // optional
   "format string",       // required, must be a format string accepted by `format!()`
   attr = value,          // optional attributes, can be repeated
   ..                     // as many additional attr = value pairs as desired
)

Attributes

The attr = value pairs are captured as attributes on the span.

dotted.name = value is also supported (and encouraged by Opentelemetry) to namespace attributes. However, dotted names are not supported in Rust format strings.

Formatting

The format string only accepts arguments by name. These can either be explicitly passed to span! as an attribute or captured from the surrounding scope by the macro. If captured from the surrounding scope, they will only be used as a format string and not exported as attributes.

Examples

// Span without any arguments
let root_span = logfire::span!("Root span");

// Span with attributes x and y
let span = logfire::span!(parent: &root_span, "Child span", x = 42, y = "hello");

// Typically a span will be "entered" to set the parent implicitly
root_span.in_scope(|| {
    // This span will be a child of root_span
    let child_span = logfire::span!("Nested span", x = 42, y = "hello");

    // Debug-level child span
    let debug_span = logfire::span!(level: tracing::Level::DEBUG, "Debugging", x = 42, y = "hello");
});

// With x included in the formatted message but not as an attribute
let x = 42;
let span = logfire::span!("Span with x = {x}, y = {y}", y = "hello");

// Attributes can either be a single name or a dotted.name
// `dotted.name` is not available in the format string.
let span = logfire::span!("Span with x = {x}, y = {y}", y = "hello", foo.bar = 42);