Token usage logging: measurements, estimates, and cost
Keep reported usage separate from estimates, handle retries, and make cost calculations explainable.
USAGE INTELLIGENCE
Token log APIMake every usage number explainable.
Track input and output token measurements, preserve their provenance, and keep estimates separate from reported usage.
{
"schema_version": "1.0",
"timestamp": "2026-09-21T09:41:02.184Z",
"severity": "INFO",
"event_id": "evt_demo_003",
"event_name": "usage.recorded",
"service": "assistant-worker",
"attributes": {
"input_tokens": 1240,
"output_tokens": 386,
"usage_source": "sample",
"usage_complete": true
}
}Synthetic fixture · nothing is sentDownload JSON ↗
DESIGN WITH INTENT
Keep the important distinctions.
Keep attempts distinct
Connect retries to a workflow without hiding their consumption.
Label the unknowns
Missing usage is not the same as a zero-token request.
Version assumptions
Keep any cost estimate tied to its rate, unit, and effective date.
THE EVENT CONTRACT
Fields with a reason to exist.
Use a stable request or attempt identifier for reconciliation. Preserve provider-specific categories where flattening them would change their meaning. Review whether a subcategory is already included in a larger total before adding quantities together.
These fields illustrate a design pattern. Map them deliberately to your own schema, source, and destination.
| Field | What it means |
|---|---|
input_tokens | An observed or estimated input quantity, labeled by provenance. |
output_tokens | The output quantity when actually available. |
usage_source | Where the measurement came from. |
usage_complete | Whether the final usage information was observed. |
Token usage refers to model processing units. Authentication tokens are secrets and must not be copied into these records. No current provider pricing is implied.
Technical reference: Claude token counting documentation . Verify the version and settings used by your own implementation.
FIELD NOTES
Keep following the signal.
AI logging in production: context without oversharing
Instrument AI workflows with useful metadata, configuration versions, and clear outcomes—not entire conversations.
Reliable log ingestion: queues, retries, and duplicates
Define delivery guarantees, bound your buffers, and make duplicate records and pipeline failures visible.
ONE EVENT IS A GOOD START
Make your next log more useful.
Start with a clear schema. Keep the context that matters.