← Back to Meter
AgentMeter
Traceable usage records
Records resource consumption with its owner, units and measurement quality so later cost calculations can be explained and checked.
usage-event-modeling-collection
See how it helpsWhen is it useful?
Use when usage comes from requests, background jobs and AI runs, but individual costs cannot be traced back reliably.
What does it help you do?
- Defines immutable events with separate occurrence and recording times and explicit units.
- Carries customer and task context through queues and services, retaining unattributed usage for investigation.
- Records partial, cancelled and retried work rather than counting only successful final results.
Try asking this
Design usage events for an AI export that retries after a timeout. Keep each attempt, its customer, token quantities and whether the measurement is estimated or provider-reported. Compare the timed-out attempt and its retry using separate attempt IDs. Keep both measurements linked to one task without treating estimates as final provider evidence.
Detailed documentation
Read the skill’s original instructions, examples and checks in their authored language.
Show less
Usage Event Modeling & Collection
Usage metering starts with an immutable, self-describing event record. Every resource consumption event must capture who triggered it, what ran, how much was consumed, and how certain the measurement is.
Workflow
- Define canonical usage event schema:
- Require every raw usage event to carry:
eventId/idempotencyKey: Deterministic key derived from the source operation ({source}:{operationId}:{stepId}:{attempt}).occurredAtandrecordedAt: Distinguish when consumption happened from when the collector ingested it (occurredAtgoverns pricing period and budget window).- Attribution dimensions:
tenantId/workspaceId,actorId(user, API key, or service account),projectId,taskId,runId,stepId,agentRole/agentId, andenvironment. - Resource identity:
provider(anthropic,openai,aws-s3,worker),service/model,operationType, andregionortier. - Explicit quantities & units: Separate numeric quantities by unit (
input_tokens,cached_input_tokens,output_tokens,bytes_stored,byte_hours,egress_bytes,cpu_ms,wall_ms). - Measurement certainty:
certainty: 'estimated' | 'provider_reported' | 'reconciled_invoice'.
- Require every raw usage event to carry:
- Propagate metering context end-to-end:
- Pass correlation metadata (
tenantId,userId,taskId,runId,parentSpanId) through HTTP headers, queue payloads, webhook handlers, scheduled jobs, and AI tool calls. - Route events lacking a customer
tenantIdto an explicit system-cost or quarantine bucket rather than dropping them.
- Pass correlation metadata (
- Decouple collection from the hot request path:
- Emit usage events asynchronously via outbox tables, ring buffers with shutdown flush hooks, or queues so metering never blocks user-facing API calls or streams.
- Persist raw provider metadata (
requestId,usagesnapshot, status) alongside normalized quantities.
- Account for failed, partial, and cancelled operations:
- Record upstream consumption even when an operation times out, fails validation after an LLM/API call, is cancelled mid-stream, or is retried.
Anti-Patterns to Avoid
- Mutating counters in place:
UPDATE tenant_usage SET tokens = tokens + ?without an event log destroys auditability and prevents repricing. - Ambiguous units: Mixing
MB(10^6) andMiB(2^20), or milliseconds and seconds, without an explicit unit field. - Swallowing retry consumption: Recording only the final successful attempt while ignoring failed retries that incurred provider cost.
Included files 1
SKILL.md