Skip to main content

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​

  1. 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.

  2. Find the request in Activity if it passed through Tutela. A provider bill can include direct traffic that Tutela never observed.

  3. 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.

  4. 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.

  5. For import failures, inspect the import's error and source status before retrying. Preserve source identifiers so a retry can be checked for duplication.

  6. Ask the operator to inspect analytics, broker and storage health when records are delayed. Follow Delayed activity processing for backlog diagnosis.

  7. 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​

FindingAction
Wrong scope or periodCorrect filters and compare the same event interval across views.
Request bypassed TutelaCorrect the application's connection, then test one new synthetic request. Keep earlier direct usage identified separately.
Usage captured but unpricedReview provider/model price coverage; retain the unpriced state until supported pricing exists.
Import rejected or disconnectedCorrect the stated source/format/connection issue, then retry the import and check source IDs for duplicates.
Processing backlog or failed persistenceHave the operator repair the failed dependency and reconcile known IDs. Do not manufacture replacement spend entries.
Unexpected budget block or allowanceInspect 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.

Next steps​