ari-subscriber 0.0.2

Async Executor Instrumentation Observability Utility A tracing subscriber layer that outputs Tokio's tracing instrumentation to the terminal in a format conducive to debugging.
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

# Async Runtime Instrumentation Subscriber

The *Async Runtime Instrumentation Subscriber* (`ari-subscriber`) is a [`tracing-subscriber`]
optimized for visually debugging Tokio tracing instrumentation.

This crate provides a [`Layer`] which writes [`tracing`] information to `stdout`. It colorizes
the traces that result from the tracing instrumentation in Tokio to make identifying them
easier.

# Usage

This example will set up a formatting [`tracing_subscriber::Layer`] which is then added to the
registry. The output from the task spawned afterwards will be seen in `stdout`.

```rust
use tracing_subscriber::prelude::*;

#[tokio::main]
async fn main() {
    let layer = ari_subscriber::layer();

    tracing_subscriber::registry().with(layer).init();

    tokio::spawn(async {
        tokio::time::sleep(std::time::Duration::from_millis(100)).await;
    })
    .await
    .unwrap();
}
````

A common use case is to use `ari-subscriber` together with the [`console-subscriber`], which
aggregates the same Tokio tracing instrumentation to be visualized in Tokio Console.

```rust
use tracing_subscriber::prelude::*;

