Nachvollziehbare Nutzungsdaten

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

1. 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}).
     • occurredAt and recordedAt: Distinguish when consumption happened from when the collector ingested it (occurredAt governs pricing period and budget window).
     • Attribution dimensions: tenantId / workspaceId, actorId (user, API key, or service account), projectId, taskId, runId, stepId, agentRole / agentId, and environment.
     • Resource identity: provider (anthropic, openai, aws-s3, worker), service / model, operationType, and region or tier.
     • 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'.
2. 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 tenantId to an explicit system-cost or quarantine bucket rather than dropping them.
3. 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, usage snapshot, status) alongside normalized quantities.
4. 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) and MiB (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.