Crate tailtriage 

tailtriage

tailtriage is the recommended default entry point for Tokio tail-latency triage.

It re-exports tailtriage-core at the crate root and exposes integration namespaces for controller workflows, Tokio runtime sampling, and Axum request boundaries. controller and tokio are enabled by default; axum remains opt-in.

What problem this solves

When a Tokio service slows down, the first triage question is often:

Is this slowdown mostly application queueing, executor pressure, blocking-pool pressure, or a slow downstream stage?

tailtriage helps you run the loop:

capture -> analyze -> next check -> re-run

The analysis result is triage guidance (evidence-ranked suspects plus next checks), not proof of root cause.

Common use cases

Symptom	tailtriage helps check
p95/p99 latency spikes	whether tail latency is dominated by queueing, executor pressure, blocking-pool pressure, or downstream stage latency
intermittent request timeouts	whether slow requests share a common bottleneck family in one captured run
low CPU but high latency	whether requests are waiting in queues, blocked behind constrained resources, or delayed by downstream work
suspected blocking in async code	whether blocking-pool pressure is visible and should be investigated with a targeted follow-up
Tokio runtime seems overloaded	whether captured runtime-pressure signals point toward executor contention rather than app-level queueing
slow database or external API suspected	whether a downstream stage dominates request latency enough to be the next check

Installation

For direct capture or repeated controller-managed capture windows:

cargo add tailtriage

Optional integration:

cargo add tailtriage --features axum

tailtriage captures request/runtime evidence. Install analyzer/report tooling based on how you work.

For command-line analysis of saved Run artifact JSON:

cargo install tailtriage-cli

For in-process Rust analysis/report generation:

cargo add tailtriage-analyzer

Add tailtriage-analyzer when you want to analyze a completed Run inside Rust code.

• tailtriage-cli consumes Run artifact JSON from disk.
• tailtriage-analyzer produces typed Report values in process and renders Report JSON when you call analyzer renderers.

Quick start

1) Capture one run

use tailtriage::Tailtriage;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let run = Tailtriage::builder("checkout-service")
        .output("tailtriage-run.json")
        .build()?;

    let started = run.begin_request("/checkout");
    started.completion.finish_ok();

    run.shutdown()?;
    Ok(())
}

2) Analyze the captured run

In process (typed Report + optional text/JSON rendering), use tailtriage-analyzer.

From the command line for saved artifacts, use tailtriage-cli:

tailtriage analyze tailtriage-run.json

Crate selection

Start with tailtriage when you want the recommended entry point and optional integrations behind feature flags.

Choose a focused crate only when you need a narrower boundary:

• tailtriage-core: framework-agnostic instrumentation primitives
• tailtriage-controller: repeated bounded windows
• tailtriage-tokio: runtime-pressure sampling and Tokio primitive helper trait (TokioRequestHandleExt)
• tailtriage-axum: Axum request-boundary wiring

Feature flags

• controller (default): enables tailtriage::controller
• tokio (default): enables tailtriage::tokio
• axum (opt-in): enables tailtriage::axum
• full: enables controller, tokio, and axum

Docs.rs note: tailtriage docs are built with all-features = true. In downstream crates, tailtriage::tokio is available with defaults, while tailtriage::axum remains feature-gated.

If you want a smaller core-only dependency surface, use tailtriage-core directly or depend on tailtriage with default-features = false.

Important constraints

• Capture and analysis are separate. For in-process analysis/report generation, use tailtriage-analyzer.
• For command-line analysis of saved artifacts, use tailtriage-cli.
• Tokio runtime sampling still requires explicit RuntimeSampler::start(...) with an active Tokio runtime.
• CaptureMode selection does not auto-start Tokio runtime sampling.
• Analysis output is triage guidance, not root-cause proof.

Related crates

• tailtriage-core: framework-agnostic instrumentation primitives and artifact model
• tailtriage-controller: repeated bounded capture windows
• tailtriage-tokio: Tokio runtime-pressure sampling
• tailtriage-axum: Axum request-boundary integration
• tailtriage-analyzer: in-process analysis/report generation for completed runs
• tailtriage-cli: command-line analysis of saved run artifacts

Re-exports

pub use tailtriage_axum as axum;axum

pub use tailtriage_controller as controller;controller

pub use tailtriage_tokio as tokio;tokio

Structs

CaptureLimits

Re-export of tailtriage-core, always available at the crate root.

CaptureLimitsOverride

Re-export of tailtriage-core, always available at the crate root.

DiscardSink

Re-export of tailtriage-core, always available at the crate root.

EffectiveCoreConfig

Re-export of tailtriage-core, always available at the crate root.

EffectiveTokioSamplerConfig

Re-export of tailtriage-core, always available at the crate root.

InFlightSnapshot

Re-export of tailtriage-core, always available at the crate root.

InflightGuard

Re-export of tailtriage-core, always available at the crate root.

LocalJsonSink

Re-export of tailtriage-core, always available at the crate root.

MemorySink

Re-export of tailtriage-core, always available at the crate root.

OwnedRequestCompletion

Re-export of tailtriage-core, always available at the crate root.

OwnedRequestHandle

Re-export of tailtriage-core, always available at the crate root.

OwnedStartedRequest

Re-export of tailtriage-core, always available at the crate root.

QueueEvent

Re-export of tailtriage-core, always available at the crate root.

QueueTimer

Re-export of tailtriage-core, always available at the crate root.

RequestCompletion

Re-export of tailtriage-core, always available at the crate root.

RequestEvent

Re-export of tailtriage-core, always available at the crate root.

RequestHandle

Re-export of tailtriage-core, always available at the crate root.

RequestOptions

Re-export of tailtriage-core, always available at the crate root.

Run

Re-export of tailtriage-core, always available at the crate root.

RunMetadata

Re-export of tailtriage-core, always available at the crate root.

RuntimeSnapshot

Re-export of tailtriage-core, always available at the crate root.

StageEvent

Re-export of tailtriage-core, always available at the crate root.

StageTimer

Re-export of tailtriage-core, always available at the crate root.

StartedRequest

Re-export of tailtriage-core, always available at the crate root.

Tailtriage

Re-export of tailtriage-core, always available at the crate root.

TailtriageBuilder

Re-export of tailtriage-core, always available at the crate root.

TruncationSummary

Re-export of tailtriage-core, always available at the crate root.

UnfinishedRequestSample

Re-export of tailtriage-core, always available at the crate root.

UnfinishedRequests

Re-export of tailtriage-core, always available at the crate root.

Enums

BuildError

Re-export of tailtriage-core, always available at the crate root.

CaptureMode

Re-export of tailtriage-core, always available at the crate root.

Outcome

Re-export of tailtriage-core, always available at the crate root.

RunEndReason

Re-export of tailtriage-core, always available at the crate root.

RuntimeSamplerRegistrationError

Re-export of tailtriage-core, always available at the crate root.

SinkError

Re-export of tailtriage-core, always available at the crate root.

Constants

SCHEMA_VERSION

Re-export of tailtriage-core, always available at the crate root.

Traits

RunSink

Re-export of tailtriage-core, always available at the crate root.

Functions

system_time_to_unix_ms

Re-export of tailtriage-core, always available at the crate root.

unix_time_ms

Re-export of tailtriage-core, always available at the crate root.