Cost tracking per request, user, feature and tenant

Read these first

• Token counting and budgeting before the call

What you will know

• Attribute the cost of a single request to a user, a feature, and a tenant

  A single user action may fan out through retries, tools, and model calls, so correlation IDs and immutable pricing snapshots are needed to avoid orphaned spend.

• Report the cost of a feature over the last week without writing a new query

  A time-bucketed fact table lets dashboards answer historical questions without reconstructing traces or relying on mutable rate cards.

• Separate input, output, cached, and reasoning tokens in the accounting

  Provider invoices and rate cards may price these categories differently, and collapsing them hides both caching mistakes and reasoning-cost spikes.

• Instrument a fan-out workflow and show why attribution must exist before the system grows

  Retries, delegated agents, and asynchronous work erase ownership boundaries once the original request context is gone.

• Spot a cost regression from the metric rather than the invoice

  A per-feature baseline and alert threshold can expose a rate or token-shape change before billing data arrives.

Chapters

1. 1

   Pricing a call at write time

   A cost row that stores token counts and joins to a mutable price table computes what last quarter's traffic would cost today, not what it cost. This chapter defines the cost ledger and the rate card, shows the schema that silently reprices history when a provider changes a price, and works through writing the applied unit price onto the row — including what to do when the model that served the request has no rate in force.

   Read chapter
2. 2

   Grouping calls under a correlation id

   One click can produce a planner call, five parallel sub-agents, two retries and an asynchronous summariser landing forty seconds after the response went back, and rows carrying user, model, tokens and a timestamp cannot be grouped into that unit. This chapter shows why grouping by user and time window fails in one direction, how an identifier minted at the entry point propagates through retries, delegations and queue hops, and which four identifier fields answer which four questions.

   Read chapter
3. 3

   Token categories and their rates

   A model call returns four token counters and they carry four different prices, spread fifty to one within a single model. A cost row that stores one total and multiplies by a blended rate reproduces today's spend exactly and stays flat through the two most common regressions — work shifting from input into output, and a cached prefix that stops being reused. This chapter gives the rates by category, the TTL arithmetic behind cache writes, and why the counts have to be stored alongside the money.

   Read chapter
4. 4

   Spend reconciliation and the residual

   A client timeout abandons a generation that keeps decoding, a cancelled stream bills what it already produced, an SDK retries below your wrapper, and a stream that errors mid-flight reports no usage at all — four ordinary ways a billed call leaves no row. This chapter covers writing a row from a finally block with an explicit status, the scheduled comparison against the provider's per-model totals, and carrying the difference as an alerted unattributed-spend line rather than dropping it.

   Read chapter
5. 5

   The cost fact table

   One row per model call, written at call time, carrying the dimensions you slice by and the measures you add up, turns every spend question into a group-by instead of a fresh export from application logs. This chapter sets the grain, gives the schema and its indexes, covers snapshotting dimensions that can change out from under a report, and compares the design against the cheaper alternative of one provider API key per feature.

   Read chapter
6. 6

   Unit-cost alerting per feature

   A nine-word instruction change can add twenty-one percent to a feature's unit cost while total spend, tokens per request, latency and blended cost per request all stay inside their thresholds. This chapter builds the metric that does fire — cost per action for one feature against that feature's own hour-of-day baseline, with token categories broken out — chooses between the three available denominators, and pairs it with the reconciliation residual so a flat dashboard and a rising invoice cannot coexist.

   Read chapter
7. 7

   Attribution as write-time plumbing

   Adding tenant and feature attribution six months after launch is expensive rather than merely late: the identifying context is no longer in scope where the call happens, so every call site, retry path and queue consumer has to be re-plumbed, and the spend already recorded stays unattributable forever. This chapter separates the write-side decisions that must ship before launch from the read-side work that can wait, and gives the four queries that test the plumbing in its first week.

   Read chapter