Crate tailtriage_analyzer

Expand description

§tailtriage-analyzer

tailtriage-analyzer is the in-process analyzer/report crate for tailtriage.

Use this crate when you already have a completed tailtriage_core::Run in memory (or an equivalent stable snapshot) and want a typed triage report, text rendering, and canonical Report JSON rendering in your Rust process.

§What this crate does

analyzes one completed run/snapshot in batch
returns a typed Report with evidence-ranked suspects and next checks
renders human-readable output with render_text(&Report)
renders canonical Report JSON with render_json(&Report) and render_json_pretty(&Report)
provides analyze+render helpers: analyze_run_json and analyze_run_json_pretty

Suspects are investigation leads, not proof of root cause.

tailtriage-analyzer accepts any tailtriage_core::Run value. It is intended for completed/finalized captures or stable snapshots; callers that require finalized artifacts should validate that separately.

§Installation

cargo add tailtriage-analyzer

You also need a capture crate that provides tailtriage_core::Run, such as tailtriage or tailtriage-core.

§How to obtain a `Run`

tailtriage-analyzer does not capture requests and does not load artifacts from disk.

Typical flow:

capture/integration crates (tailtriage, tailtriage-core, tailtriage-controller, tailtriage-tokio, tailtriage-axum, tailtriage-tracing) produce completed runs or saved artifacts
tailtriage-analyzer analyzes completed in-memory runs or stable snapshots in process
tailtriage-cli loads saved artifacts from disk and invokes tailtriage-analyzer

§In-process API

use tailtriage_analyzer::{analyze_run, render_json_pretty, render_text, AnalyzeOptions};
use tailtriage_core::Run;

fn render_report(run: &Run) -> Result<String, Box<dyn std::error::Error>> {
    let report = analyze_run(run, AnalyzeOptions::default());
    let text = render_text(&report);
    let json = render_json_pretty(&report)?;
    Ok(format!("{text}\n\n{json}"))
}

§Report contract

analyze_run currently returns Report directly and is currently infallible
AnalyzeOptions::default() is the normal path today and leaves room for future analyzer options
Report is the typed analyzer output model and should be your primary integration surface
render_text is for human-readable triage output
render_json and render_json_pretty are canonical Report JSON renderers
analyze_run_json and analyze_run_json_pretty combine analysis + canonical JSON rendering
Report JSON is analyzer output and is distinct from raw Run artifact JSON input
default analysis is permissive: duplicate completed request IDs emit warnings; strict artifact validation APIs reject duplicate completed request IDs and orphan stage/queue request IDs

§Request ID contract

request_id is the per-run tailtriage identity of one completed logical request/work item. It must be unique among completed requests in one Run; stage and queue events must reuse that ID only for the same logical request. Duplicate completed IDs make request-scoped queue attribution, route breakdowns, temporal segmentation, and downstream-stage matching ambiguous.

Use validate_artifact_strict or try_analyze_run_strict_artifact when you want the analyzer to reject duplicate completed request IDs and orphan stage/queue request IDs before producing evidence-ranked suspects and next checks. Default analysis remains backward-compatible and warns instead of failing.

Users remain responsible for meaningful instrumentation and request-boundary semantics. The analyzer cannot know whether an external trace ID, retry ID, fanout ID, or batch ID identifies the correct logical request; convert repeating external IDs into unique tailtriage request IDs before analysis.

§Analyzer tuning options

Start with defaults:

use tailtriage_analyzer::AnalyzeOptions;

let options = AnalyzeOptions::default();
let _ = options;

In-process checked custom options:

use tailtriage_analyzer::{try_analyze_run, AnalyzeOptions};
use tailtriage_core::Run;

fn analyze_checked(run: &Run) -> Result<(), Box<dyn std::error::Error>> {
    let options = AnalyzeOptions::default()
        .with_queueing(|o| o.trigger_permille = 450);
    let report = try_analyze_run(run, options)?;
    let _ = report;
    Ok(())
}

TOML parsing example:

use tailtriage_analyzer::AnalyzeOptions;

let input = r#"
[analyzer]
schema_version = 1

[analyzer.queueing]
trigger_permille = 450
"#;

let options = AnalyzeOptions::from_toml_str(input)?;

Report transparency behavior:

default options omit analyzer_config from Report JSON
non-default options include analyzer_config with active non-default overrides
tuning changes interpretation of captured evidence; it does not change capture artifacts

