tracing-bunyan-formatter

tracing-bunyan-formatter provides two Layers implementation to be used on top of a tracing Subscriber:

• JsonStorageLayer, to attach contextual information to spans for ease of consumption by downstream Layers, via JsonStorage and Span's extensions;
• BunyanFormattingLayer`, which emits a 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.

Example

use tracing_bunyan_formatter::{BunyanFormattingLayer, JsonStorageLayer, Config};
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() {
    // UTC offset
    let config = Config { offset: 1 };
    let formatting_layer = BunyanFormattingLayer::new("tracing_demo".into(), std::io::stdout, Some(config));
    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

If you pipe the output in the bunyan CLI:

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 Layers.

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.

Optional features

You can enable the arbitrary_precision feature to handle numbers of arbitrary size losslessly. Be aware of a known issue with untagged deserialization.

Testing

Currently the tests only support being run sequentially, so the number of threads needs to be restricted:

cargo test -- --test-threads 1