Attaching properties to spans

Properties added to the span macros are added to an ambient context and automatically included on any events emitted within that operation:

#![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));

    emit::emit!("waiting a bit longer");

    std::thread::sleep(std::time::Duration::from_millis(sleep_ms));
}
}

Event {
    mdl: "my_app",
    tpl: "waiting a bit longer",
    extent: Some(
        "2024-04-27T22:47:34.780288000Z",
    ),
    props: {
        "trace_id": d2a5e592546010570472ac6e6457c086,
        "sleep_ms": 1200,
        "span_id": ee9fde093b6efd78,
    },
}
Event {
    mdl: "my_app",
    tpl: "wait a bit",
    extent: Some(
        "2024-04-27T22:47:33.574839000Z".."2024-04-27T22:47:35.985844000Z",
    ),
    props: {
        "evt_kind": span,
        "span_name": "wait a bit",
        "trace_id": d2a5e592546010570472ac6e6457c086,
        "sleep_ms": 1200,
        "span_id": ee9fde093b6efd78,
    },
}

Any operations started within a span will inherit its identifiers:

#![allow(unused)]
fn main() {
extern crate emit;
#[emit::span("outer span", sleep_ms)]
fn outer_span(sleep_ms: u64) {
    std::thread::sleep(std::time::Duration::from_millis(sleep_ms));

    inner_span(sleep_ms / 2);
}

#[emit::span("inner span", sleep_ms)]
fn inner_span(sleep_ms: u64) {
    std::thread::sleep(std::time::Duration::from_millis(sleep_ms));
}
}

Event {
    mdl: "my_app",
    tpl: "inner span",
    extent: Some(
        "2024-04-27T22:50:50.385706000Z".."2024-04-27T22:50:50.994509000Z",
    ),
    props: {
        "evt_kind": span,
        "span_name": "inner span",
        "trace_id": 12b2fde225aebfa6758ede9cac81bf4d,
        "span_parent": 23995f85b4610391,
        "sleep_ms": 600,
        "span_id": fc8ed8f3a980609c,
    },
}
Event {
    mdl: "my_app",
    tpl: "outer span",
    extent: Some(
        "2024-04-27T22:50:49.180025000Z".."2024-04-27T22:50:50.994797000Z",
    ),
    props: {
        "evt_kind": span,
        "span_name": "outer span",
        "sleep_ms": 1200,
        "span_id": 23995f85b4610391,
        "trace_id": 12b2fde225aebfa6758ede9cac81bf4d,
    },
}

Notice the span_parent of inner_span is the same as the span_id of outer_span. That’s because inner_span was called within the execution of outer_span.

Adding properties to a span as it runs

If you bind the implicit span guard created for an instrumented function to an identifier, you can use it in the body of the function to interact with the span before it completes. See Manual span creation for more details.

With a SpanGuard, you can attach additional properties collection to the span:

#![allow(unused)]
fn main() {
extern crate emit;
use std::collections::HashMap;
// This example uses a `HashMap` to store additional properties to include
#[emit::span(guard: span, evt_props: HashMap::new(), "checking a value", i)]
fn check(i: i32) {
    if i > 4 {
        // The type of the span's properties derefence to `HashMap`, so we can insert into them
        span.props_mut().map(|props| props.insert("is_big", true));
    }

    // At this point `span` will be dropped
    // It may or may not carry `is_big`
}
}

Event {
    mdl: "my_app",
    tpl: "checking a value",
    extent: Some(
        "2024-04-27T22:50:49.180025000Z".."2024-04-27T22:50:50.994797000Z",
    ),
    props: {
        "evt_kind": span,
        "span_name": "checking a value",
        "is_big": true,
        "i": 5,
        "span_id": 23995f85b4610391,
        "trace_id": 12b2fde225aebfa6758ede9cac81bf4d,
    },
}

Attaching additional properties to the span guard is preferrable to adding them through the span’s completion. When they’re on the guard they’ll be used even if the function panics.

Visibility of properties on spans

Properties on spans have two visibility levels:

Shared: Added to the ambient context and present on all child events. Properties you add to the #[span] template are shared.
Private: Added to the SpanGuard and only present on the span event itself. Properties you add through the evt_props control parameter, and subsequently through the SpanGuard are private.

#![allow(unused)]
fn main() {
extern crate emit;
#[emit::span(
    guard: span,
    evt_props: emit::props! {
        private_1: i,
    },
    "checking {public_1: i}",
    public_2: i,
)]
fn check(i: i32) {
    let _span = span.push_prop("private_2", i);

    // Your code goes here
}
}

This means you only want to include properties in your #[span] template that are ambiently useful, because they’ll also appear on all child events.

To make additional properties ambiently available during the execution of a span, see Context.

Capturing complex values

Properties aren’t limited to strings; they can be arbitrarily complex structured values. See the following sections and Value data model for more details.

Using `fmt::Debug`

If you want to log a type that implements Debug, you can apply the #[as_debug] attribute to it to capture it with its debug format:

#![allow(unused)]
fn main() {
extern crate emit;
#[derive(Debug)]
struct User<'a> {
    name: &'a str,
}

#[emit::span("greet {user}", #[emit::as_debug] user)]
fn greet(user: &User) {
    println!("Hello, {}", user.name);
}
}

Using `serde::Serialize`

If you want to log a type that implements Serialize, you can apply the #[as_serde] attribute to it to capture it as a structured value:

#![allow(unused)]
fn main() {
extern crate emit;
#[macro_use] extern crate serde;
#[derive(Serialize)]
struct User<'a> {
    name: &'a str,
}

#[emit::span("greet {user}", #[emit::as_serde] user)]
fn greet(user: &User) {
    println!("Hello, {}", user.name);
}
}

Keyboard shortcuts

emit