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
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130

# Filtering events

`emit` supports client-side filtering using a [`Filter`](https://docs.rs/emit/1.0.0/emit/trait.Filter.html).

## Setup

Filters are configured through the [`setup`](https://docs.rs/emit/1.0.0/emit/setup/fn.setup.html) function at the start of your application by calling [`emit_when`](https://docs.rs/emit/1.0.0/emit/setup/struct.Setup.html#method.emit_when):

```rust
# extern crate emit;
# extern crate emit_term;
fn main() {
    let rt = emit::setup()
        // This filter accepts any event with a level over warn
        .emit_when(emit::level::min_filter(emit::Level::Warn))
        .emit_to(emit_term::stdout())
        .init();

    // Your app code goes here

    rt.blocking_flush(std::time::Duration::from_secs(5));
}
```

Filters can be combined with [`and_when`](https://docs.rs/emit/1.0.0/emit/trait.Filter.html#method.and_when) and [`or_when`](https://docs.rs/emit/1.0.0/emit/trait.Filter.html#method.or_when):

```rust
# extern crate emit;
use emit::Filter;

# extern crate emit_term;
fn main() {
    let rt = emit::setup()
        // This filter accepts any event with a level over warn or where the module path is `my_module`
        .emit_when(emit::level::min_filter(emit::Level::Warn)
            .or_when(emit::filter::from_fn(|evt| evt.mdl() == "my_module"))
        )
        .emit_to(emit_term::stdout())
        .init();

    // Your app code goes here

    rt.blocking_flush(std::time::Duration::from_secs(5));
}
```

## Wrapping emitters in filters

You can also wrap an emitter in [`emit_to`](https://docs.rs/emit/1.0.0/emit/setup/struct.Setup.html#method.emit_to) in a filter:

```rust
# extern crate emit;
# extern crate emit_term;
use emit::Emitter;

fn main() {
    let rt = emit::setup()
        // Wrap the emitter in a filter instead of setting it independently
        .emit_to(emit_term::stdout()
            .wrap_emitter(emit::emitter::wrapping::from_filter(
                emit::level::min_filter(emit::Level::Warn))
            )
        )
        .init();

    // Your app code goes here

    rt.blocking_flush(std::time::Duration::from_secs(5));
}
```

Wrapping an emitter in a filter is not the same as providing an emitter and filter independently.

When you use `emit_when`, the filter may be by-passed using the `when` [control parameter](./reference/control-parameters.md) on the [`emit!`](https://docs.rs/emit/1.0.0/emit/macro.emit.html) or [`#[span]`](https://docs.rs/emit/1.0.0/emit/attr.span.html) macros to emit an event even if the filter wouldn't match it. However, the filter specified by `emit_when` doesn't allow you to filter differently if you specify multiple emitters.

When you wrap an emitter in a filter, the filter cannot by by-passed, but each emitter can use its own filter.

Also see [Wrapping emitters](./emitting-events.md#wrapping-emitters) for more details on wrappings.

## Filtering by level

You can use the [`level::min_filter`](https://docs.rs/emit/1.0.0/emit/level/fn.min_filter.html) function to create a filter that matches events based on their level:

```rust
# extern crate emit;
# extern crate emit_term;
fn main() {
    let rt = emit::setup()
        // This filter accepts any event with a level over warn
        .emit_when(emit::level::min_filter(emit::Level::Warn))
        .emit_to(emit_term::stdout())
        .init();

    // Your app code goes here

    rt.blocking_flush(std::time::Duration::from_secs(5));
}
```

See [the crate docs](https://docs.rs/emit/1.0.0/emit/level/struct.MinLevelFilter.html) for more details.

## Filtering by module

You can use the [`level::min_by_path_filter`](https://docs.rs/emit/1.0.0/emit/level/fn.min_by_path_filter.html) function to create a filter that matches events based on their module path and level:

```rust
# extern crate emit;
# extern crate emit_term;
fn main() {
    let rt = emit::setup()
        // This filter accepts any event with a level over warn
        .emit_when(emit::level::min_by_path_filter([
            (emit::path!("noisy_module"), emit::Level::Warn),
            (emit::path!("noisy_module::important_sub_module"), emit::Level::Info),
            (emit::path!("important_module"), emit::Level::Debug),
        ]))
        .emit_to(emit_term::stdout())
        .init();

    // Your app code goes here

    rt.blocking_flush(std::time::Duration::from_secs(5));
}
```

See [the crate docs](https://docs.rs/emit/1.0.0/emit/level/struct.MinLevelPathMap.html) for more details.

## Filtering spans

When you use the [`#[span]`](https://docs.rs/emit/1.0.0/emit/attr.span.html) macro, `emit` will apply the filter to determine whether the span should be created. If the span doesn't match the filter then no trace context will be generated for it. This isn't the same as trace sampling. `emit` doesn't have the concept of a trace that is not recorded. See [Sampling and filtering traces](./producing-events/tracing/sampling.md) for more details.