---
title: "prometheus.relabel | Grafana Agent documentation"
description: "Learn about prometheus.relabel"
---

# prometheus.relabel

Prometheus metrics follow the [OpenMetrics](https://openmetrics.io/) format. Each time series is uniquely identified by its metric name, plus optional key-value pairs called labels. Each sample represents a datapoint in the time series and contains a value and an optional timestamp.

![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```none
<metric name>{<label_1>=<label_val_1>, <label_2>=<label_val_2> ...} <value> [timestamp]
```

The `prometheus.relabel` component rewrites the label set of each metric passed along to the exported receiver by applying one or more relabeling `rule`s. If no rules are defined or applicable to some metrics, then those metrics are forwarded as-is to each receiver passed in the component’s arguments. If no labels remain after the relabeling rules are applied, then the metric is dropped.

The most common use of `prometheus.relabel` is to filter Prometheus metrics or standardize the label set that is passed to one or more downstream receivers. The `rule` blocks are applied to the label set of each metric in order of their appearance in the configuration file. The configured rules can be retrieved by calling the function in the `rules` export field.

Multiple `prometheus.relabel` components can be specified by giving them different labels.

## Usage

Alloy ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```alloy
prometheus.relabel "LABEL" {
  forward_to = RECEIVER_LIST

  rule {
    ...
  }

  ...
}
```

## Arguments

The following arguments are supported:

Expand table

| Name             | Type                    | Description                                                             | Default | Required |
|------------------|-------------------------|-------------------------------------------------------------------------|---------|----------|
| `forward_to`     | `list(MetricsReceiver)` | Where the metrics should be forwarded to, after relabeling takes place. |         | yes      |
| `max_cache_size` | `int`                   | The maximum number of elements to hold in the relabeling cache.         | 100,000 | no       |

## Blocks

The following blocks are supported inside the definition of `prometheus.relabel`:

Expand table

| Hierarchy | Name                | Description                                    | Required |
|-----------|---------------------|------------------------------------------------|----------|
| rule      | [rule](#rule-block) | Relabeling rules to apply to received metrics. | no       |

### rule block

The `rule` block contains the definition of any relabeling rules that can be applied to an input metric. If more than one `rule` block is defined, the transformations are applied in top-down order.

The following arguments can be used to configure a `rule`. All arguments are optional. Omitted fields take their default values.

Expand table

| Name            | Type           | Description                                                                                                                                                                                                                                   | Default | Required |
|-----------------|----------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------|----------|
| `action`        | `string`       | The relabeling action to perform.                                                                                                                                                                                                             | replace | no       |
| `modulus`       | `uint`         | A positive integer used to calculate the modulus of the hashed source label values.                                                                                                                                                           |         | no       |
| `regex`         | `string`       | A valid RE2 expression with support for parenthesized capture groups. Used to match the extracted value from the combination of the `source_label` and `separator` fields or filter labels during the `labelkeep/labeldrop/labelmap` actions. | `(.*)`  | no       |
| `replacement`   | `string`       | The value against which a regular expression replace is performed, if the regular expression matches the extracted value. Supports previously captured groups.                                                                                | `"$1"`  | no       |
| `separator`     | `string`       | The separator used to concatenate the values present in `source_labels`.                                                                                                                                                                      | ;       | no       |
| `source_labels` | `list(string)` | The list of labels whose values are to be selected. Their content is concatenated using the `separator` and matched against `regex`.                                                                                                          |         | no       |
| `target_label`  | `string`       | Label to which the resulting value will be written to.                                                                                                                                                                                        |         | no       |

You can use the following actions:

- `drop` - Drops metrics where `regex` matches the string extracted using the `source_labels` and `separator`.
- `dropequal` - Drop targets for which the concatenated `source_labels` do match `target_label`.
- `hashmod` - Hashes the concatenated labels, calculates its modulo `modulus` and writes the result to the `target_label`.
- `keep` - Keeps metrics where `regex` matches the string extracted using the `source_labels` and `separator`.
- `keepequal` - Drop targets for which the concatenated `source_labels` do not match `target_label`.
- `labeldrop` - Matches `regex` against all label names. Any labels that match are removed from the metric’s label set.
- `labelkeep` - Matches `regex` against all label names. Any labels that don’t match are removed from the metric’s label set.
- `labelmap` - Matches `regex` against all label names. Any labels that match are renamed according to the contents of the `replacement` field.
- `lowercase` - Sets `target_label` to the lowercase form of the concatenated `source_labels`.
- `replace` - Matches `regex` to the concatenated labels. If there’s a match, it replaces the content of the `target_label` using the contents of the `replacement` field.
- `uppercase` - Sets `target_label` to the uppercase form of the concatenated `source_labels`.

> Note
> 
> The regular expression capture groups can be referred to using either the `$CAPTURE_GROUP_NUMBER` or `${CAPTURE_GROUP_NUMBER}` notation.

## Exported fields

The following fields are exported and can be referenced by other components:

Expand table

| Name       | Type              | Description                                                |
|------------|-------------------|------------------------------------------------------------|
| `receiver` | `MetricsReceiver` | The input receiver where samples are sent to be relabeled. |
| `rules`    | `RelabelRules`    | The currently configured relabeling rules.                 |

## Component health

`prometheus.relabel` is only reported as unhealthy if given an invalid configuration. In those cases, exported fields are kept at their last healthy values.

## Debug information

`prometheus.relabel` does not expose any component-specific debug information.

## Debug metrics

- `agent_prometheus_relabel_metrics_processed` (counter): Total number of metrics processed.
- `agent_prometheus_relabel_metrics_written` (counter): Total number of metrics written.
- `agent_prometheus_relabel_cache_misses` (counter): Total number of cache misses.
- `agent_prometheus_relabel_cache_hits` (counter): Total number of cache hits.
- `agent_prometheus_relabel_cache_size` (gauge): Total size of relabel cache.
- `agent_prometheus_fanout_latency` (histogram): Write latency for sending to direct and indirect components.
- `agent_prometheus_forwarded_samples_total` (counter): Total number of samples sent to downstream components.

## Example

Let’s create an instance of a see `prometheus.relabel` component and see how it acts on the following metrics.

Alloy ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```alloy
prometheus.relabel "keep_backend_only" {
  forward_to = [prometheus.remote_write.onprem.receiver]

  rule {
    action        = "replace"
    source_labels = ["__address__", "instance"]
    separator     = "/"
    target_label  = "host"
  }
  rule {
    action        = "keep"
    source_labels = ["app"]
    regex         = "backend"
  }
  rule {
    action = "labeldrop"
    regex  = "instance"
  }
}
```

![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```none
metric_a{__address__ = "localhost", instance = "development", app = "frontend"} 10
metric_a{__address__ = "localhost", instance = "development", app = "backend"}  2
metric_a{__address__ = "cluster_a", instance = "production",  app = "frontend"} 7
metric_a{__address__ = "cluster_a", instance = "production",  app = "backend"}  9
metric_a{__address__ = "cluster_b", instance = "production",  app = "database"} 4
```

After applying the first `rule`, the `replace` action populates a new label named `host` by concatenating the contents of the `__address__` and `instance` labels, separated by a slash `/`.

![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```none
metric_a{host = "localhost/development", __address__ = "localhost", instance = "development", app = "frontend"} 10
metric_a{host = "localhost/development", __address__ = "localhost", instance = "development", app = "backend"}  2
metric_a{host = "cluster_a/production",  __address__ = "cluster_a", instance = "production",  app = "frontend"} 7
metric_a{host = "cluster_a/production",  __address__ = "cluster_a", instance = "production",  app = "backend"}  9
metric_a{host = "cluster_b/production",  __address__ = "cluster_a", instance = "production",  app = "database"} 4
```

On the second relabeling rule, the `keep` action only keeps the metrics whose `app` label matches `regex`, dropping everything else, so the list of metrics is trimmed down to:

![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```none
metric_a{host = "localhost/development", __address__ = "localhost", instance = "development", app = "backend"}  2
metric_a{host = "cluster_a/production",  __address__ = "cluster_a", instance = "production",  app = "backend"}  9
```

The third and final relabeling rule which uses the `labeldrop` action removes the `instance` label from the set of labels.

So in this case, the initial set of metrics passed to the exported receiver is:

![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```none
metric_a{host = "localhost/development", __address__ = "localhost", app = "backend"}  2
metric_a{host = "cluster_a/production",  __address__ = "cluster_a", app = "backend"}  9
```

The two resulting metrics are then propagated to each receiver defined in the `forward_to` argument.

## Compatible components

`prometheus.relabel` can accept arguments from the following components:

- Components that export [Prometheus `MetricsReceiver`](../../compatibility/#prometheus-metricsreceiver-exporters)

`prometheus.relabel` has exports that can be consumed by the following components:

- Components that consume [Prometheus `MetricsReceiver`](../../compatibility/#prometheus-metricsreceiver-consumers)

> Note
> 
> Connecting some components may not be sensible or components may require further configuration to make the connection work correctly. Refer to the linked documentation for more details.