System design
How FluxMeter turns model usage into customer-level lines — and what stays outside the system boundary.
FluxMeter meters and attributes AI usage. It is not a complete invoice, CRM, or warehouse platform.
Non-goals include replacing your billing product of record, inventing customer acquisition metrics, and shipping unqualified performance claims on this site.
Single supported path: SDK/Gateway → HTTP Custody → Kafka acknowledgement → Flink billing and aggregation → Redis query state → Usage API.
make demo starts this stack. HTTP ingest returns 202 only after Kafka acknowledgement; when Kafka is unavailable, ingest returns a retryable 503. Flink is the billing and aggregation engine. ClickHouse may be added as an audit cold store — it is not billing truth.
Supported path
make demo starts the only supported full stack. ClickHouse is an audit cold store — not billing truth.
Local HTTP measurements: 291.20 events/s (single-event) and 14,006.89 events/s (batch 1,000, concurrency 10) — local only, not product guarantees. 10K/100K release gates remain unmet. Engine 4.4.1. Python/JS SDK 2.0.0 are repository versions — package-index publication not reverified.
Gateway orchestration: estimate → gate → reserve → upstream → Custody, with a Redis outbox for durable handoff.
The same Usage API surface applies whether traffic enters through the SDK or the Gateway. Intelligence remains a heuristic, secondary layer on metered rollups.
Ingest uses camelCase fields such as customerId, modelId, inputTokens, and outputTokens.
Usage queries return snake_case lines such as customer_id, period, tokens, and cost_usd.
Authoritative order: Ingest → Price → Attribute → Control (optional) → Export (optional).
Pricing uses model catalog rates; attribution writes the customer-level ledger line.
Optional prepaid control: check before a call, reserve an estimate for streams, reconcile when tokens are known.
These APIs sit beside metering — they are not required to produce a usage line.
Dedup relies on stable event identifiers at the application boundary.
Treat delivery as application-level effectively-once — do not claim stronger sink guarantees without evidence.
Operators choose how gateway and budget failures surface to callers (block vs soft fail) for their product.
Demo environments may leave auth optional; production exposure requires API keys.
The supported stack always includes HTTP Custody, Kafka, and Flink — operational cost is inherent to the only customer event path.
Local HTTP measurements (291.20 / 14,006.89 events/s) are environment-qualified, not product guarantees; 10K/100K release gates remain unmet. See engine load-testing docs.
Identity mapping, pricing catalog maintenance, billing product choice, and production auth posture stay with you.
Revenue overlays and Intelligence APIs are heuristic helpers on metered data — not a finance system of record.
Go deeper