§Semantics and boundaries

batch/snapshot analysis of one completed run
not streaming analysis
artifact loading from disk is CLI-owned (tailtriage-cli)
CLI --format json uses the same canonical pretty Report JSON rendering path

§Report fields (overview)

Report includes request counts, latency percentiles, queue/service share summaries, warnings, evidence quality, ranked suspects, and optional supporting route/temporal sections.

§How to interpret a report

primary_suspect is the strongest triage lead for the analyzed run, not proof of root cause.
secondary_suspects are lower-ranked leads worth checking when evidence is close or the primary lead does not explain the incident.
evidence[] explains why a suspect was ranked.
next_checks[] gives targeted follow-up actions.
score ranks suspects inside one report; it is not a probability.
confidence is ranking strength and may be capped by missing, sparse, partial, or truncated evidence.
warnings[] and evidence_quality describe interpretation limits.
route_breakdowns and temporal_segments, when present, are supporting context only and do not override the global primary_suspect.
Report JSON is analyzer output and is distinct from raw Run artifact JSON.

§Migration note

// Old pre-0.1.x API was hosted in the CLI crate.
// Use the analyzer crate directly for in-process analysis/report APIs.

use tailtriage_analyzer::{analyze_run, render_text, AnalyzeOptions};

Structs§

AnalyzeConfigOverrideSummary: One non-default analyzer option override rendered as a stable path/value pair.
AnalyzeOptionDescriptor: Human-readable metadata for one semantic analyzer option path.
AnalyzeOptions: Semantic analyzer options grouped by triage domain.
Analyzer: Reusable analyzer configured with AnalyzeOptions.
AnalyzerConfigSummary: Summary of non-default analyzer options used during analysis.
BlockingOptions: Blocking-pressure suspect thresholds and minimum-sample guards.
ConfidenceOptions: Confidence-bucket and ambiguity-warning score thresholds.
DownstreamOptions: Downstream-stage suspect thresholds and blocking-correlation heuristics.
EvidenceOptions: Evidence-quality thresholds used for low-sample warnings.
EvidenceQuality: Structured capture-coverage and interpretation-quality summary.
ExecutorOptions: Executor-pressure suspect thresholds derived from runtime queue pressure.
InflightTrend: Summary of one dominant in-flight gauge trend over the run window.
QueueingOptions: Queue-saturation suspect thresholds.
Report: Rule-based triage report for one completed Run snapshot.
RouteBreakdown: Supporting per-route triage summary derived from captured request route labels.
RouteOptions: Route-breakdown thresholds used for route-level suspect comparisons.
Suspect: Evidence-ranked suspect produced by heuristic analysis.
TemporalOptions: Temporal-shift thresholds used for early/late suspect comparisons.
TemporalSegment: Supporting early/late temporal triage summary for one run.

Enums§

AnalyzeConfigError: Validation and configuration errors for analyzer options and checked triage APIs.
AnalyzeRunError: Error returned by try_analyze_run_strict_artifact.
ArtifactValidationError: Errors returned by strict run-artifact validation.
Confidence: Confidence bucket derived from suspect score thresholds.
DiagnosisKind: Evidence-ranked diagnosis categories produced by heuristic triage.
EvidenceQualityLevel: Overall evidence-quality level for this capture.
SignalCoverageStatus: Coverage status for one signal family.

Functions§

analyze_option_descriptors: Returns semantic analyzer option descriptors for every supported v1 path.
analyze_run: Analyzes one completed Run with rule-based heuristics and returns a triage report.
analyze_run_json: Analyzes one in-memory Run and returns compact analyzer Report JSON.
analyze_run_json_pretty: Analyzes one in-memory Run and returns canonical pretty analyzer Report JSON.
render_json: Renders analyzer Report JSON in compact form.
render_json_pretty: Renders analyzer Report JSON in canonical pretty form.
render_text: Renders a compact text triage summary from a Report.
try_analyze_run: Analyzes one completed Run with validated options and returns a triage report.
try_analyze_run_json: Analyzes one in-memory Run and returns compact analyzer Report JSON.
try_analyze_run_json_pretty: Analyzes one in-memory Run and returns pretty analyzer Report JSON.
try_analyze_run_strict_artifact: Validates options and strict artifact invariants, then analyzes one Run.
validate_artifact_strict: Strictly validates request-scoped artifact invariants before analysis.