Skip to main content

Billable Metrics

Measure and track user usage and consumption.

Billable metrics operate on a per-buyer basis and provide the foundational data for billing.

Instead of reflecting the resultant charge (e.g., $0.10 for 10 API calls at $0.01 each), they count or aggregate usage units (e.g., 10 API calls).

Definition​

A billable metric is defined by the following properties:

  • ID: Unique identifier for the billable metric. If omitted, the system generates one.
  • Name: The display name of the billable metric.
  • Description: A description for reference.
  • Filter Groups: Criteria for determining which events should contribute to the metric.
  • Aggregation Type: Defines how the selected events are aggregated.
  • Property Unique On: Used for distinct counts when the aggregation type is UNIQUE COUNT.

Filter Groups​

Filter groups allow users to specify which events affect the metric. Each filter group consists of one or more filters. The filters are combined using the logical OR operator, and the filter groups are combined using the logical AND operator.

Filters are based on the properties of the event. The following filters are supported:

  • For string properties: is, not is, contains, not contains, exists, not exists.
  • For numeric properties: greater than, greater than equal, less than, less than equal, equal, not equal.

Aggregation Types​

Aggregation types define how consumption is measured.

Aggregation TypeDescriptionExample
COUNTCount the numbers of events matching filter groups.COUNT(meteringUsageRecordGroup.metaInfo.billableRecords[index].key) WHERE filters
UNIQUE COUNTCount distinct values of a specified property.COUNT_DISTINCT(meteringUsageRecordGroup.metaInfo.billableRecords[index].properties[propertyUniqueOn]) WHERE filters
SUMSum the values of a specified property.SUM(meteringUsageRecordGroup.metaInfo.billableRecords[index].quantity) WHERE filters
MAXRetrieve the maximum value of a property.MAX(meteringUsageRecordGroup.metaInfo.billableRecords[index].quantity) WHERE filters
LATESTRetrieve the most recent value of a property.LAST_VALUE(meteringUsageRecordGroup.metaInfo.billableRecords[index].quantity) WHERE filters

UNIQUE COUNT​

For unique count metrics, the property to count must be specified via propertyUniqueOn when create. The distinct counting process involves three levels of aggregation.

Calculation Logic:

  1. In hourly report aggregation, we only save the new added property values.
  • Aggregate the target property values of all record groups in this hour.
  • Read all target property values of the previous hours today from db.
  • Remove data from current hourly result that already exist in the previous hours results.

  1. In daily report aggregation, we just need to concat the result of 24 hourly reports, because each of them only keep the new values. We only keep the distinct count of values in the daily report, not the raw values array.

  2. In usage invoice generate, we aggregate all hourly reports data.

  • Read all hourly reports in the invoice period.
  • Aggregate hourly reports to daily reports. In this step, we just need to concat values of all hourly reports. We keep the concated array in memeory temporarily for daily reports aggregation.
  • Aggregate daily reports. In this step, we merge values of all daily reports to get the final distinct count. After get the final count, delete the source array kept in daily reports to forbid they are saved to the db.
  • Calculate fee by the final count.

E2E Testing Plan​

  1. Count metric with filters.
ID: api_call
Name: API Call
Description: Count the number of API calls.
Filter Groups:
  - Filters:
    - Property: api
      Operator: is
      Value: /api/v1
Aggregation Type: COUNT
  1. Unique count metric with filters.
ID: api_call_by_cluster
Name: API Call by Cluster
Description: Count the number of unique API calls by cluster.
Filter Groups:
  - Filters:
    - Property: api
      Operator: is
      Value: /api/v1
Aggregation Type: UNIQUE COUNT
  1. Sum metric with filters.
ID: network_traffic
Name: Network Traffic
Description: Sum the network traffic.
Filter Groups:
  - Filters:
    - Property: region
      Operator: is
      Value: east
    - Property: protocol
      Operator: is
      Value: tcp
Aggregation Type: SUM
  1. Max metric without filters.
ID: cpu_usage
Name: CPU Usage
Description: Get the maximum CPU usage.
Filter Groups: []
Aggregation Type: MAX
  1. Latest metric with filters.
ID: <empty>
Name: <empty>
Description: <empty>
Filter Groups:
  - Filters:
    - Property: region
      Operator: is
      Value: east
Aggregation Type: LATEST