Caution
Grafana Alloy is the new name for our distribution of the OTel collector. Grafana Agent has been deprecated and is in Long-Term Support (LTS) through October 31, 2025. Grafana Agent will reach an End-of-Life (EOL) on November 1, 2025. Read more about why we recommend migrating to Grafana Alloy.
Important: This documentation is about an older version. It's relevant only to the release noted, many of the features and functions have been updated or replaced. Please view the current version.
prometheus.relabel
Prometheus metrics follow the OpenMetrics 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.
<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
prometheus.relabel "LABEL" {
forward_to = RECEIVER_LIST
rule {
...
}
...
}
Arguments
The following arguments are supported:
Name | Type | Description | Default | Required |
---|---|---|---|---|
forward_to | list(receiver) | Where the metrics should be forwarded to, after relabeling takes place. | yes |
Blocks
The following blocks are supported inside the definition of prometheus.relabel
:
Hierarchy | Name | Description | Required |
---|---|---|---|
rule | rule | 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.
Name | Type | Description | Default | Required |
---|---|---|---|---|
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 | |
separator | string | The separator used to concatenate the values present in source_labels . | ; | 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 |
modulus | uint | A positive integer used to calculate the modulus of the hashed source label values. | no | |
target_label | string | Label to which the resulting value will be written to. | no | |
replacement | string | The value against which a regex replace is performed, if the regex matches the extracted value. Supports previously captured groups. | $1 | no |
action | string | The relabeling action to perform. | replace | no |
Here’s a list of the available actions, along with a brief description of their usage.
replace
- Matchesregex
to the concatenated labels. If there’s a match, it replaces the content of thetarget_label
using the contents of thereplacement
field.keep
- Keeps metrics whereregex
matches the string extracted using thesource_labels
andseparator
.drop
- Drops metrics whereregex
matches the string extracted using thesource_labels
andseparator
.hashmod
- Hashes the concatenated labels, calculates its modulomodulus
and writes the result to thetarget_label
.labelmap
- Matchesregex
against all label names. Any labels that match are renamed according to the contents of thereplacement
field.labeldrop
- Matchesregex
against all label names. Any labels that match are removed from the metric’s label set.labelkeep
- Matchesregex
against all label names. Any labels that don’t match are removed from the metric’s label set.keepequal
- Drop targets for which the concatenatedsource_labels
do not matchtarget_label
.dropequal
- Drop targets for which the concatenatedsource_labels
do matchtarget_label
.lowercase
- Setstarget_label
to the lowercase form of the concatenatedsource_labels
.uppercase
- Setstarget_label
to the uppercase form of the concatenatedsource_labels
.
Finally, note that the regex 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:
Name | Type | Description |
---|---|---|
receiver | receiver | 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.
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"
}
}
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 /
.
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:
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:
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.