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
#![allow(clippy::needless_doctest_main)] //! # A Bunyan formatter for [`tracing`] //! //! `tracing-bunyan-formatter` provides two [`Layer`]s implementation to be used on top of //! a [`tracing`] [`Subscriber`]: //! - [`JsonStorageLayer`], to attach contextual information to spans for ease of consumption by //! downstream [`Layer`]s, via [`JsonStorage`] and [`Span`]'s [`extensions`](https://docs.rs/tracing-subscriber/0.2.5/tracing_subscriber/registry/struct.ExtensionsMut.html); //! - [`BunyanFormattingLayer`]`, which emits a [bunyan](https://github.com/trentm/node-bunyan)-compatible formatted record upon entering a span, //! existing a span and event creation. //! //! **Important**: each span will inherit all fields and properties attached to its parent - this is //! currently not the behaviour provided by [`tracing_subscriber::fmt::Layer`](https://docs.rs/tracing-subscriber/0.2.5/tracing_subscriber/fmt/struct.Layer.html). //! //! ## Example //! //! ```rust //! use tracing_bunyan_formatter::{BunyanFormattingLayer, JsonStorageLayer}; //! use tracing::instrument; //! use tracing::info; //! use tracing_subscriber::Registry; //! use tracing_subscriber::layer::SubscriberExt; //! //! #[instrument] //! pub fn a_unit_of_work(first_parameter: u64) { //! for i in 0..2 { //! a_sub_unit_of_work(i); //! } //! info!(excited = "true", "Tracing is quite cool!"); //! } //! //! #[instrument] //! pub fn a_sub_unit_of_work(sub_parameter: u64) { //! info!("Events have the full context of their parent span!"); //! } //! //! fn main() { //! let formatting_layer = BunyanFormattingLayer::new("tracing_demo".into(), std::io::stdout); //! let subscriber = Registry::default() //! .with(JsonStorageLayer) //! .with(formatting_layer); //! tracing::subscriber::set_global_default(subscriber).unwrap(); //! //! info!("Orphan event without a parent span"); //! a_unit_of_work(2); //! } //! ``` //! //! ## Console output //! //! <div> //! <img src="https://raw.githubusercontent.com/LukeMathWalker/tracing-bunyan-formatter/master/images/ConsoleOutput.png" /> //! </div> //! <hr/> //! //! If you pipe the output in the [`bunyan`](https://github.com/trentm/node-bunyan) CLI: //! <div> //! <img src="https://raw.githubusercontent.com/LukeMathWalker/tracing-bunyan-formatter/master/images/ConsoleBunyanOutput.png" /> //! </div> //! <hr/> //! //! //! ## Implementation strategy //! //! The layered approach we have pursued is not necessarily the most efficient, //! but it makes it easier to separate different concerns and re-use common logic across multiple [`Layer`]s. //! //! While the current crate has no ambition to provide any sort of general purpose framework on top of //! [`tracing-subscriber`]'s [`Layer`] trait, the information collected by [`JsonStorageLayer`] can be leveraged via //! its public API by other downstream layers outside of this crate whose main concern is formatting. //! It significantly lowers the amount of complexity you have to deal with if you are interested //! in implementing your own formatter, for whatever reason or purpose. //! //! You can also add another enrichment layer following the [`JsonStorageLayer`] to collect //! additional information about each span and store it in [`JsonStorage`]. //! We could have pursued this compositional approach to add `elapsed_milliseconds` to each span //! instead of baking it in [`JsonStorage`] itself. //! //! [`Layer`]: https://docs.rs/tracing-subscriber/0.2.5/tracing_subscriber/layer/trait.Layer.html //! [`JsonStorageLayer`]: struct.JsonStorageLayer.html //! [`JsonStorage`]: struct.JsonStorage.html //! [`BunyanFormattingLayer`]: struct.BunyanFormattingLayer.html //! [`Span`]: https://docs.rs/tracing/0.1.13/tracing/struct.Span.html //! [`Subscriber`]: https://docs.rs/tracing-core/0.1.10/tracing_core/subscriber/trait.Subscriber.html //! [`tracing`]: https://docs.rs/tracing //! [`tracing`]: https://docs.rs/tracing-subscriber mod formatting_layer; mod storage_layer; pub use formatting_layer::*; pub use storage_layer::*;