tailtriage-core 0.1.0

Core schema and request instrumentation primitives for Tokio tail-latency triage
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73

# tailtriage-core


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

For the public repo launch, the primary path is workspace/source integration from this repository. Crates.io snippets below are post-publish guidance.

## Use from this repo now


From the workspace root, run examples and analysis directly:

```bash
cargo run -p tailtriage-tokio --example minimal_checkout
cargo run -p tailtriage-cli -- analyze tailtriage-run.json --format json
```

## Post-publish crate add (when released)


```toml
[dependencies]
tailtriage-core = "0.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


```rust,no_run
use tailtriage_core::{RequestOptions, Tailtriage};

# async fn demo() -> Result<(), Box<dyn std::error::Error>> {

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()?;
# Ok(())

# }

```

## 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>