tracing-forest

Preserve contextual coherence among trace data from concurrent tasks.

Overview

tracing is a framework for instrumenting programs to collect structured and async-aware diagnostics. The tracing-subscriber crate provides tools for working with tracing. This crate extends tracing-subscriber by providing types capable of preserving contextual coherence of trace data from concurrent tasks when logging.

This crate is intended for programs running many nontrivial and disjoint tasks concurrently, like server backends. Unlike other Subscribers which simply keep track of the context of an event, tracing-forest preserves the contextual coherence when writing logs, allowing readers to easily trace a sequence of events from the same task.

tracing-forest provides many tools for authoring applications, but can also be extended to author other libraries.

Getting started

The easiest way to get started is to enable all features. Do this by adding the following to your Cargo.toml file:

tracing-forest = { version = "1", features = ["full"] }

Then, add the #[tracing_forest::main] attribute to your main function:

#[tracing_forest::main]
fn main() {
    // do stuff here...
    tracing::trace!("Hello, world!");
}

Contextual Coherence in action

This example contains two counters, one for evens and another for odds. Running it will emit trace data at the root level, implying that all the events are independent, meaning each trace will be processed and written as it's collected. In this case, the logs will count up chronologically.

let evens = async {
    for i in 0..3 {
        tracing::info!("{}", i * 2);
        // pause for `odds`
        sleep(Duration::from_millis(100)).await;
    }
};

let odds = async {
    // pause for `evens`
    sleep(Duration::from_millis(50)).await;
    for i in 0..3 {
        tracing::info!("{}", i * 2 + 1);
        // pause for `evens`
        sleep(Duration::from_millis(100)).await;
    }
};

let _ = tokio::join!(evens, odds);

INFO     💬 [info]: 0
INFO     💬 [info]: 1
INFO     💬 [info]: 2
INFO     💬 [info]: 3
INFO     💬 [info]: 4
INFO     💬 [info]: 5

Instrumenting the counters tells the TreeLayer in the current subscriber to preserve the contextual coherence of trace data from each task. Traces from the even counter will be grouped, and traces from the odd counter will be grouped.

let evens = async {
    // ...
}.instrument(tracing::trace_span!("counting_evens"));

let odds = async {
    // ...
}.instrument(tracing::trace_span!("counting_odds"));
    
let _ = tokio::join!(evens, odds);

TRACE    counting_evens [ 409µs | 100.000% ]
INFO     ┕━ 💬 [info]: 0
INFO     ┕━ 💬 [info]: 2
INFO     ┕━ 💬 [info]: 4
TRACE    counting_odds [ 320µs | 100.000% ]
INFO     ┕━ 💬 [info]: 1
INFO     ┕━ 💬 [info]: 3
INFO     ┕━ 💬 [info]: 5

Although the numbers were logged chronologically, they appear grouped in the spans they originated from.

License

tracing-forest is open-source software, distributed under the MIT license.