#[tokio::main]
async fn main() {
    let fmt_layer = ari_subscriber::layer();
    let console_layer = console_subscriber::spawn();

    tracing_subscriber::registry()
        .with(fmt_layer)
        .with(console_layer)
        .init();

    tokio::spawn(async {
        tokio::time::sleep(std::time::Duration::from_millis(100)).await;
    })
    .await
    .unwrap();
}
````

 ## Example output
 
 The beginning of the output of the above program would be:
 
 <pre style="background-color: #000; color: #fff; overflow-x: auto;">
 <span style='opacity:0.67'><b><span style='color:#aaa'>2023-11-28</span></b></span><span style='opacity:0.67'>T<b><span style='color:#aaa'>10:06:44</span></b></span><span style='opacity:0.67'>.746508Z</span> <span style='color:#9d4edd'>TRACE</span> <span style='color:#489e6c'>runtime.spawn[<b><span style='color:#5aba84'>1</span></b></span><span style='color:#489e6c'>]{kind=task, task.name=, task.id=18, loc.file=&quot;examples/tokio-task.rs&quot;, loc.line=14, loc.col=5}</span> <b><u><span style='color:#5aba84'>new</span></u></b>
 <span style='opacity:0.67'><b><span style='color:#aaa'>2023-11-28</span></b></span><span style='opacity:0.67'>T<b><span style='color:#aaa'>10:06:44</span></b></span><span style='opacity:0.67'>.747110Z</span> <span style='color:#9d4edd'>TRACE</span> <span style='color:#489e6c'>runtime.spawn[<b><span style='color:#5aba84'>1</span></b></span><span style='color:#489e6c'>]{kind=task, task.name=, task.id=18, loc.file=&quot;examples/tokio-task.rs&quot;, loc.line=14, loc.col=5}</span> <b><u><span style='color:#5aba84'>enter</span></u></b>
 <span style='opacity:0.67'><b><span style='color:#aaa'>2023-11-28</span></b></span><span style='opacity:0.67'>T<b><span style='color:#aaa'>10:06:44</span></b></span><span style='opacity:0.67'>.747340Z</span> <span style='color:#9d4edd'>TRACE</span> <span style='color:#489e6c'>runtime.spawn[<b><span style='color:#5aba84'>1</span></b></span><span style='color:#489e6c'>]{kind=task, task.name=, task.id=18, loc.file=&quot;examples/tokio-task.rs&quot;, loc.line=14, loc.col=5}</span> <span style='color:#ba5a57'>runtime.resource[<b><span style='color:#df5853'>274877906945</span></b></span><span style='color:#ba5a57'>]{concrete_type=&quot;Sleep&quot;, kind=&quot;timer&quot;, loc.file=&quot;examples/tokio-task.rs&quot;, loc.line=15, loc.col=9}</span> <b><u><span style='color:#df5853'>new</span></u></b>
 <span style='opacity:0.67'><b><span style='color:#aaa'>2023-11-28</span></b></span><span style='opacity:0.67'>T<b><span style='color:#aaa'>10:06:44</span></b></span><span style='opacity:0.67'>.747539Z</span> <span style='color:#9d4edd'>TRACE</span> <span style='color:#489e6c'>runtime.spawn[<b><span style='color:#5aba84'>1</span></b></span><span style='color:#489e6c'>]{kind=task, task.name=, task.id=18, loc.file=&quot;examples/tokio-task.rs&quot;, loc.line=14, loc.col=5}</span> <span style='color:#ba5a57'>runtime.resource[<b><span style='color:#df5853'>274877906945</span></b></span><span style='color:#ba5a57'>]{concrete_type=&quot;Sleep&quot;, kind=&quot;timer&quot;, loc.file=&quot;examples/tokio-task.rs&quot;, loc.line=15, loc.col=9}</span> <b><u><span style='color:#df5853'>enter</span></u></b>
 <span style='opacity:0.67'><b><span style='color:#aaa'>2023-11-28</span></b></span><span style='opacity:0.67'>T<b><span style='color:#aaa'>10:06:44</span></b></span><span style='opacity:0.67'>.747683Z</span> <span style='color:#9d4edd'>TRACE</span> <span style='color:#489e6c'>runtime.spawn[<b><span style='color:#5aba84'>1</span></b></span><span style='color:#489e6c'>]{kind=task, task.name=, task.id=18, loc.file=&quot;examples/tokio-task.rs&quot;, loc.line=14, loc.col=5}</span> <span style='color:#ba5a57'>runtime.resource[<b><span style='color:#df5853'>274877906945</span></b></span><span style='color:#ba5a57'>]{concrete_type=&quot;Sleep&quot;, kind=&quot;timer&quot;, loc.file=&quot;examples/tokio-task.rs&quot;, loc.line=15, loc.col=9}</span> <b><span style='color:#ff4d6d'>runtime::resource::state_update</span></b>: <span style='color:#c9184a'>duration=101, duration.unit=&quot;ms&quot;, duration.op=&quot;override&quot;</span>
 <span style='opacity:0.67'><b><span style='color:#aaa'>2023-11-28</span></b></span><span style='opacity:0.67'>T<b><span style='color:#aaa'>10:06:44</span></b></span><span style='opacity:0.67'>.747854Z</span> <span style='color:#9d4edd'>TRACE</span> <span style='color:#489e6c'>runtime.spawn[<b><span style='color:#5aba84'>1</span></b></span><span style='color:#489e6c'>]{kind=task, task.name=, task.id=18, loc.file=&quot;examples/tokio-task.rs&quot;, loc.line=14, loc.col=5}</span> <span style='color:#ba5a57'>runtime.resource[<b><span style='color:#df5853'>274877906945</span></b></span><span style='color:#ba5a57'>]{concrete_type=&quot;Sleep&quot;, kind=&quot;timer&quot;, loc.file=&quot;examples/tokio-task.rs&quot;, loc.line=15, loc.col=9}</span> <span style='color:#5c8dce'>runtime.resource.async_op[<b><span style='color:#508ee3'>274877906946</span></b></span><span style='color:#5c8dce'>]{source=&quot;Sleep::new_timeout&quot;}</span> <b><u><span style='color:#508ee3'>new</span></u></b>
 <span style='opacity:0.67'><b><span style='color:#aaa'>2023-11-28</span></b></span><span style='opacity:0.67'>T<b><span style='color:#aaa'>10:06:44</span></b></span><span style='opacity:0.67'>.747991Z</span> <span style='color:#9d4edd'>TRACE</span> <span style='color:#489e6c'>runtime.spawn[<b><span style='color:#5aba84'>1</span></b></span><span style='color:#489e6c'>]{kind=task, task.name=, task.id=18, loc.file=&quot;examples/tokio-task.rs&quot;, loc.line=14, loc.col=5}</span> <span style='color:#ba5a57'>runtime.resource[<b><span style='color:#df5853'>274877906945</span></b></span><span style='color:#ba5a57'>]{concrete_type=&quot;Sleep&quot;, kind=&quot;timer&quot;, loc.file=&quot;examples/tokio-task.rs&quot;, loc.line=15, loc.col=9}</span> <b><u><span style='color:#df5853'>exit</span></u></b>
 <span style='opacity:0.67'><b><span style='color:#aaa'>2023-11-28</span></b></span><span style='opacity:0.67'>T<b><span style='color:#aaa'>10:06:44</span></b></span><span style='opacity:0.67'>.748118Z</span> <span style='color:#9d4edd'>TRACE</span> <span style='color:#489e6c'>runtime.spawn[<b><span style='color:#5aba84'>1</span></b></span><span style='color:#489e6c'>]{kind=task, task.name=, task.id=18, loc.file=&quot;examples/tokio-task.rs&quot;, loc.line=14, loc.col=5}</span> <span style='color:#ba5a57'>runtime.resource[<b><span style='color:#df5853'>274877906945</span></b></span><span style='color:#ba5a57'>]{concrete_type=&quot;Sleep&quot;, kind=&quot;timer&quot;, loc.file=&quot;examples/tokio-task.rs&quot;, loc.line=15, loc.col=9}</span> <span style='color:#5c8dce'>runtime.resource.async_op[<b><span style='color:#508ee3'>274877906946</span></b></span><span style='color:#5c8dce'>]{source=&quot;Sleep::new_timeout&quot;}</span> <b><u><span style='color:#508ee3'>enter</span></u></b>
 <span style='opacity:0.67'><b><span style='color:#aaa'>2023-11-28</span></b></span><span style='opacity:0.67'>T<b><span style='color:#aaa'>10:06:44</span></b></span><span style='opacity:0.67'>.748196Z</span> <span style='color:#9d4edd'>TRACE</span> <span style='color:#489e6c'>runtime.spawn[<b><span style='color:#5aba84'>1</span></b></span><span style='color:#489e6c'>]{kind=task, task.name=, task.id=18, loc.file=&quot;examples/tokio-task.rs&quot;, loc.line=14, loc.col=5}</span> <span style='color:#ba5a57'>runtime.resource[<b><span style='color:#df5853'>274877906945</span></b></span><span style='color:#ba5a57'>]{concrete_type=&quot;Sleep&quot;, kind=&quot;timer&quot;, loc.file=&quot;examples/tokio-task.rs&quot;, loc.line=15, loc.col=9}</span> <span style='color:#5c8dce'>runtime.resource.async_op[<b><span style='color:#508ee3'>274877906946</span></b></span><span style='color:#5c8dce'>]{source=&quot;Sleep::new_timeout&quot;}</span> <span style='color:#e5e44d'>runtime.resource.async_op.poll[<b><span style='color:#f5f466'>274877906947</span></b></span><span style='color:#e5e44d'>]{}</span> <b><u><span style='color:#f5f466'>new</span></u></b>
 </pre>

