Crate tailtriage_core 

tailtriage-core

Core run schema, split request lifecycle API, and instrumentation primitives for tailtriage.

Use from the repo

From the workspace root, run examples and analysis directly:

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"

What this crate owns

• Run artifact schema (Run, requests, stages, queues, inflight snapshots, runtime snapshots)
• Unified started-request model (Tailtriage, StartedRequest, RequestHandle, RequestCompletion)
• Queue/stage/in-flight instrumentation primitives
• Explicit completion token lifecycle (finish, finish_ok, finish_result) and final artifact flush (shutdown)

Minimal usage

use tailtriage_core::{RequestOptions, Tailtriage};

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

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

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

tailtriage.shutdown()?;

Lifecycle ownership

begin_request(...) / begin_request_with(...) returns StartedRequest { handle, completion }:

• started.handle (RequestHandle) is instrumentation-only
• started.completion (RequestCompletion) is the only finish path

queue(...), stage(...), and inflight(...) do not finish the request. Every request must be finished exactly once via finish(...), finish_ok(), or finish_result(...).

Shutdown semantics

• shutdown() does not auto-finish requests.
• shutdown() does not fabricate timings or outcomes.
• unfinished requests are surfaced in run metadata warnings and unfinished-request samples.
• strict_lifecycle(true) makes shutdown() return an error when unfinished requests remain.

Related docs

• Repo docs index: https://github.com/SG-devel/tailtriage/tree/main/docs
• Tokio integration crate: https://github.com/SG-devel/tailtriage/tree/main/tailtriage-tokio
• CLI crate: https://github.com/SG-devel/tailtriage/tree/main/tailtriage-cli Core run schema and split request lifecycle instrumentation API for tailtriage.

use tailtriage_core::{RequestOptions, Tailtriage};

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

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

// queue(...), stage(...), and inflight(...) instrumentation can happen here.
// They do not finish the request lifecycle.
started.completion.finish_ok();
// You must finish each request exactly once via finish(...), finish_ok(), or finish_result(...).
// Drop only asserts on unfinished completions in debug builds; it does not auto-record completion.

tailtriage.shutdown()?;

Structs

CaptureLimits

Limits that bound in-memory capture growth for each run section.

InFlightSnapshot

Point-in-time in-flight gauge reading.

InflightGuard

RAII guard tracking one in-flight unit for a named gauge.

LocalJsonSink

Local file sink that writes one JSON document per run.

OwnedRequestCompletion

Completion-facing request token backed by Arc<Tailtriage>.

OwnedRequestHandle

Instrumentation-facing request handle backed by Arc<Tailtriage>.

OwnedStartedRequest

Split request lifecycle start result backed by Arc<Tailtriage>.

QueueEvent

Queue wait measurement for a request waiting on a queue/permit.

QueueTimer

Thin wrapper for recording queue-wait latency around one await point.

RequestCompletion

Completion-facing request token.

RequestEvent

Per-request timing and status.

RequestHandle

Instrumentation-facing request handle.

RequestOptions

Optional request start settings used by crate::Tailtriage::begin_request_with.

Run

A full output artifact for one tailtriage capture run.

RunMetadata

Top-level metadata for one capture run.

RuntimeSnapshot

Point-in-time runtime metrics sample.

StageEvent

Timing record for one named stage.

StageTimer

Thin wrapper for recording stage latency around one await point.

StartedRequest

Split request lifecycle start result.

Tailtriage

Per-run collector that records request events and writes the final artifact.

TailtriageBuilder

Builder for constructing a crate::Tailtriage run.

TruncationSummary

Per-section counters indicating dropped samples due to capture limits.

UnfinishedRequestSample

One unfinished request sample captured for lifecycle warnings.

UnfinishedRequests

Summary of unfinished requests detected at shutdown.

Enums

BuildError

Errors emitted while building one tailtriage capture instance.

CaptureMode

Capture mode used during a run.

Outcome

Logical request outcome categories used by the public API.

SinkError

Errors emitted while writing run artifacts.

Constants

SCHEMA_VERSION

Current schema version for Run JSON artifacts.

Traits

RunSink

A sink that can persist a run artifact.

Functions

system_time_to_unix_ms

Converts a SystemTime to unix epoch milliseconds.

unix_time_ms

Returns the current unix epoch timestamp in milliseconds.