Usage Events
What happened? When did it happen? Who did it happen to? What's important?
Usage Events capture information about things that happen in your API. They answer questions like what happened, how much did it happen, and who did it happen to. Usage events are at the core of usage-based billing.
Usage events are the basis of your billing and data infrastructure on Kable. They define how customers are invoiced and what metrics are displayed in your dashboards.
Usage Events
Kable usage events are flexible -- you can pass just about any data you want from your API into Kable. Events have a few required fields that help Kable attribute appropriately, but generally, the meat of an event is a flexible JSON payload.
| Name | API Field | Required | Description |
|---|---|---|---|
| Client ID | clientId | Yes | Identifies your customer to whom the event is associated. |
| Timestamp | timestamp | Yes | When the event occurred. Timestamps must be formatted as RFC 3339 strings. |
| Transaction ID | transactionId | No | A unique identifier for the event, used as an idempotency key for event deduplication. |
| Data | data | No | A JSON-formatted object containing usage data to be tracked by Kable. You may include as many key-value pairs as you like. Keys in the data payload correspond to the Dimensions you've defined. |
Recording Events
There are three ways to ingest usage events into Kable from within your API:
You can read more about each ingestion methodology in the pages the follow.
Event Idempotency
Kable uses the transactionId field on each event to ensure idempotence. If an event is received with a transactionId that has already been processed, Kable will discard the second (or third or fourth...) event as a duplicate.
Idempotency keys are a good way to ensure that you never double-record a metric. Each Kable library includes an optional transactionId field which you, the developer, can set on each event. Just be sure that you don't accidentally send the same idempotency key on events that should be considered unique. (UUIDs are usually a good pattern to ensure global uniqueness of event transactionIds.)
Querying Events
Events form the basis of your usage data on Kable. This data is leveraged in several places:
- The Kable billing engine uses events when calculating usage-based invoices
- Your dashboard shows usage metrics based on the events you record
- Any embedded dashboards you add to your customer portal are based on usage events
- You can query your events directly using SQL from the dashboard
- You can download reports based on events to dig into trends in product usage
Updated 5 months ago