Metering architecture

Usage metering is the core — and only required — component of every BYOC deployment. This page describes how usage events flow through the BYOC metering service and how current usage is served to your application.

​

Event ingestion

Your application reports usage events to the BYOC metering endpoint using the same Stigg SDK or API calls you use today — only the endpoint URL changes. The metering service accepts:

• Single events
• Batches of up to 1,000 events per request
• Parallel reporting from multiple distributed services without coordination

Events are written to a durable local buffer immediately upon receipt. The SDK call returns once the event is durably buffered — before aggregation completes. This gives you fast acknowledgment without sacrificing durability.

​

Throughput

The BYOC metering service is designed to sustain up to 1,000,000 usage events per second. This is achieved through:

• Stateless, horizontally scalable ingestion layer
• Kafka as the durable, high-throughput event buffer between ingestion and aggregation
• Flink for real-time stream processing and per-customer usage aggregation
• ClickHouse as the columnar store for fast usage queries and durable event retention

For comparison, Stigg Cloud supports up to 1,000 events/sec per account. BYOC removes this constraint for enterprise-scale workloads.

​

Aggregation and current usage

Ingested events are aggregated in real time to maintain a running current usage total per feature per customer. This aggregated value is what the SDK reads when checking entitlements or current usage — not the raw event stream. The aggregation pipeline:

1. Events land in Kafka (durable buffer in your cluster)
2. Flink consumes events in micro-batches and updates per-customer usage counters in ClickHouse
3. Aggregated usage counters are cached in a low-latency store for fast reads
4. The entitlement check path reads from this store — typical read latency is sub-millisecond

​

Idempotency

The BYOC metering service inherits Stigg’s built-in idempotency guarantees. Duplicate events (identified by event ID) are discarded at the buffer layer, before aggregation. Reporting the same event twice does not double-count usage.

​

Billing rollups

Aggregated usage totals are periodically rolled up and sent to Stigg Cloud. Raw events are not transmitted — only the counters required to compute billing. Rollup frequency and format are configured during provisioning.

​

Durable event storage

All raw usage events are stored in their original format in ClickHouse within your cloud environment. This allows you to:

• Audit raw event data
• Reprocess events if aggregation logic changes
• Rebuild usage totals from scratch if needed

​

Cold-tier archival

Older events are tiered to cold storage in your own object store (S3, GCS, or Azure Blob) under your configured retention policy, encrypted by your own KMS keys. Stigg does not access or read this cold-tier data. Raw event data is retained according to the retention policy configured during provisioning.