Skip to main content

Designing billable metrics

This document takes a deeper look at Metronome's concept of billable metrics, which aggregate customer usage. Billable metrics are tracked continuously as usage enters the system, so they can power real-time usage dashboards and alerting. They also form the basis for pricing.

Aggregating usage

Usage enters the system in the form of usage events, which are covered in the Getting usage data into Metronome guide.

An example web hosting company might have two types of usage events: one for each incoming HTTP request and one for an hourly snapshot of disk usage. The rest of this document will use these example events:

[{
"transaction_id": "...",
"customer_id": "...",
"timestamp": "...",
"event_type": "page_load",
"properties": {
"region": "US-East",
"url": "https://www.example.org",
"status": "200",
"bytes": "648"
}
},
{
"transaction_id": "...",
"customer_id": "...",
"timestamp": "...",
"event_type": "hourly_snapshot",
"properties": {
"bytes": "104857600"
}
}]

A billable metric describes a per-customer aggregation over a subset of usage events. The following would be reasonable billable metrics to build on top of these usage events:

  • number of page hits: count for page_load events
  • total amount of data transferred: sum of properties.bytes for page_load events
  • maximum data on disk: max of properties.bytes for hourly_snapshot events

As in this example, it's common for a single usage event to be the basis for multiple billable metrics. Each metric specifies an aggregator and, with the exception of count, a single property to aggregate over. Metronome currently supports the following aggregators: count, sum, max, and unique (which counts the number of unique values).

Flexible event filtering

In the preceding example, each billable metric applied to all events with a given event_type. It can sometimes be useful to define more complex filters. Perhaps our example web hosting company only wants to track data transfer for successful HTTP requests. The following updated billable metric would support this:

sum of properties.bytes for page_load events where properties.status is 200

For now, you'll need to work with a Metronome engineer to set up your billable metrics. They can guide you on what type of filtering is possible.

Grouped metrics

When defining a billable metric, you can also specify one or more properties the metric should be grouped by. This functions similarly to a group by clause in a SQL query. Grouping a metric by a property does not affect pricing, but the grouping is available in the /usage API endpoint, and it can be used to alter the appearance of products on an invoice.

Continuing the web hosting example, grouping by the region property would support giving customers a breakdown of how each region contributed to their overall traffic, as in the following example API request and response:

POST /v1/customers/<customer ID>/billable-metrics/<metric ID>/usage HTTP/1.1
Host: api.metronome.com
Authorization: Bearer TOKEN
Content-Type: application/json

{
"starting_on": "2021-01-01T00:00:00Z",
"ending_before": "2021-01-15T00:00:00Z",
"window_size": "day",
"group_by": {
"key": "region",
"values": ["US-East, US-West, EU-Central"]
}
}
HTTP/1.1 200 OK
Content-Type: application/json

{
"data": [
{
"start_timestamp": "2021-01-01T00:00:00+00:00",
"end_timestamp": "2021-01-02T00:00:00+00:00",
"value": 1234,
"groups": {
"EU-Central": 0,
"US-East": 789,
"US-West": 445
}
},
{
"start_timestamp": "2021-01-02T00:00:00+00:00",
"end_timestamp": "2021-01-03T00:00:00+00:00",
...
},
...
]
}

For performance reasons, we recommend having no more than 100 unique values for a property you're grouping by.

Next steps

If you haven't already, read Getting usage data into Metronome to see how to make sure the usage events you're sending Metronome support the billable metrics you want to define. Work with your Metronome representative to create your billable metrics and start aggregating usage.

Once your billable metrics are created, you can use them to configure products and pricing.