Skip to main content

Usage Metering

InfraSage meters your usage in real time, storing hourly event counts per tenant, per type.

How Metering Works​

Every event that passes validation and is written to ClickHouse increments the usage counter:

Event received → validation passes → write to raw_firehose → increment usage_metering

Failed validation records are sent to the DLQ and do not count toward your quota.

Metering Schema​

Usage is stored in infrasage_usage_metering:

ColumnTypeDescription
tenant_idstringTenant identifier
hourDateTimeRounded to the hour
event_typestringmetric, log, trace, event, profile, slo
event_countuint64Events ingested in this hour
bytes_ingesteduint64Raw bytes ingested (for cost attribution)

Querying Usage​

Last 24 hours by type​

SELECT
  event_type,
  sum(event_count) AS total_events,
  formatReadableSize(sum(bytes_ingested)) AS total_bytes
FROM infrasage.infrasage_usage_metering
WHERE tenant_id = 'acme-corp'
  AND hour > now() - INTERVAL 24 HOUR
GROUP BY event_type
ORDER BY total_events DESC

Monthly billing summary​

SELECT
  sum(event_count) AS total_events,
  formatReadableSize(sum(bytes_ingested)) AS total_bytes,
  round(sum(event_count) / 1000000, 2) AS millions_of_events
FROM infrasage.infrasage_usage_metering
WHERE tenant_id = 'acme-corp'
  AND hour >= toStartOfMonth(now())

Usage by service (via raw_firehose — slower, ad-hoc)​

SELECT
  service_id,
  count() AS events
FROM infrasage.infrasage_raw_firehose
WHERE tenant_id = 'acme-corp'
  AND timestamp > now() - INTERVAL 7 DAY
GROUP BY service_id
ORDER BY events DESC
LIMIT 20

API Usage Endpoint​

curl http://localhost:8080/api/v1/usage/breakdown \
  -H "Authorization: Bearer $ADMIN_JWT" \
  -G --data-urlencode "since=2026-04-01T00:00:00Z" \
     --data-urlencode "until=2026-04-10T00:00:00Z" \
     --data-urlencode "group_by=service_id"
{
  "period": {
    "start": "2026-04-01T00:00:00Z",
    "end": "2026-04-10T00:00:00Z"
  },
  "breakdown": [
    {"service_id": "payment-api", "events": 45000000, "bytes": 4500000000},
    {"service_id": "user-service", "events": 31000000, "bytes": 3100000000}
  ],
  "total_events": 142000000,
  "total_bytes": 14200000000
}

Usage Alerts​

Configure usage alerts so you're never surprised:

curl -X POST http://localhost:8080/api/v1/usage/alerts \
  -H "Authorization: Bearer $ADMIN_JWT" \
  -d '{
    "threshold_percent": 80,
    "notify_email": "billing@mycompany.com",
    "notify_slack": true
  }'

You can configure multiple thresholds (e.g., 50%, 80%, 95%) to get progressive warnings.

Byte Tracking​

In addition to event counts, InfraSage tracks raw bytes ingested per tenant per hour. This is used for:

  • Cost attribution in multi-team organizations
  • Capacity planning for ClickHouse storage
  • Enterprise billing for volume-based pricing

Byte counts reflect compressed bytes stored in ClickHouse, not raw HTTP request sizes.