Get started

The ledger

Source

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
}
FieldMeaning
modelThe name the provider was asked for, which differs by route
unitsOne served request is one unit. A refused or failed one is zero, and so is one the response cache answered, since no provider served it.
lane, sku, decision, policyWhat makes the request attributable
viadirect, or the substrate
routedFalse for a model name passed through untouched
serveprimary, fallback:<n> for the chain entry that answered, or rule:<n> for a routed rule
shadowRule, shadowSkuWhere a shadow rule matched: which rule, and what it would have served instead
cohortThe 0 to 99 bucket a traffic share 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
sellersThe 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
outcomeserved, refused, failed, timed_out, caller_left or drained
statusWhat the provider answered, where it answered: null for a provider that could not be reached or never answered
latencyMsHow 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, outputTokensWhat 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, cacheWriteTokensThe 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, cacheWrite1hTokensThe 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_hittrue on a row the response cache answered, with serve and via both cache, no units and every token count null. Null otherwise
secretsLifted, secretsRestoredHow many secrets redaction 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
requestIdThe 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
agentId, runIdThe 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
listPriceUsd, chargedUsdWhat 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_tierWhat 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; 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 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` 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` 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, 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` 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` totals them into a unit profile per lane, with the window and the sample size beside each figure, reading this file and reaching no network.