emit 1.0.0

Developer-first diagnostics for Rust applications.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98

# Ambient context

`emit` supports enriching events automatically with properties from the ambient environment.

## Using the `#[span]` macro

The most straightforward way to add ambient context is using the [`#[span]`](https://docs.rs/emit/1.0.0/emit/attr.span.html) macro. Any properties captured by the span will also be added to events emitted during its execution:

```rust
# extern crate emit;
#[emit::span("greet {user}", lang)]
fn greet(user: &str, lang: &str) {
    match lang {
        "el" => emit::emit!("Γεια σου, {user}"),
        "en" => emit::emit!("Hello, {user}"),
        "eo" => emit::emit!("Saluton, {user}"),
# /*
        ..
# */    _ => (),
    }
}

greet("Rust", "eo");
```

```text
Event {
    mdl: "my_app",
    tpl: "Saluton, {user}",
    extent: Some(
        "2024-10-02T20:53:29.580999000Z",
    ),
    props: {
        "user": "Rust",
        "span_id": b26bfe938b77eb19,
        "lang": "eo",
        "user": "Rust",
        "trace_id": 7fc2efc824915dc180c29a79af358e78,
    },
}
```

Note the presence of the `lang` property on the events produced by `emit!`. They appear because they're added to the ambient context by the `#[span]` attribute on `greet()`.

See [Tracing](../tracing.md) for more details.

## Manually

Ambient context can be worked with directly. `emit` stores its ambient context in an implementation of the [`Ctxt`](https://docs.rs/emit/1.0.0/emit/trait.Ctxt.html) trait. Properties in the ambient context can be added or removed using [`Frame`s](https://docs.rs/emit/1.0.0/emit/frame/struct.Frame.html). You may want to work with context directly when you're not trying to produce spans in a distributed trace, or when your application doesn't have a single point where attributes could be applied to manipulate ambient context.

When converted to use ambient context manually, the previous example looks like this:

```rust
# extern crate emit;
fn greet(user: &str, lang: &str) {
    // Get a frame over the amient context that pushes the `lang` property
    let mut frame = emit::Frame::push(
        emit::ctxt(),
        emit::props! {
            lang,
        },
    );

    // Make the frame active
    // While this guard is in scope the `lang` property will be present
    // When this guard is dropped the `lang` property will be removed
    // Frames may be entered and exited multiple times
    let _guard = frame.enter();

    // The rest of the function proceeds as normal
    match lang {
        "el" => emit::emit!("Γεια σου, {user}"),
        "en" => emit::emit!("Hello, {user}"),
        "eo" => emit::emit!("Saluton, {user}"),
# /*
        ..
# */     _ => (),
    }
}

greet("Rust", "eo");
```

```text
Event {
    mdl: "my_app",
    tpl: "Saluton, {user}",
    extent: Some(
        "2024-10-02T21:01:50.534810000Z",
    ),
    props: {
        "user": "Rust",
        "lang": "eo",
    },
}
```

When using ambient context manually, it's important that frames are treated like a stack. They need to be exited in the opposite order they were entered in.