cost-attribution

Files (3)

• SKILL.md
• SKILL.md.bundle
• SKILL.md.sig

SKILL.md (first lines)

# Cost Attribution

> Per-tenant cost attribution from day one. Cryptographically signed audit
> trail.

**Tradeoff:** Every billable op needs a ledger entry. Worth it: client
invoicing is automatic, surprise bills are caught early, and cost-by-feature
guides optimization.

---

## How it works

DevOPs ships two pieces of this: the Stratum `billing_records` ledger and the
budget caps below. The exporter, the report command and the anomaly job on
this page are the design to build in each project; none of them exists in
DevOPs yet.

1. OTel baggage carries `tenant.id` and `user.id` on every span.
2. LLM calls auto-add `cost_usd` via OpenInference instrumentation.
3. The cost-attribution exporter aggregates costs by `tenant.id` per hour.
4. Aggregates are written to:
   - File: `.workflow/state/cost-ledger.jsonl` (per-project)
   - Stratum: `billing_records` table (HMAC-signed, append-only) if configured
5. A report command (not yet built; see Reports below) summarizes the ledger.

---

## Ledger entry shape

```json
{
  "ts": 1716372013,
  "tenant_id": "client-abc",
  "user_id": "user-123",
  "session_id": "s-7f3a",
  "operation": "llm.call",
  "provider": "anthropic",
  "model": "claude-sonnet-4-6",
  "input_tokens": 1234,
  "output_tokens": 567,
  "cost_usd": 0.0122,
  "hmac": "sha256:..."  // Stratum signs server-side
}
```

---

## Reports

Example monthly report for one client (illustrative figures; the `devops`
CLI has no `cost-report` command yet):

```
Client: client-abc
Period: 2026-05-01 to 2026-05-31

Total spend:        $124.37
By provider:
  Anthropic:        $118.42
  OpenAI:             $5.95
By model:
  claude-opus-4-7:   $42.18  (12% of calls)
  claude-sonnet-4-6: $63.71  (44% of calls)
  claude-haiku-4-5:  $12.53  (44% of calls)
By feature:
  /api/auth:         $34.21
  /api/payments:     $18.42
  /api/search:       $71.74
Cost per session:   avg $0.34, p95 $1.21
Cost per request:   avg $0.0023, p95 $0.012
```

---

## Hard caps integration

`hooks/universal/pre-tool/budget-brake.sh` enforces the caps in
`.workflow/state/budget.yml` against its own ledger,
`.workflow/state/budget-ledger.jsonl` (not the cost ledger above):

- Per-session cap (default $5)
- Per-hour cap (default $20)
- Per-day cap (default $100)

When a cap is hit, the hook exits 2 and the tool call is blocked; the agent
cannot override it. It runs only once the harness registers it as a
PreToolUse hook (for Claude Code, in `.claude/settings.json`).
`analyzer/install.ts` copies the script without registering it, so check the
settings before relying on the cap.

---

## Anomaly detection

A daily anomaly job (not yet built) should flag:
- Day-over-day spend > 3x weekly average
- Per-client spend exceeding contract terms
- Calls with token counts > 90th percentile (potential prompt bloat)

It should write anomalies to `governance/telemetry/cost-anomalies.jsonl`.

---

## Anti-patterns

**Tagging by session only**: lose per-feature breakdown. Always include
endpoint or skill name in span attributes.

**No HMAC**: ledger entries can be tampered. Always sign server-side.

**No retention policy**: ledger grows unbounded. Roll up to monthly aggregates
after 90 days; archive raw to cold storage.

---

**This skill is working when:** client invoices reconcile to ledger entries
exactly, and cost-anomaly alerts fire before manual review notices the spike.

From MILTONADINA/DevOPs, MIT.

More from MILTONADINA/DevOPs