> Source: https://vitna.ai/docs/runtime/ledger
> Raw Markdown: https://vitna.ai/docs/runtime/ledger.md
> Corpus index: https://vitna.ai/llms.txt
# The ledger
One line per request, appended to the file `VITNA_LEDGER` names. It is yours, on
your disk, and it moves only when you move it.
## A row
```json
{
"at": "2026-08-24T09:14:02.118Z",
"model": "claude-opus-4-8",
"units": 1,
"lane": "deep-research",
"sku": "anthropic/claude-opus-4-8",
"provider": "anthropic",
"via": "direct",
"decision": "154",
"policy": "ecb93b2a5c50...",
"policyAgeSeconds": 3120,
"routed": true,
"serve": "primary",
"shadowRule": null,
"shadowSku": null,
"sellers": null,
"cohort": null,
"outcome": "served",
"status": 200,
"latencyMs": 2210,
"inputTokens": 812,
"outputTokens": 140,
"error": null
}
```
| Field | Meaning |
|---|---|
| `model` | The name the provider was asked for, which differs by route |
| `units` | One served request is one unit. A refused or failed one is zero, and so is one the [response cache](cache.md) answered, since no provider served it. |
| `lane`, `sku`, `decision`, `policy` | What makes the request attributable |
| `via` | `direct`, or the substrate |
| `routed` | False for a model name passed through untouched |
| `serve` | `primary`, `fallback:<n>` for the [chain](../routing/fallbacks.md) entry that answered, or `rule:<n>` for a routed [rule](../routing/rules.md) |
| `shadowRule`, `shadowSku` | Where a shadow rule matched: which rule, and what it would have served instead |
| `cohort` | The 0 to 99 bucket a [traffic share](../routing/rules.md) was decided by, and null where no share rule looked. A canary nobody can audit is a canary nobody should trust: this is why that rule matched this request |
| `sellers` | The hosts OpenRouter was allowed to serve this attempt from, in the policy's order, and null where the lane does not rotate. What was permitted, not which host answered |
| `outcome` | `served`, `refused`, `failed`, `timed_out`, `caller_left` or `drained` |
| `status` | What the provider answered, where it answered: null for a provider that could not be reached or never answered |
| `latencyMs` | How long the attempt took. For `timed_out` before anything reached the caller, the budget that ran out; for `caller_left`, the moment the caller hung up; for `drained`, the moment a restart's drain window closed |
| `inputTokens`, `outputTokens` | What the provider reported, or null. `inputTokens` is every input token: Anthropic reports the part it read from or wrote to its prompt cache beside `input_tokens` rather than inside it, and the runtime adds the three, as OpenAI's `prompt_tokens` already includes its cached part |
| `cacheReadTokens`, `cacheWriteTokens` | The parts of `inputTokens` the provider read from its prompt cache and wrote to it, which it bills at their own rates, and null where it reported none. OpenAI reports the first; Anthropic reports both, and so does OpenRouter for the models it prices a cache write for |
| `cacheWrite5mTokens`, `cacheWrite1hTokens` | The parts of `cacheWriteTokens` the provider kept for five minutes and for an hour, which it bills at different rates, as it reported them in `cache_creation`. Null where it did not report the split, and never derived from the total: a write with no split says nothing about its retention. Anthropic reports it; on a stream, each part is the last count it sent. OpenRouter reports a write as one count, so a row it served carries null in both |
| `cache_hit` | `true` on a row the [response cache](cache.md) answered, with `serve` and `via` both `cache`, no units and every token count null. Null otherwise |
| `secretsLifted`, `secretsRestored` | How many secrets [redaction](redaction.md) took out of the request, and how many surrogates it put back into the answer. Null where redaction did not apply to the request. Counts only: no secret is ever on a row |
| `requestId` | The id the caller sent for the request in `x-vitna-request-id`, on every row that request wrote, fallback attempts included, and null where it sent none. See [the request](serving.md#the-request) |
| `agentId`, `runId` | The agent or routine the caller says the request was made for, from `x-vitna-agent`, and which run of it, from `x-vitna-run`, on every row that request wrote, fallback attempts included, and null where it sent none. What the caller says, recorded as sent and checked against nothing. See [the request](serving.md#the-request) |
| `listPriceUsd`, `chargedUsd` | What the request cost at the list price the record showed, and what the provider or router reported charging. This runtime writes null for both today; a writer that knows them fills them, and neither is ever estimated |
| `hardware_cost_usd`, `cloud_market_usd`, `net_saved_usd`, `airgap`, `precision_tier` | What serving the request cost in hardware, a cloud price for the same request, the saving between the two, whether anything left the machine, and the quantization the model ran at. A writer fills one only with what it measured. This runtime measures none of them, so it writes null in all five, on every route |
## The three rules it inherits
**Append only.** One write per row. There is no code in the runtime that can
edit a line it has already written, and no compaction.
**Nothing is estimated.** A provider that reported no token counts gets nulls,
never a plausible figure. That is the synthetic fallback the record refuses in
every other data path, at request scale. It covers cost and egress as well.
Until 2026-09-27 `main` filled in the five cost and egress columns in the table
above on any row a lane whose provider is `local` served: a hardware cost and a
cloud price worked out of the token counts at fixed rates, the saving between
them, `airgap: true` and a precision tier, whatever had actually answered. None
of it was measured, so all five are null now. No published version of the
runtime wrote them.
**Three outcomes are the runtime stopping a request, not a provider failing
one.** `timed_out` is a provider that did not answer within its
[budget](serving.md#when-a-provider-hangs); before anything reached the caller
the lane's chain is walked after it, and after, the response is ended.
`caller_left` is a caller who hung up, after which the upstream request is
aborted and nothing else is tried. `drained` is a request still under way when a
[restart](serving.md#restarting) ran out of time to wait for it: the runtime cut
it, told a caller still waiting 503, and wrote this row before it exited.
**All three are requests the provider still bills** for whatever it generated
before the abort reached it, so all carry zero units and none is free. The
runtime writes none of them before 0.2.0.
**A failure is a row, and it is worth nothing.** A refused or failed request is
recorded with its outcome, because a ledger holding only successes makes "ran
little" and "failed often" the same shape. It carries zero units, because a
request nobody served is not a unit of work and counting it would put it in an
import's denominator. A window of nothing but refusals therefore totals zero,
and the import says the file says nothing about what ran.
## One request can be more than one row
A request a fallback answered is two rows: the primary's failure, worth no
units, and the fallback's serve, worth one. Totals stay right, and the ledger
still says the primary was down.
That is also what tells the two stories of a split window apart. A window where
a minority share sits on `fallback:1` rows is a lane with a healthy failover. The
same split sitting on `primary` rows is a deployment that has drifted onto a
model nobody decided, which is a different problem with a different fix.
## Reading it back
The file is the shape [`aperture:usage:import`](../routing/usage-import.md)
already reads, so it is imported by the command that already existed:
```bash
npm run aperture:usage:import -- \
--workload convexity/deep-research --file /var/lib/vitna/ledger.jsonl \
--window 2026-08-01..2026-08-31 --source-ref "runtime ledger, box 1"
```
`.jsonl` is recognised by extension. The reader takes the same two fields it
takes from a CSV, `model` and `units`, and ignores the rest of the row.
## The run becomes evidence
The import above says what ran. A second reader takes the same file and writes
what the run measured, as a row on the workload in the register:
```bash
npm run aperture:evidence:from-run -- --workload convexity/deep-research --file /var/lib/vitna/ledger.jsonl --label "Harness run, 10 Sep"
```
One measurement per sku the run served, carrying `latencyP90Ms` out of the
`latencyMs` column and `n` out of the units, both naming the run they came
from. It is the same append-only path
[`aperture:evidence:add`](../cli/aperture/evidence.md) writes through and it
passes the same refusals.
What it does not write is a success rate. A `failed` row is a request nobody
served, and the share of requests that came back is not the quality of the
answers that did: Vitna measures what this file observed and grades nothing.
## Why this is better than an export
The [first real import](../routing/usage-import.md), on 2026-08-24, taught three
things, and all three are properties of reading somebody's export after the fact:
- **A surface is not an intent.** That export could only be scoped by where a
call came from, so a lane's window carried 56 percent of a model that lane
never ran. A ledger is lane-exact because the caller named the lane.
- **The register could not see volume.** A dormant lane and one carrying thirty
thousand calls read identically. A row count is a volume.
- **Most of a window resolved by the weaker of two routes.** The ledger records
the name the policy said to send, so there is nothing to map back.
Nothing pushes this anywhere on its own. [`vitna-runtime-push`](pushing.md)
sends closed days to the record when an operator runs or schedules it, opt-in
and off by default, and the file path stays the default path.
## What it can tell you without leaving the machine
`inputTokens` and `outputTokens` per request per lane are a measurement nobody
hands you: what one call on this lane actually consumes.
[`runtime:profile`](profile.md) totals them into a
[unit profile](../cli/aperture/workloads.md) per lane, with the window and the
sample size beside each figure, reading this file and reaching no network.