Core Concepts
Usage & Metering
How entitlement usage is tracked, reported, and monitored.
Usage & Metering
Kaiten tracks entitlement usage per instance, allowing you to monitor consumption against license thresholds.
How Usage Works
- An instance is linked to a license with entitlements and threshold values
- Your application reports usage via the API
- Kaiten stores the current consumption in
entitlement_usage - When usage reaches the threshold, an
INSTANCE_ENTITLEMENT_USAGE_REACHEDevent is emitted
Reporting Usage
POST /api/instances/{instanceSlug}/entitlements/{entitlementSlug}/usage{"value": 42}The reported value is aggregated according to the entitlement's aggregation_method (SUM, COUNT, AVERAGE, MAX, MIN, LATEST).
Usage Value Shape
Usage is stored as structured JSON:
{
"type": "number",
"value": 42,
"event_count": 5
}| Field | Description |
|---|---|
type | Always "number" |
value | Current aggregated value |
event_count | Number of usage reports received |
Feature Audit Trail
Kaiten maintains an append-only audit trail for entitlement operations on each instance:
| Event | Status | Description |
|---|---|---|
kaiten.v1.entitlement.value.get | ACCEPTED | An entitlement value was read |
kaiten.v1.entitlement.usage.report.accepted | ACCEPTED | Usage report was accepted (below threshold) |
kaiten.v1.entitlement.usage.report.rejected | REJECTED | Usage report was rejected (above threshold) |
Querying the Audit Trail
GET /api/instances/{instanceSlug}/audit-trails?event_name=kaiten.v1.entitlement.usage.report.accepted&limit=50Filter parameters: event_name, after, before (RFC3339), limit (1-200), offset.
Audit Trail vs Domain Events
| Aspect | Feature Audit Trail | Domain Events (Outbox) |
|---|---|---|
| Purpose | Track entitlement reads/reports per instance | Track CRUD mutations across all entities |
| Storage | feature_audit_trail table | outbox_events table → CDC → webhooks |
| Scope | Per instance, per entitlement operation | Per organization, per entity type |
| Delivery | Queried via REST/GraphQL | Delivered via webhooks (Svix) |
See It in the Console
The Instance detail page in the Console shows live entitlement usage charts, per-entitlement consumption vs threshold, and the full audit trail with filters and event inspection.