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
