Skip to content
Trazum

Getting a usage log

Documentation / Quick start · Commands · JSON contracts

Recorded spend comes from usage data. Prompt-only cost figures are projections. The prompt rules work without one — they count tokens — but "this label costs $340 a month and two thirds of it is the cache" is a sentence only a log can produce.

This page is the answer to the one thing a first run says most often: no usage found. Four shapes, with real records rather than a schema dump, because the moment you need one of these is the moment you have a file open and want to know whether it will work.

The normalized usage-log format is one JSON object per line — .jsonl, .ndjson, a .log file of the same, and any of those gzipped. A .json file holding a single JSON array is not read: convert it to one object per line first. Pass a file or a directory; a directory is read as one log, which is what a month of rotated files already is.

For provider and observability exports, trazum bill <path> detects supported shapes automatically. The rules below describe normalized logs used by profile, not every export accepted by bill.

What every record needs#

Two things, and nothing else is mandatory:

  • a model, so the tokens can be priced;
  • token counts, so there is something to price.

Everything else buys you a specific finding, and Trazum tells you which findings are unavailable rather than reporting them as zero.

FieldBuys you
labelPer-workload bills, budgets per label, the plan's ranking. Without it everything is one bucket.
timestampDays, drift, the watch, rates per month. Without it a total is still a total.
sessionConversation growth, per-session budgets, cache TTL fit.
threadOnly when one session runs several conversations at once, such as an agent and its subagents: which one the call belongs to. The turn-by-turn findings (growth, repeats, truncation retries, cache TTL fit, cache writes never read) follow each thread on its own; what a session costs, and the per-session budget, still count the whole session. Leave it out on the main conversation. from-claude-code and bill write it for you from a subagent's agentId.
interactiveOnly on a call something waited on: a person in a conversation, or an agent whose next step needed the answer. Say "interactive": true and plan stops offering the Batch API for that call, which answers within a day. from-claude-code, from-codex and from-gemini-cli write it on every line. Leave it out and nothing changes: a log that marks none of its calls is read as it always was.
cache token fieldsThe cache verdict — whether caching is paying for itself or costing you.
stop_reasonTruncation-and-retry detection: work billed twice.
requestsOnly on a row that sums calls, such as a usage report's hourly or daily bucket: how many it sums, or null when the report does not say. A per-call log leaves it out. It is what lets a model priced by prompt length be billed honestly: a call is billed on its own prompt, and a summed row at the dearer rate unless its whole prompt total is under the line, with the cheaper figure printed beside it. The from-* converters for usage reports write it for you.
outcomeCost per resolved outcome, the success rate, the quality gate, experiments on real traffic. Without it this tool can say a workload got 40% cheaper and cannot say whether it stopped working. Record your own word for what happened — nothing is inferred from a stop reason, a latency or a retry — and declare the vocabulary under outcomes in the config.

The names it will accept#

One concept, several spellings, because a log that already exists should not have to be rewritten to be read. Each row is tried in order and the first present value wins:

ConceptAccepted keys
when the call happenedts, timestamp, created_at, created
the conversationsession, conversation_id
what happenedoutcome, trazum_outcome
why it stoppedstop_reason, finish_reason, finishReason

trazum_outcome exists for the case where outcome already means something else in your pipeline. The prefixed name is never required and never preferred — it is there so a field collision is not a reason to go unmeasured.

trazum conform your-log.jsonl reports which of these a log carries, and what each absent one would have unlocked, rather than guessing.

Anthropic#

The API returns usage on every response. Log the whole usage object as it arrives — the field names below are Anthropic's own, and Trazum reads them directly:

{"timestamp":"2026-08-01T09:14:22Z","model":"claude-opus-5","label":"support-rag","session":"conv-8814","stop_reason":"end_turn","usage":{"input_tokens":1840,"output_tokens":412,"cache_read_input_tokens":18600,"cache_creation_input_tokens":0}}
{"timestamp":"2026-08-01T09:14:51Z","model":"claude-opus-5","label":"support-rag","session":"conv-8814","stop_reason":"end_turn","usage":{"input_tokens":2210,"output_tokens":388,"cache_read_input_tokens":18600,"cache_creation_input_tokens":0}}

cache_creation_input_tokens and cache_read_input_tokens are what make the cache verdict possible. A log without them is not a log with no caching — and Trazum says so instead of reporting a hit rate of zero.