## Comparison with `tracing-subscriber`

`ari-subscriber` is built on top of `tracing-subscriber` and uses its registry (as do the majority
of `tracing` subscribers). It offers an alternative to the [`fmt::Subscriber`] and underlying
[`fmt::Layer`] in that crate.

If you are in doubt about which format subscriber to use, pick the one from
`tracing-subscriber`. It is more flexible and without a doubt, much more performant.

You would only use the `ari-subscriber` format [`Layer`] if you have a specific need to visualize
the tracing instrumentation built into Tokio.

## Supported Rust Versions

`ari-subscriber` is built against the latest stable release. The minimum supported version is
1.65. The current version of `ari-subscriber` is not guaranteed to build on Rust versions earlier
than the minimum supported version.

## License

This project is licensed under the [MIT license].

[MIT license]: https://github.com/hds/ari-subscriber/blob/main/LICENSE

### Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion
in `ari-subscriber` by you, shall be licensed as MIT, without any additional terms or conditions.

[`Layer`]: src/layer.rs
[`tracing`]: https://docs.rs/tracing/0.1.40/tracing/
[`console-subscriber`]: https://docs.rs/console-subscriber/latest/console_subscriber/
[`tracing-subscriber`]: tracing_subscriber
[`tracing_subscriber::Layer`]: https://docs.rs/tracing-subscriber/0.3.18/tracing_subscriber/layer/trait.Layer.html
[`fmt::Layer`]: https://docs.rs/tracing-subscriber/0.3.18/tracing_subscriber/fmt/struct.Layer.html
[`fmt::Subscriber`]: https://docs.rs/tracing-subscriber/0.3.18/tracing_subscriber/fmt/struct.Subscriber.html