emit_macros 1.20.1

Internal proc macro crate for emit.
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
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115

See the [`SpanGuard::new`](https://docs.rs/emit/1.20.1/emit/span/struct.SpanGuard.html#method.new) for details on starting and completing the returned span.

Also see [the guide](https://emit-rs.io/producing-events/tracing/manual-span-creation.html) for more details on manual span construction.

# Examples

## Creating spans

Note that [`macro@debug_span_guard`], [`macro@info_span_guard`], [`macro@warn_span_guard`], and [`macro@error_span_guard`] use the same syntax.

Creating a span with captured properties in the template:

```ignore
let x = 42;
let y = true;

let (span, guard) = emit::span_guard!("got {x} and {y}");
```

Creating a span with captured properties after the template:

```ignore
let x = 42;
let y = true;

let (span, guard) = emit::span_guard!("something of note", x, y);
```

Specifying control parameters before the template (in this example, `mdl`):

```ignore
let (span, guard) = emit::span_guard!(mdl: emit::path!("a::b"), "something of note");
```

## Entering the created span

Once a span is created, a block of code can be executed within it:

```ignore
let (mut span, guard) = emit::span_guard!("manual span");

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

    // Your code goes here
})
```

The call to `span.start()` **must** be within the call to `guard.call` (or the future passed to `guard.in_future`) otherwise the span will complete early, without its ambient context.

# Syntax

```text
(control_param),* template_literal, (property),*
```

where

- `control_param`: A Rust field-value with a pre-determined identifier (see below).
- `template_literal`: A template string literal.
- `property`: A Rust field-value for a property to capture.

# Control parameters

This macro accepts the following optional control parameters:

| name        | type                          | description                                                                                                                                                                                                                                                    |
|-------------|-------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `rt`        | `impl emit::runtime::Runtime` | The runtime to emit the event through.                                                                                                                                                                                                                         |
| `mdl`       | `impl Into<emit::Path>`       | The module the event belongs to. If unspecified the current module path is used.                                                                                                                                                                               |
| `when`      | `impl emit::Filter`           | A filter to use instead of the one configured on the runtime.                                                                                                                                                                                                  |
| `evt_props` | `impl emit::Props`            | A set of properties to attach to the span guard that will appear on the emitted span event, but not pushed to the ambient context. The type that will appear on the `SpanGuard` is an anonymous wrapper that dereferences to the concrete type of `evt_props`. |
| `panic_lvl` | `str` or `emit::Level`        | Detect whether the function panics and use the given level if it does.                                                                                                                                                                                         |

# Template literals

Templates are text literals that include regular text with _holes_. A hole is a point in the template where a property should be interpolated in.

- `template_literal`: `"` `(text | hole)*` `"`
- `text`: A fragment of plain text where `{` are escaped as `{{` and `}` are escaped as `}}`.
- `hole`: `{` `property` `}`
- `property`: A Rust field-value expression.

The following are all examples of templates:

```text
"some text"
 ├───────┘
 text
```

```text
"some text and {x}"
 ├────────────┘ │
 text           property
```

```text
"some {{text}} and {x: 42} and {y}"
 ├────────────────┘ ├───┘ └───┤ │
 text               property  │ property
                              text
```

See [the guide](https://emit-rs.io/reference/templates.html) for more details and examples of templates.

# Properties

Properties that appear within the template or after it are added to the emitted event. The identifier of the property is its key. Property capturing can be adjusted through the `as_*` attribute macros.

See [the guide](https://emit-rs.io/reference/property-capturing.html) for more details on property capturing.

# Returns

A `(SpanGuard, Frame<impl Ctxt>)`.