Macro log

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

Export a log message at the specified level.

Syntax

The macro accepts the following syntax:

log!(
   parent: tracing::Span, // optional, can emit this
   tracing::Level,        // required, see `info!` and variants for convenience
   "format string",       // required, must be a format string accepted by `format!()`
   attr = value,          // optional attributes, can be repeated
   ..                     // as many additional arg = 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

use tracing::Level;

// Root span
let root_span = logfire::span!("Root span");

// Log with attributes x and y
logfire::log!(parent: &root_span, Level::INFO, "Child log", x = 42, y = "hello");
// or
logfire::info!(parent: &root_span, "Child log", x = 42, y = "hello");

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

    // Debug-level child log
    logfire::log!(Level::DEBUG, "Debugging", x = 42, y = "hello");
    // or
    logfire::debug!("Debugging", x = 42, y = "hello");
});

// With x included in the formatted message but not as an attribute
let x = 42;
logfire::log!(Level::INFO, "Log with x = {x}, y = {y}", y = "hello");
// or
logfire::info!("Log 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.
logfire::log!(Level::INFO, "Log with x = {x}, y = {y}", y = "hello", foo.bar = 42);
// or
logfire::info!("Log with x = {x}, y = {y}", y = "hello", foo.bar = 42);