Grafana Cloud fundamentalsConfigure usage groups

Usage groups

You can configure usage groups so that you can get usage statistics for user combinations when the users are accessing the same stack. For example, if multiple teams are using the same stack, you can define a group for each team. Active series sent to Grafana Cloud are counted and attributed to usage groups using a predefined set of labels that you set on your metrics.

Setting up usage group tracking

Grafana Cloud has a predefined label set for usage groups. The label name is grafanacloud_usage_group and defaults to supporting values 1 to 15, e.g. grafanacloud_usage_group=1 to grafanacloud_usage_group=15. You need to set this label and value on all metrics that you want attributed to specific groups.

Setting up in the Agent

Here we are going to address 3 different setups. For detailed explanation of configuration sections, please refer Agent Configuration

1. Standalone configuration for each agent deployments

For simple cases when there are separate agent configurations for each group you would like to track, add a global stanza in the metrics section of the agent configuration file for each agent. For example:

    ...
    metrics:
        global:
            external_labels:
                grafanacloud_usage_group: 8
    ...

The same can be done for integrations:

    ...
    integrations:
        labels:
            grafanacloud_usage_group: 8
    ...

2. Relabel configuration for single agent deployments

In cases where one agent scrapes metrics from different targets belonging to different groups, you need to ensure that each group is using their corresponding label value for grafanacloud_usage_group. This can be achieved by putting relabel configs to the corresponding scrape targets.

    ...
        scrape_configs:
            relabel_configs:
                target_label: 'grafanacloud_usage_group',
                replacement: '8',
    ...

3. Adding usage group labels based on conditions

When a single agent is scraping metrics owned by multiple groups, labels can be applied dynamically based on additional logic. For example, the following is an example of dynamic labeling in the remote_write section of the agent configuration file for a Kubernetes deployment.

    ...
    remote_write:
        ...
          write_relabel_configs:
          # Add usage group 8 to metrics, where the namespace is dev
          # and the kubernetes pod name matches on a specific regexp.
          # The value of the two source labels are joined by the separator and then matched by the regex
          - source_labels: ['namespace', 'name']
            action: 'replace'
            separator: '/'
            regex: 'dev/podnameprefix-.*'
            target_label: 'grafanacloud_usage_group'
            replacement: '8'
          # Metrics belonging to the prod namespace going to usage group 9
          - source_labels: ['namespace']
            action: 'replace'
            separator: '/'
            regex: 'prod/.*'
            target_label: 'grafanacloud_usage_group'
            replacement: '9'
          # If there is no usage group defined by the rules above, put the metric in group 15
          - source_labels: ['grafanacloud_usage_group']
            regex: '^$'
            target_label: 'grafanacloud_usage_group'
            replacement: '15'
        ...
    ...

Exploring usage groups

After you set up the scraping configuration, the usage group statistics will be displayed in the grafanacloud-usage datasource using grafanacloud_instance_active_usage_group_series.