feat(usage): rename metrics → tokens_embedded/pages_embedded + export token cost to Prometheus

Billing product model finalized (Deck #281): bill pages externally, record
tokens internally. Rename the data-plane metric literals to match the now-
canonical contract (Deck #284) — the control plane's METRIC_EVENT_NAMES is
already renamed, so the old names would be unmapped and never sync to Stripe.

Rename (values unchanged):
- embeddings_queries → tokens_embedded (value = real token count, already
  emitted by this PR; the unit upstream providers bill on).
- pages_chunks → pages_embedded (value kept as len(chunk_texts) interim;
  TODO(#282): real normalized "pages indexed" count — real pages for paginated
  types, chars/tokens-per-page constant otherwise — is deferred to the
  instrumentation card, this only lands the name/contract).
- All literals, log strings, docstrings, comments, the migration comment, and
  tests renamed; grep confirms zero old strings remain.

Observability (new): export embedding token cost to Prometheus as
astrolabe_embedding_tokens_total{provider,operation} (operation = index|query)
so the billed cost unit is visible in Grafana, not just the per-tenant billing
DB. Dedicated counter (doesn't inflate the existing chunk/request metrics) and
always-on (independent of USAGE_METERING_ENABLED, so OSS/self-host gets it).
Wired on both the indexing batch embed and the search query embed (query inside
the per-request cache-miss branch, so reused embeddings aren't double-counted).

Note: the rename orphans any pre-existing embeddings_queries/pages_chunks rows
in tenant app DBs (CP no longer maps them) — acceptable; pipeline is inert with
throwaway dev/sandbox data.

Deck #284 (folded into PR #875).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
Chris Coutinho
2026-06-08 13:17:53 +02:00
co-authored by Claude Opus 4.8
parent ddefb03701
commit 973f80e7b9
15 changed files with 129 additions and 45 deletions
+5 -5
View File
@@ -1,7 +1,7 @@
"""Unit tests for the indexing-path usage-metering helper (Deck #67).
``record_indexing_usage`` records the two billable events (``pages_chunks`` +
``embeddings_queries``) after a document's chunks are embedded. These cover the
``record_indexing_usage`` records the two billable events (``pages_embedded`` +
``tokens_embedded``) after a document's chunks are embedded. These cover the
value mapping, the flag/zero-chunk no-ops, and the best-effort failure path
without standing up the full document pipeline.
"""
@@ -25,8 +25,8 @@ def store_spy(monkeypatch):
@pytest.mark.unit
async def test_records_pages_chunks_and_token_count(store_spy):
"""Both events fire: pages_chunks = chunk count, embeddings_queries = tokens."""
async def test_records_pages_embedded_and_token_count(store_spy):
"""Both events fire: pages_embedded = chunk count, tokens_embedded = tokens."""
await processor.record_indexing_usage(
enabled=True,
provider="mistral",
@@ -40,7 +40,7 @@ async def test_records_pages_chunks_and_token_count(store_spy):
calls = store_spy.record_usage_event.await_args_list
by_metric = {c.kwargs["metric"]: c.kwargs["value"] for c in calls}
assert by_metric == {"pages_chunks": 110, "embeddings_queries": 4242}
assert by_metric == {"pages_embedded": 110, "tokens_embedded": 4242}
for c in calls:
# Hot-path fast-gate + tenant-local attribution metadata.
assert c.kwargs["enabled"] is True