Guides
Entitlement Metering
Deep dive into NUMBER entitlements, meter types, aggregation, and threshold alerts.
Entitlement Metering Guide
This guide covers advanced metering patterns with NUMBER entitlements.
Meter Types
| Meter Type | Description | Use Case |
|---|---|---|
CALCULATED_USAGE | Kaiten calculates usage from reported events | API calls, data storage |
RAW_EVENT | Each report is an individual event | Transaction records |
Aggregation Methods
| Method | Description | Example |
|---|---|---|
SUM | Total of all reported values | Total API calls |
COUNT | Number of events | Number of logins |
AVERAGE | Average of reported values | Average response time |
MAX | Highest reported value | Peak concurrent users |
MIN | Lowest reported value | Minimum SLA uptime |
LATEST | Most recent value | Current storage used |
Reporting Usage
POST /api/instances/{instanceSlug}/entitlements/{entitlementSlug}/usage{"value": 42}Each report updates the aggregated usage value based on the entitlement's aggregation method.
Threshold Alerts
When usage reaches the configured threshold, Kaiten emits:
INSTANCE_ENTITLEMENT_USAGE_REACHEDSubscribe to this event via webhooks to trigger:
- Email notifications to your sales team
- In-app upgrade prompts
- CRM pipeline updates
- Automated billing adjustments
Patterns
Per-Request Metering
Report usage on every API call from your customer's instance:
// In your API middleware
kaiten.ReportUsage(ctx, "acme-production", "api-calls", 1)Batch Metering
Aggregate usage locally and report periodically:
// Every hour
kaiten.ReportUsage(ctx, "acme-production", "api-calls", hourlyCount)Gauge Metering (LATEST)
For metrics like "current storage used", use LATEST aggregation:
kaiten.ReportUsage(ctx, "acme-production", "storage-gb", currentStorageGB)