Keep speed, inference_geo and service_tier inside usage. The response names all three, and each changes the bill. "service_tier": "batch" is the Batch API, billed at half the standard price; "standard" and "priority" are priced at the standard rate. "speed": "fast" is fast mode, which bills Opus 5.5 at $8/$40 against $4/$20 and Opus 5 and Opus 4.8 at $10/$50 against $5/$25. "inference_geo": "us" is US-only inference, which bills every token category at 1.1x on Claude 4.6 and later; "global" and "not_available" are the standard price. A line without either is priced at the standard, global rate, so a US-only workload logged without the field reads a tenth under its cost. A record from any other source can say "batch": true at the top level, which is what Trazum's own usage report converters write for a batch row. A call marked that way is billed at the batch rate, and plan does not offer to batch it a second time.

Keep server_tool_use too. "server_tool_use": {"web_search_requests": 3} is three searches by Anthropic's web search tool, billed at $10 per 1,000 on top of the tokens, at the same fee on the Batch API, in fast mode and on US-only inference. A line without it is billed for no searches. The count is all that crosses: what was searched for is in the content, which no usage log needs.

Claude Code's own transcripts keep both:

{"timestamp":"2026-11-01T09:14:22Z","model":"claude-opus-4-6","label":"support-rag","usage":{"input_tokens":1840,"output_tokens":412,"cache_read_input_tokens":18600,"speed":"standard","inference_geo":"us"}}

Without a log at all: trazum connect anthropic pulls the Admin API's usage report, which serves token sums per bucket. It carries no request count, so every per-call finding is reported as unavailable rather than computed from a call count nobody supplied. The key is an Admin API key with read access to the usage report, given as TRAZUM_ANTHROPIC_ADMIN_KEY (or ANTHROPIC_ADMIN_KEY); trazum connect names it, and what it needs, in its own refusal. The the command reference's trazum connect chapter is the walkthrough.

OpenAI#

The response's usage object, same idea:

{"timestamp":"2026-08-01T09:14:22Z","model":"gpt-5","label":"classify","usage":{"prompt_tokens":3400,"completion_tokens":180,"prompt_tokens_details":{"cached_tokens":3072}}}

prompt_tokens includes the cached ones, so Trazum subtracts prompt_tokens_details.cached_tokens before pricing — counting them twice would report a bill higher than the invoice, and in the direction that flatters the tool.

The Responses API spells the same thing input_tokens and input_tokens_details, with the cached tokens likewise inside the total, and Trazum reads either spelling:

{"timestamp":"2026-10-05T09:14:22Z","model":"gpt-6-sol","label":"agent","usage":{"input_tokens":120000,"output_tokens":900,"input_tokens_details":{"cached_tokens":100000,"cache_write_tokens":15000}}}

On GPT-5.6 and later, cache_write_tokens is also inside the total: the tokens this request wrote to the cache, billed at 1.25x input. Trazum takes them out with the cached ones and prices them as writes, against an entry that lives at least 30 minutes, which is what the cache TTL verdict judges your gaps against on those models.

Keep service_tier beside usage. The response names the tier that ran, and OpenAI bills each from its own table: "flex" at about half the standard price, "priority" or "fast" at up to twice, "ultrafast" at six times on GPT-6 Astra and GPT-6.1 Sol. A line without it, or with "default", is priced at the standard rate, so a Flex workload logged without the field reads at twice its cost:

{"timestamp":"2026-11-01T09:14:22Z","model":"gpt-6-sol","service_tier":"flex","usage":{"input_tokens":120000,"output_tokens":900,"input_tokens_details":{"cached_tokens":100000}}}

Moonshot's Kimi API reports usage in the same two shapes, cache_write_tokens included, and Trazum reads them the same way. On Kimi K3 a write is billed by its entry's lifetime, $3 for five minutes and $6 for an hour per million tokens; the usage line does not say which, so Trazum prices Kimi's default of five minutes and counts the call among those whose write TTL was assumed. Kimi's Anthropic-compatible endpoint reports cache_creation split by TTL, which needs no assumption.

Without a log: trazum connect openai reads the usage endpoint, which does serve request counts.

Vercel AI SDK#

onFinish gives you the usage for the call. The SDK's names differ from both providers above, so map them once at the edge:

