ez_tracing 0.1.0

Tracing, made easy
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

# ez_tracing

Tracing, made easy.

Do you want to structure debug information better than what `dbg!` gives you ?\
Do you want to see what exactly happens in a multi-threaded program ?\
Are you lost with the different crates that could solve these problem in a similar but not quite
the same way, in the Rust ecosystem ?

Then this crate is for you!

# Overview

This crate provides a convinient way to setup logs and trace, using an easily
configurable [Tracer][Code Tracer] struct.

## Features

- `verbosity-*`: Compile time choice of the [Console][Code Console] default verbosity level.
  If multiple are choosed, this will select the lowest verbosity level.
  IE: `Error` before `Warn`.
  If none are chosen, this will default to `Warn`.

- `bon`: Use [bon builders][Bon] to create structs.
  This is a nicer interface than using raw strucs, but it increases compile time.
- `chrono`: Add the time as a prefix to the [log files name][Code LogFile].
- `clap`: Enable configuring the [Console][Code Console] from the CLI, using the [clap library][Clap].
  - `clap-log-file`: Enable configuring the [log files][Code LogFile] from the CLI.
- `serde`: Enable creating [Tracer][Code Tracer] and friends usings any [Serde] compatible de/serializer.
  This can be useful for configuration files.
- `telemetry`: Enables exporting traces to an [OpenTelemetry] compatible server.
  - `telemetry-auth`: Connecting to an [OpenTelemetry] compatbile server that is
    protected by an authentication method.
- `tokio`: Enable exporting traces to the [Tokio console].
  You will need to add `RUSTFLAGS="--cfg tokio_unstable"` to your application during build time.

## Examples

```rust
use ez_tracing::{errors::EErrorTracer, tracer::Tracer};

/// Log to `stdout` and `stderr` at the default `Warn` level
fn main() -> Result<(), EErrorTracer> {
    let _guard = Tracer::default().try_setup_tracer()?;
    # Ok(())
}
```

For a more thorough showcase, check out the `tests` folder, which also serves as examples.

## Known issues

There is a known bug ([#3309](https://github.com/tokio-rs/tracing/issues/3309)) in the `tracing`
crates that makes the `instrument` macro unreachable after a re-export.\
To fix this, you can add, to your top `lib.rs` file:

```rust
use ez_tracing::tracing::*;
extern crate self as tracing;
```

## License

[Apache2](LICENSE-APACHE) or [MIT](LICENSE-MIT), at your option.

[Code Console]: ./src/console.rs
[Code Tracer]: ./src/tracer.rs
[Code LogFile]: ./src/log_file.rs
[Bon]: https://github.com/elastio/bon
[Clap]: https://github.com/clap-rs/clap
[OpenTelemetry]: https://github.com/open-telemetry/opentelemetry-rust
[Serde]: https://github.com/serde-rs/serde
[Tracing]: https://github.com/tokio-rs/tracing
[Tokio console]: https://github.com/tokio-rs/console