• Home
Name Date Size #Lines LOC

..--

src/12-May-2024-649396

CHANGELOG.mdD12-May-20241.3 KiB4932

Cargo.tomlD12-May-2024996 3731

LICENSED12-May-20241 KiB2622

README.mdD12-May-20243.9 KiB12289

README.md

1![Tracing — Structured, application-level diagnostics][splash]
2
3[splash]: https://raw.githubusercontent.com/tokio-rs/tracing/master/assets/splash.svg
4
5# tracing-serde
6
7An adapter for serializing [`tracing`] types using [`serde`].
8
9[![Documentation][docs-badge]][docs-url]
10[![Documentation (master)][docs-master-badge]][docs-master-url]
11
12[docs-badge]: https://docs.rs/tracing-serde/badge.svg
13[docs-url]: https://docs.rs/tracing-serde
14[docs-master-badge]: https://img.shields.io/badge/docs-master-blue
15[docs-master-url]: https://tracing-rs.netlify.com/tracing_serde
16
17## Overview
18
19[`tracing`] is a framework for instrumenting Rust programs to collect
20scoped, structured, and async-aware diagnostics.`tracing-serde` enables
21serializing `tracing` types using [`serde`].
22
23Traditional logging is based on human-readable text messages.
24`tracing` gives us machine-readable structured diagnostic
25information. This lets us interact with diagnostic data
26programmatically. With `tracing-serde`, you can implement a
27`Subscriber` to serialize your `tracing` types and make use of the
28existing ecosystem of `serde` serializers to talk with distributed
29tracing systems.
30
31Serializing diagnostic information allows us to do more with our logged
32values. For instance, when working with logging data in JSON gives us
33pretty-print when we're debugging in development and you can emit JSON
34and tracing data to monitor your services in production.
35
36The `tracing` crate provides the APIs necessary for instrumenting
37libraries and applications to emit trace data.
38
39*Compiler support: [requires `rustc` 1.49+][msrv]*
40
41[msrv]: #supported-rust-versions
42
43## Usage
44
45First, add this to your `Cargo.toml`:
46
47```toml
48[dependencies]
49tracing = "0.1"
50tracing-serde = "0.1"
51```
52
53Next, add this to your crate:
54
55```rust
56use tracing_serde::AsSerde;
57```
58
59Please read the [`tracing` documentation](https://docs.rs/tracing/latest/tracing/index.html)
60for more information on how to create trace data.
61
62This crate provides the `as_serde` function, via the `AsSerde` trait,
63which enables serializing the `Attributes`, `Event`, `Id`, `Metadata`,
64and `Record` `tracing` values.
65
66For the full example, please see the [examples](../examples) folder.
67
68Implement a `Subscriber` to format the serialization of `tracing`
69types how you'd like.
70
71```rust
72pub struct JsonSubscriber {
73    next_id: AtomicUsize, // you need to assign span IDs, so you need a counter
74}
75
76impl Subscriber for JsonSubscriber {
77
78    fn new_span(&self, attrs: &Attributes) -> Id {
79        let id = self.next_id.fetch_add(1, Ordering::Relaxed);
80        let id = Id::from_u64(id as u64);
81        let json = json!({
82        "new_span": {
83            "attributes": attrs.as_serde(),
84            "id": id.as_serde(),
85        }});
86        println!("{}", json);
87        id
88    }
89    // ...
90}
91```
92
93After you implement your `Subscriber`, you can use your `tracing`
94subscriber (`JsonSubscriber` in the above example) to record serialized
95trace data.
96
97## Supported Rust Versions
98
99Tracing is built against the latest stable release. The minimum supported
100version is 1.49. The current Tracing version is not guaranteed to build on Rust
101versions earlier than the minimum supported version.
102
103Tracing follows the same compiler support policies as the rest of the Tokio
104project. The current stable Rust compiler and the three most recent minor
105versions before it will always be supported. For example, if the current stable
106compiler version is 1.45, the minimum supported version will not be increased
107past 1.42, three minor versions prior. Increasing the minimum supported compiler
108version is not considered a semver breaking change as long as doing so complies
109with this policy.
110
111## License
112
113This project is licensed under the [MIT license](LICENSE).
114
115### Contribution
116
117Unless you explicitly state otherwise, any contribution intentionally submitted
118for inclusion in Tokio by you, shall be licensed as MIT, without any additional
119terms or conditions.
120
121[`tracing`]: https://crates.io/crates/tracing
122[`serde`]: https://crates.io/crates/serde