const result = streamText({
  model: anthropic('claude-opus-5'),
  prompt,
  onFinish({ usage, finishReason }) {
    log.write(`${JSON.stringify({
      timestamp: new Date().toISOString(),
      model: 'claude-opus-5',
      label: 'summarise',
      session: threadId,
      stop_reason: finishReason,
      usage: {
        input_tokens: usage.promptTokens,
        output_tokens: usage.completionTokens,
      },
    })}\n`);
  },
});

Write finishReason through. length on a call that then got retried is work billed twice, and it is one of the cheapest findings in the tool to act on.

An OpenTelemetry collector#

If your calls are already instrumented, the spans carry the counts — and trazum from-otel reads them without your reshaping anything. Point it at the OTLP/JSON any OpenTelemetry GenAI exporter produces (one document, or newline-delimited spans) and it converts each LLM-call span — the model from gen_ai.request.model/gen_ai.response.model, the timestamp from startTimeUnixNano, a label from the span's gen_ai.operation.name or the resource's service.name, and the gen_ai.usage.*_tokens counts:

trazum from-otel spans.otlp.json -o usage.jsonl
trazum profile usage.jsonl

Spans that are not LLM calls are counted and skipped, never priced, and the stderr summary says how many were converted, skipped, and carried no cache data. Nothing but the numbers crosses: prompt content, trace ids and every other attribute stay in the span. OpenTelemetry has not standardised the cache-write TTL split, so an OTel-sourced record carries no cache_creation and its cache verdicts read cannot tell rather than a fabricated one.

You can also reshape the spans yourself — the field names are yours to map, and Trazum reads a flat record as readily as a nested one:

{"timestamp":"2026-08-01T09:14:22Z","model":"claude-opus-5","label":"agent","input_tokens":92400,"output_tokens":1200}

Trazum writes OTLP as well: trazum doctor --otlp-out metrics.json produces OTLP/HTTP JSON for your pipeline to send, and trazum bill --otlp-out bill-metrics.json does the same for the bill, per closed day (see bill). Trazum writes the file; it never sends anything anywhere.

Batch API results#

You do not need to log a batch: the results file each provider returns is already a log Trazum reads.

# Anthropic: the results of one message batch, streamed to a file.
curl "https://api.anthropic.com/v1/messages/batches/$BATCH_ID/results" \
  -H "x-api-key: $ANTHROPIC_API_KEY" -H "anthropic-version: 2023-06-01" > results.jsonl
npx @trazum/cli bill results.jsonl

# OpenAI: the batch's output file.
curl "https://api.openai.com/v1/files/$OUTPUT_FILE_ID/content" \
  -H "Authorization: Bearer $OPENAI_API_KEY" > output.jsonl
npx @trazum/cli bill output.jsonl

Every billed line is priced at the model's batch rate, half the standard one. Results the provider says it did not bill (Anthropic's errored, canceled and expired, an OpenAI line without a 200) are counted and left out. Nothing but the model, the usage and the end reason crosses: the generated text and your custom_id stay in your file.

Checking a log before you trust it#

trazum profile your-log.jsonl

It reports what it could not read — malformed lines by position, models it could not price, duplicate lines and what they added — rather than skipping them quietly. A total that is quietly wrong by an unknown amount is worse than an error.

trazum init finds a log named usage.jsonl, usage.ndjson, usage.log, logs/usage.jsonl or a logs/ directory without being told. Anywhere else, name it.

Very large files#

A file larger than 256 MiB is read line by line instead of whole. JavaScript cannot hold a string much past 512 MiB, and an agent session that read large files or ran chatty commands can grow past that: Claude Code writes every tool result into its transcript.

In that mode each line longer than 4,096 characters is parsed, and every string in it longer than 4,096 characters is replaced by a short marker before it is kept. Those strings are prompts, replies, thinking, tool arguments and tool results; nothing is billed by its text here. What a converter reads (the type, model, ids, timestamp, session, working directory and token counts) is kept exactly, so the bill is the same as a whole read would give. The tests check that byte for byte, with every file forced down this path. A line that is not JSON, such as a CSV row, is never rewritten.

The web app's Bill tab does the same in the browser, with the same function (slimUsageLine in @trazum/core), so a large session dropped there is read without leaving the page either.

The run says which files were read this way, on stderr. A file whose lines are too many to hold even after that is refused with its name and size, never the runtime's "Invalid string length": split it (for example split -l 500000) and pass the pieces.