Anatomy of a usage event
Every usage event is a structured data point composed of three primary elements. This structure ensures that activity is accurately attributed and available for complex calculations.- Customer identity (
customer_id): A unique identifier that links the event to a specific customer and their associated contract. - Temporal placement (
timestamp): A precise timestamp, recorded in DateTime64 format, indicating exactly when the activity occurred. This ensures usage is billed in the correct billing cycle. - Data payload (
data): A flexible JSON-like container for the actual usage details. This allows you to send any relevant key-value pairs required for your pricing logic, such asrequest_sizeorregion.
Event types
Zenskar ingests usage data in two distinct formats, depending on how your upstream systems track and report activity.- Granular usage events: Raw, individual units of activity. For example: “User A streamed 1 minute at 11:34 PM.” Zenskar performs the aggregation for these events at the end of the billing period.
- Pre-aggregated usage events: Pre-summarized activity from your infrastructure. For example: “User A streamed 1,000 minutes this month.” Useful when your source system already performs high-volume calculations before sending data to Zenskar.
Standard aggregation types
Usage events are not billed individually. Instead, Zenskar looks at the collection of events within a billing period and applies an aggregate function to derive a single billable metric.| Aggregate | Description | Example use case |
|---|---|---|
| SUM | Adds the values of all events in the period. | Total gigabytes transferred. |
| COUNT | Counts the number of events in the period. | Total API calls made. |
| MAX | Takes the highest value recorded in the period. | Peak concurrent users. |
| MIN | Takes the lowest value recorded in the period. | Minimum committed throughput. |
| UNIQUE COUNT | Counts the number of distinct values in the period. | Unique active users. |
Relationship to the product hierarchy
In the Zenskar data model, usage events serve as the input for the product defined within a phase.- The contract establishes that a customer is using a specific product.
- The product defines the price and the aggregate function to apply (e.g., “Sum of gigabytes”).
- The usage events provide the raw numbers.
- The billing engine calculates the final billable metric and generates the corresponding invoice line item.
Next steps:
- To learn how to move usage data from your systems to Zenskar, see the [Usage ingestion] concept page.
- For a technical breakdown of usage event fields, see the [Usage event API reference].