Documentation for Tutela v3.9.0.
AI usage and cost problems
Use this runbook when AI Spend shows missing usage, unpriced activity, failed imports or unexpected budget decisions. Separate a request that never reached Tutela from usage that was captured but could not be priced or persisted.
Prerequisites
- Permission to view AI Spend for the affected workspace.
- A request or usage-event ID, provider/model, time/timezone and the selected report filters.
- An operator for processing, storage or persistence failures.
Investigate
-
Open AI Spend and confirm workspace, selected time range and filters. Compare like-for-like periods; an operational health indicator may describe the last 24 hours while a report covers a different interval.
-
Find the request in Activity if it passed through Tutela. A provider bill can include direct traffic that Tutela never observed.
-
Read the displayed usage state. Missing records, missing token counts, missing price coverage and failed imports are separate problems; unknown cost is not zero cost.
-
Compare the model/provider and pricing coverage with the event's time. Keep estimated cost distinct from billed cost and do not add multiple breakdowns of the same usage together.
-
For import failures, inspect the import's error and source status before retrying. Preserve source identifiers so a retry can be checked for duplication.
-
Ask the operator to inspect analytics, broker and storage health when records are delayed. Follow Delayed activity processing for backlog diagnosis.
-
For external-usage persistence failures, inspect:
increase(tutela_external_usage_persistence_failed_total[5m])Group by the reported reason and correlate the usage-event ID. A provider response may already have returned even though usage persistence failed. Do not repeat the provider request simply to make a usage record appear.
Correct the cause
| Finding | Action |
|---|---|
| Wrong scope or period | Correct filters and compare the same event interval across views. |
| Request bypassed Tutela | Correct the application's connection, then test one new synthetic request. Keep earlier direct usage identified separately. |
| Usage captured but unpriced | Review provider/model price coverage; retain the unpriced state until supported pricing exists. |
| Import rejected or disconnected | Correct the stated source/format/connection issue, then retry the import and check source IDs for duplicates. |
| Processing backlog or failed persistence | Have the operator repair the failed dependency and reconcile known IDs. Do not manufacture replacement spend entries. |
| Unexpected budget block or allowance | Inspect the evaluated budget scope, period and decision. Use budget preview before changing enforcement. |
Record existing budget/provider/import settings before changing them. Restore an unsuccessful configuration change and repeat the same scoped test. Avoid disabling budget enforcement while diagnosing reporting.
Expected outcome and recovery
A new synthetic request has the expected usage state, model/provider and attribution, processing failures stop, and no duplicate entry appears. Reconcile the original affected IDs separately and record any unrecovered interval. A healthy latest request does not establish that old usage or charges were corrected.
Support handoff
Escalate failed persistence, unexplained duplicate charges/records, persistent missing usage or a budget decision inconsistent with its configured scope. Include IDs, times, filters, usage state, source/import status and redacted error details; exclude provider keys and prompt/output content.