tailtriage-core

tailtriage-core is the framework-agnostic capture foundation for tailtriage.

Use it when you want explicit request lifecycle instrumentation and bounded JSON artifacts without controller, Axum, or Tokio runtime-sampler APIs unless you add them separately.

What this crate does

tailtriage-core owns capture-side lifecycle semantics:

• request admission
• queue/stage/inflight instrumentation
• explicit request completion
• bounded in-memory retention
• JSON run artifact writing

For in-process analysis/report generation, use tailtriage-analyzer. For command-line analysis of saved artifacts, use tailtriage-cli.

Crate selection

Use tailtriage-core when you want the smallest framework-agnostic capture surface.

Use tailtriage when you want the recommended default entry point: an aggregator/re-export crate with optional integrations behind features.

Installation

cargo add tailtriage-core

Quick start

use tailtriage_core::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(())
}

Request lifecycle

begin_request(...) / begin_request_with(...) returns StartedRequest with:

• started.handle for queue/stage/inflight instrumentation
• started.completion for explicit finish

For Arc<Tailtriage> flows that move request handles across spawned tasks or helper layers, use begin_request_owned(...) / begin_request_with_owned(...). Owned handles keep the same lifecycle rule: instrumentation does not finish the request, and the completion token must be finished exactly once.

use tailtriage_core::{RequestOptions, Tailtriage};

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

    let started = run.begin_request_with(
        "/checkout",
        RequestOptions::new().request_id("req-1").kind("http"),
    );
    let req = started.handle.clone();

    req.queue("ingress").await_on(async {}).await;
    req.stage("db")
        .await_on(async { Ok::<(), std::io::Error>(()) })
        .await?;

    started.completion.finish_ok();
    run.shutdown()?;
    Ok(())
}

Output sinks

tailtriage-core captures run data and finalizes through a sink. It does not perform analysis/report generation.

• LocalJsonSink (or builder .output(...)) writes Run artifact JSON to disk.
• MemorySink stores finalized typed Run values in memory.
• DiscardSink finalizes lifecycle and drops the finalized Run without persisting output.

MemorySink stores only the last finalized Run; each new finalized run replaces the previous stored value.

Use MemorySink when you want in-process analysis. DiscardSink drops finalized runs; use MemorySink instead when the finalized Run should be analyzed in process.

use tailtriage_core::{MemorySink, Tailtriage};

# fn example() -> Result<(), Box<dyn std::error::Error>> {
let sink = MemorySink::new();
let run = Tailtriage::builder("checkout-service")
    .sink(sink.clone())
    .build()?;

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

let finalized = sink.last_run();
# let _ = finalized;
# Ok(())
# }

Two easy-to-miss helpers

For infallible async work, StageTimer::await_value(...) avoids a dummy Result:

# use tailtriage_core::Tailtriage;
# async fn demo(run: Tailtriage) {
# let req = run.begin_request("/x").handle;
let value = req.stage("cache").await_value(async { 42 }).await;
# let _ = value;
# }

When queue depth is known at enqueue time, QueueTimer::with_depth_at_start(...) records it directly:

# use tailtriage_core::Tailtriage;
# async fn demo(run: Tailtriage) {
# let req = run.begin_request("/x").handle;
req.queue("ingress")
    .with_depth_at_start(12)
    .await_on(async {})
    .await;
# }

Lifecycle contract

• queue(...), stage(...), and inflight(...) do not finish requests.
• Every admitted request must be finished exactly once.
• Dropping a completion token does not auto-finish.
• Non-strict lifecycle: shutdown() writes the artifact and records unfinished-request warnings/metadata.
• strict_lifecycle(true): unfinished requests cause shutdown() to return an error and no artifact is written.

Finalization timestamps:

• Active snapshot() output is not finalized (metadata.finalized_at_unix_ms == None).
• shutdown() writes final artifacts with both:
  • metadata.finished_at_unix_ms set to shutdown time
  • metadata.finalized_at_unix_ms set to that same timestamp
• Older artifacts may deserialize with metadata.finalized_at_unix_ms == None.
• When finalized_at_unix_ms is present, prefer that field as the finalization signal; finished_at_unix_ms remains for backward compatibility.

Capture modes

Modes change retention defaults only. They do not change lifecycle semantics and do not auto-start runtime sampling.

• CaptureMode::Light
• CaptureMode::Investigation

Override limits with:

• capture_limits(...) (full override)
• capture_limits_override(...) (field-level override)

What this crate does not do

This crate does not provide:

• repeated arm/disarm controller windows
• Tokio runtime sampling
• Axum middleware/extractors
• analysis/report generation

Use sibling crates for those surfaces: tailtriage-controller, tailtriage-tokio, tailtriage-axum, tailtriage-analyzer, and tailtriage-cli.