tracing-texray ![Latest Version]

tracing-texray is a tracing layer to introspect spans and events in plain text. By examine-ing a specific span, a full tree will be output when that span exits. Using code like the following (actual program elided):

``rust fn main() { // initialize & install as the global subscriber tracing_texray::init(); // examine theloaddata` span: tracingtexray::examine(tracing::infospan!("loaddata")).inscope(|| { doa_thing() }); }

fn doathing() { // ... } ```

You would see the following output printed to stderr:

```text loaddata 52ms ├────────────────────────────────┤ downloadresults{uri: www.crates.io} 11ms ├─────┤

URI resolved ┼ connected ┼ computestats 10ms ├─────┤ renderresponse 6ms ├──┤ ```

In cases where a more powerful solution like tracing-chrome is not required, tracing-texray can render lightweight timeline of what happened when.

Usage

tracing-texray combines two pieces: a global subscriber, and local span examination. By default, tracing-texray won't print anything—it just sits in the background. But: once a span is examine'd, tracing-texray will track the span and all of its children. When the span exits, span diagnostics will be printed to stderr (or another impl io::Write as configured).

First, the layer must be installed globally:

```rust,norun use std::time::Duration; use tracingtexray::TeXRayLayer; use tracingsubscriber::{Registry, EnvFilter, layer::SubscriberExt}; fn main() { // Option A: Exclusively using tracingtexray: tracing_texray::init();

// Option B: install the layer in combination with other layers, eg. tracing_subscriber::fmt:
let subscriber = Registry::default()
    .with(EnvFilter::try_from_default_env().expect("invalid env filter"))
    .with(tracing_subscriber::fmt::layer())
    .with(
        TeXRayLayer::new()
            // by default, all metadata fields will be printed. If this is too noisy,
            // fitler only the fields you care about
            .only_show_fields(&["name", "operation", "service"])
            // only print spans longer than a certain duration
            .min_duration(Duration::from_millis(100)),
    );
tracing::subscriber::set_global_default(subscriber).unwrap();

} ```

Next, wrap any spans you want to track with examine:

```rust use tracing::infospan; use tracingtexray::examine;

fn somewheredeepinmyprogram() { tracingtexray::examine(infospan!("doathing")).inscope(|| { for id in 0..5 { someother_function(id); } }) }

fn someotherfunction(id: usize) { infospan!("innertask", id = %id).in_scope(|| tracing::info!("buzz")); // ... } ```

When the do_a_thing span exits, output like the following will be printed: ```text doathing 509μs ├───────────────────────────────────────────────────┤ inner_task{id: 0} 92μs ├────────┤

buzz ┼ innertask{id: 1} 36μs ├──┤ buzz ┼ innertask{id: 2} 35μs ├──┤ buzz ┼ innertask{id: 3} 36μs ├──┤ buzz ┼ innertask{id: 4} 35μs ├──┤ buzz ┼ ```