Skip to main content

Crate tailtriage_tokio

Crate tailtriage_tokio 

Source
Expand description

§tailtriage-tokio

Tokio integration for tailtriage, including RuntimeSampler for periodic runtime snapshots.

§Use from the repo

cargo run -p tailtriage-tokio --example minimal_checkout
cargo run -p tailtriage-cli -- analyze tailtriage-run.json --format json

§Add from crates.io

[dependencies]
tailtriage-core = "0.1.1"
tailtriage-tokio = "0.1.1"

§What this crate provides

  • RuntimeSampler for periodic Tokio runtime snapshots
  • Runtime evidence enrichment on the same run artifact used for request instrumentation
  • Works alongside the split lifecycle API from tailtriage-core (StartedRequest { handle, completion })

§Split lifecycle reminder

Request lifecycle ownership stays in tailtriage-core:

  • start with begin_request / begin_request_with
  • instrument via started.handle
  • finish exactly once via started.completion

shutdown() does not auto-finish pending requests. Unfinished requests are surfaced in run metadata, and strict_lifecycle(true) can make shutdown fail.

§RuntimeSampler metric availability

Always available on stable Tokio:

  • alive_tasks
  • global_queue_depth

Requires tokio_unstable:

  • local_queue_depth
  • blocking_queue_depth
  • remote_schedule_count

When tokio_unstable is not enabled, unstable-only fields are recorded as None.

§Minimal usage

use std::sync::Arc;
use std::time::Duration;

use tailtriage_core::Tailtriage;
use tailtriage_tokio::RuntimeSampler;

let tailtriage = Arc::new(
    Tailtriage::builder("checkout-service")
        .output("tailtriage-run.json")
        .build()?,
);

let sampler = RuntimeSampler::start(Arc::clone(&tailtriage), Duration::from_millis(200))?;

// ... run workload ...

sampler.shutdown().await;
tailtriage.shutdown()?;

§Axum adapter crate

Axum adoption helpers and axum examples live in tailtriage-axum.

The adapter is an ergonomics layer over core primitives. It does not claim production-hardening or zero-instrumentation auto-diagnosis. Tokio runtime integration for tailtriage.

This crate provides RuntimeSampler for periodic Tokio runtime metrics snapshots that feed evidence into the same unified Tailtriage API surface. Use it when you need stronger separation between executor pressure, blocking-pool pressure, queueing, and downstream-stage slowdowns.

Structs§

RuntimeSampler
Periodically samples Tokio runtime metrics and records them into a Tailtriage run.

Enums§

SamplerStartError
Errors produced while starting runtime sampling.

Functions§

capture_runtime_snapshot
Captures one point-in-time runtime metrics snapshot from handle.
crate_name
Returns the crate name for smoke-testing workspace wiring.