Crate tailtriage_controller

Expand description

§tailtriage-controller

tailtriage-controller manages repeated, bounded capture windows for long-lived services.

Use it when you want to turn capture on, collect one generation, turn capture off, and later start a fresh generation without restarting the process.

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

§When to use this crate

Use tailtriage-controller when you need repeated arm/disarm windows in one process.

Use tailtriage-core for a single explicit build -> capture -> shutdown run.

Use tailtriage when you want the default entry point with controller support enabled by default (or disabled via Cargo features).

§Installation

cargo add tailtriage-controller

§Quick start

output("tailtriage-run.json") configures the base artifact path template. Each activation writes a per-generation artifact with -generation-N in the file name (for example, generation 1 writes tailtriage-run-generation-1.json).

use tailtriage_controller::TailtriageController;

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

    let _generation = controller.enable()?;

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

    let _ = controller.disable()?;
    Ok(())
}

§Mental model

A controller owns a template plus at most one active generation.

enable() creates a fresh generation from the current template.
disable() stops new admissions for that generation.
If no captured requests are still in flight, the generation finalizes immediately.
Otherwise the generation enters closing and finalizes after its already-admitted captured requests drain.
The next enable() creates a new generation with a new artifact path.

Requests started while the controller is disabled or closing are inert:

they preserve request metadata
they record no capture events
they never join a later generation

Each activation writes a per-generation artifact whose file name includes -generation-N.

§Minimal TOML example

Use TOML when you want repeatable operational settings, including mode selection.

[controller]
service_name = "checkout-service"

[controller.activation]
mode = "light"

[controller.activation.sink]
type = "local_json"
output_path = "tailtriage-run.json"

§Expanded TOML example

[controller]
service_name = "checkout-service"
initially_enabled = false

[controller.activation]
mode = "investigation"
strict_lifecycle = true

[controller.activation.capture_limits_override]
max_requests = 150000
max_stages = 300000
max_queues = 300000
max_inflight_snapshots = 300000
max_runtime_snapshots = 150000

[controller.activation.sink]
type = "local_json"
output_path = "tailtriage-run.json"

[controller.activation.runtime_sampler]
enabled_for_armed_runs = true
mode_override = "investigation"
interval_ms = 250
max_runtime_snapshots = 20000

[controller.activation.run_end_policy]
kind = "auto_seal_on_limits_hit"

§Config precedence and reload rules

When TOML is loaded with config_path(...):

service_name from TOML overrides the builder value when present.
builder service_name is a fallback only when TOML omits service_name.
initially_enabled falls back to the builder value when omitted.
activation template settings come from TOML.
omitted optional activation subfields use TOML contract defaults.

reload_config() updates the template for future generations only.

It does not mutate a generation that is already active.

§Run-end policies

Supported policies:

continue_after_limits_hit (default)
auto_seal_on_limits_hit

Behavior:

continue_after_limits_hit: generation stays active after the first truncation
auto_seal_on_limits_hit: on the first limits_hit, new admissions stop and the generation moves to closing; finalization happens immediately if no captured requests are still in flight, otherwise after they drain

TOML contract:

[controller.activation.run_end_policy] is optional
if that table is present, kind is required

§Runtime sampler template

The controller can start a Tokio runtime sampler automatically for armed generations.

Important constraints:

sampler startup still requires an active Tokio runtime
sampler settings are fixed at activation time
runtime snapshot retention is still bounded by the resolved core capture limits

§TOML field reference

§`[controller]`

service_name (optional string): overrides the builder service name when present; must not be empty
initially_enabled (optional bool): when true, build() starts generation 1

§`[controller.activation]`

mode (required string): light or investigation
strict_lifecycle (optional bool, default false)

§`[controller.activation.sink]`

type (required string): local_json
output_path (required string for local_json): base path template for per-generation files

§`[controller.activation.capture_limits_override]`

All fields are optional:

max_requests
max_stages
max_queues
max_inflight_snapshots
max_runtime_snapshots

§`[controller.activation.runtime_sampler]`

Optional table. Default is disabled.

enabled_for_armed_runs
mode_override
interval_ms
max_runtime_snapshots

§`[controller.activation.run_end_policy]`

Optional table. If present, kind is required.

kind = "continue_after_limits_hit"
kind = "auto_seal_on_limits_hit"

§Important constraints

at most one generation is active at a time
active generation settings do not change after activation
requests remain bound to the generation that admitted them
controller capture and analysis are separate
for in-process analysis/report generation, use tailtriage-analyzer
for command-line analysis of saved artifacts, use tailtriage-cli

tailtriage: default entry point
tailtriage-core: direct instrumentation lifecycle
tailtriage-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

Structs§

ActiveGenerationState: Metadata for one active generation.
ControllerActivationTemplate: One bounded activation template snapshot.
ControllerRequestCompletion: Completion token for a request admitted through TailtriageController.
ControllerStartedRequest: Result of trying to begin one captured request in a generation.
InertControllerRequestHandle: Inert controller request handle metadata stored while disabled/closing.
LoadedControllerConfig: Parsed controller config loaded from a TOML file.
RuntimeSamplerTemplate: Runtime sampler template attached to controller activation settings.
TailtriageController: Long-lived live-capture controller for arm/disarm workflows.
TailtriageControllerBuilder: Builder for a long-lived TailtriageController.
TailtriageControllerStatus: Public status snapshot for reporting controller state.
TailtriageControllerTemplate: Template configuration that the controller applies to future activations.

Enums§

ConfigLoadError: Errors emitted while loading controller TOML config from disk.
ControllerBuildError: Errors emitted while building a controller.
ControllerInflightGuard: Controller-local in-flight guard wrapper.
ControllerQueueTimer: Controller-local queue timer wrapper.
ControllerRequestHandle: Instrumentation handle for requests admitted through TailtriageController.
ControllerSinkTemplate: Sink/output template used by controller-generated runs.
ControllerStageTimer: Controller-local stage timer wrapper.
DisableError: Errors emitted while disarming and finalizing generation artifacts.
DisableOutcome: Outcome of calling TailtriageController::disable.
EnableError: Errors emitted when enabling/arming controller capture.
GenerationState: Current generation state for a controller.
ReloadConfigError: Errors emitted while reloading controller TOML config.
ReloadTemplateError: Errors emitted while replacing controller activation templates directly.
RunEndPolicy: Policy for bounded activation run completion.
ShutdownError: Errors emitted during process shutdown finalization.