Dimensions grouping
Grouping with a single key
Consider the following example:
Your company provides DevOps services and you want to charge your customers for compute capacity by the hour.
In your Lago account, you create a compute
billable metric that calculates
the total number of hours (i.e. SUM(properties.hours)
).
As your customers can choose from different cloud providers, you need to group usage records (i.e. events) according to the provider.
On the configuration page of your billable metric, you can define
"key": "provider"
and "values": ["AWS","Google","Azure"]
to create the
corresponding dimension (see snippet below).
Dashboard
API
- Create a new billable metric;
- Click and expand the section Define groups in this billable metric; and
- Add groups following the JSON structure below.
{
"key": "provider",
"values": ["AWS", "Google", "Azure"]
}
Below is an example of an event with a single group for the billable metric described above:
LAGO_URL="https://api.getlago.com"
API_KEY="__YOUR_API_KEY__"
curl --location --request POST "$LAGO_URL/api/v1/events" \
--header "Authorization: Bearer $API_KEY" \
--header 'Content-Type: application/json' \
--data-raw '{
"event": {
"transaction_id": "event_001",
"external_customer_id": "customer_1234",
"code": "compute",
"timestamp": 1668461043,
"properties": {
"hours": 0.07,
"provider": "Azure"
}
}
}'
Values are case-sensitive. If you don’t use the exact value when pushing
events, they will not be taken into account. Following our example: the
expected value is "Azure"
and "azure"
is an invalid value.
Grouping with two keys
It is also possible to define two levels for grouping events. Following our previous example:
In addition to their cloud provider, your customers can select their region.
Therefore, you can define "key": "region"
to add a second dimension (see
snippet below).
When creating a plan, you will then be able to add a charge for each region available for each provider.
Dashboard
API
- Create a new billable metric;
- Click and expand the section Define groups in this billable metric; and
- Add groups following the JSON structure below.
{
"key": "provider",
"values": [
{
"name": "AWS",
"key": "region",
"values": ["Europe", "Africa", "Asia"]
},
{
"name": "Google",
"key": "region",
"values": ["Europe", "North America"]
},
{
"name": "Azure",
"key": "region",
"values": ["North America", "Asia"]
}
]
}
Below is an example of an event including two group values for the billable metric described above:
LAGO_URL="https://api.getlago.com"
API_KEY="__YOUR_API_KEY__"
curl --location --request POST "$LAGO_URL/api/v1/events" \
--header "Authorization: Bearer $API_KEY" \
--header 'Content-Type: application/json' \
--data-raw '{
"event": {
"transaction_id": "event_002",
"external_customer_id": "customer_1234",
"code": "compute",
"timestamp": 1668461044,
"properties": {
"hours": 0.13,
"provider": "AWS",
"region": "Europe"
}
}
}'
You can also create billable metrics with dimensions via the API.
Edit dimensions
You can edit billable metric groups associated with existing subscriptions. It’s important to note that making changes to these metric groups can have an impact on all plans where this billable metric is defined as a charge. Here’s an example to illustrate the impact of editing a billable metric:
From Payload A:
{
"billable_metric": {
"name": "gigabyte",
"code": "gigabyte",
"aggregation_type": "sum_agg",
"field_name": "total",
"group": {
"key": "region",
"values": [
"usa",
"europe",
]
}
}
}
To Payload B:
{
"billable_metric": {
"name": "gigabyte",
"code": "gigabyte",
"aggregation_type": "sum_agg",
"field_name": "total",
"group": {
"key": "region",
"values": [
"USA",
"europe",
"africa"
]
}
}
}
Note that each group is case-sensitive and has its own group_id
, upon which Lago bases its logic.
Here’s how Lago handles these changes:
- Since
"region: europe"
remains the same between both payloads;
itsgroup_id
remains unchanged. - As
"region: usa"
is present in Payload A but not in Payload B;
itsgroup_id
is removed from the billable metric. - As
"region: USA"
is not present in Payload A but is present in Payload B;
itsgroup_id
will be created in the billable metric. - Similarly, as
"region: africa"
is not present in Payload A but is present in Payload B;
itsgroup_id
will be created in the billable metric.
When this billable metric is associated with charges, editing it will impact all plans where it is defined.
- If an existing
group_id
remains the same (case 1), Lago will retain the group definitions in all associated charges. - If an existing
group_id
is removed from the billable metric (case 2), Lago will remove the group definition in all associated charges. - If a new
group_id
is created in the billable metric (case 3 and 4), Lago will not automatically add the new group to all associated charges; you will need to add them manually.