Metering
Usage metering and report.
After the entitlement is created, you can report metric usage data to Suger in real time. Suger will regularly aggregate the reported data, and calculate the amount to be paid for the current invoice period when issuing the invoice.
Report usage to Suger
Use the following APIs to submit usage data.
Request body example:
{
"ID": "request uuid", # Optional, if not provided, suger will generate one and return in the response.
"organizationID": "your-suger-org-id",
"entitlementID": "your-suger-entitlement-id",
"billableRecords": [
{
"key": "billable-metric-id-of-the-entitlment's-billable-dimension",
"properties": {
"custom-property-1": "val1",
"custom-property-2": "val2"
},
"quantity": 10, # The num of the metric.
},
...
]
}
The reported usage data can be viewed on the entitlement details page.
Usage hourly report
Suger aggregates usage data every hour, according to each entitlement and metric.
- Each aggregation only processes data from the previous hour.
- Some usage data may be filtered out based on the filter conditions of the billable metric.
- After the hourly aggregation is completed, these usage data will be marked as reported.
- Hourly reports only aggregate the quantity of metrics and do not calculate the corresponding amount.
Aggregate logic
How to aggregate depends on the aggregation type selected when the billable metric was created.
| Billable metric aggregate type | Hourly report aggregate logic |
|---|---|
| COUNT | The number of reports within the hour |
| UNIQUE COUNT | The unique count of the specified property's values in reports within the hour |
| SUM | The sum of the quantity of reports within the hour |
| MAX | The maximum value of the quantity of reports within the hour |
| LATEST | The most recent value of the quantity of reports within the hour |
Billable metric with groupby
If the billable metric is configured with the groupby attribute, the usage data will first be divided into multiple groups and then aggregated separately according to the aggregation type.
Unique count aggregate
When the aggregation method is set to unique count, the calculation will be more complicated.
- First, we will remove duplicates from the target attribute values within that hour and obtain an array.
- Then we will read all array in previous hourly reports today and remove duplicates from the array of the current hour.
- Afterwards, we will obtain the unique count of the newly added value of this attribute within this hour.
The purpose of this design is that the data stored per hour is incremental data and has been deduplicated. This allows for the calculation costs to be shared in terms of both computation and storage per hour.
In the subsequent daily report and invoice amount calculation, we can directly use the hourly report result.
The hourly reports can be viewed on the entitlement details page.
Usage daily report
Suger automatically generates the daily usage record report every day.
The daily report is aggregated from the results of all the hourly reports within today.
| Billable metric aggregate type | Hourly report aggregate logic |
|---|---|
| COUNT | The sum of all hourly report counts |
| UNIQUE COUNT | The sum of all hourly report unique counts |
| SUM | The sum of all hourly report sum results |
| MAX | The largest value in all hourly report results |
| LATEST | The value of the last hourly report result |
The daily reports can be viewed on the entitlement details page.
Calculate usage invoice fee
When entitlement generates a usage invoice, Suger will calculate the quantity of billable metrics configured in this entitlement during the invoice period. The source of the calculation data is the hourly reports rather than the original reported data, as the hourly report has already been aggregated.
- First, calculate the aggregated daily quantity of each billable metric within the invoice period based on the hourly report.
- Then calculate the final aggregated quantity of each billable metric based on daily aggregated data.
- Finally, we calculate the final fee amount based on the quantity according to the price model of each billable metric.
If a billable metric is configured with groupbys, the hourly and daily aggregation results, as well as the total quantity, will be calculated for multiple results based on the combination of the groupby attributes. These quantities will be calculated as amounts based on the price model, and the sum of them will be the final amount.