Set up billable metrics

Billable metrics aggregate customer usage and form the basis for pricing. They are tracked continuously as usage enters the system to power real-time usage dashboards and alerting.

caution

You cannot edit billable metrics.

Aggregate usage

Usage enters the system in the form of usage events, which are covered in Design usage events.

For example, a 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 guide uses 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. Here are example billable metrics to build on top of these usage events:

• number of page hits, COUNT() with the filter event_type in ("page_load")
• total amount of data transferred, SUM(properties["bytes"]) with the filter event_type in ("page_load")
• maximum data on disk, MAX(properties["bytes"]) with the filter event_type in ("hourly_snapshot")

As in this example, it's common for a single usage event to act as 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(), count the number of events that match the filters for the metric.

• SUM(property), sum the values of the given property for all events that match the filters for the metric.

• MAX(property), find the maximum value of the given property for all events that match the filters for the metric.

• UNIQUE(property), count the number of unique values of the given property for all events that match the filters for the metric.

  Calculating unique values

  There are two ways Metronome can compute unique values:

  • By default, Metronome computes unique values by using a highly tuned probabilistic data structure. This method enables a highly efficient calculation of unique values. In practice, the accuracy of this data structure is within +/- 1.3% of the actual value.
  • Metronome also supports calculating exact unique counts for finalized invoices. If you are interested in using this calculation method, please contact your Metronome representative.

Flexible event filtering

Event filters provide a mechanism to determine which events should be associated with a billable metric. In the preceding example, each billable metric applied to all events with a given event_type. You can also add property filters. For example, a billable metric tracking data transfer per region might require that the region property exists.

Case-sensitive

Keys and values are case-sensitive.

You may also define more complex filters. If the example web hosting company only wants to track data transfer for successful HTTP requests, the following updated billable metric would support this:

SUM(properties["bytes"]) with the filters event_type in ("page_load") and properties["status"] in ("200")

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 /getUsage endpoint, and 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",
      ...
    },
    ...
  ]
}

Grouped metric availability

If you are interested in using grouped metrics, please contact your Metronome representative.