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.
Open source


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 rules. 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.


prometheus.relabel "LABEL" {
  forward_to = RECEIVER_LIST

  rule {



The following arguments are supported:

forward_tolist(MetricsReceiver)Where the metrics should be forwarded to, after relabeling takes place.yes
max_cache_sizeintThe maximum number of elements to hold in the relabeling cache.100,000no


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

ruleruleRelabeling rules to apply to received

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.

actionstringThe relabeling action to perform.replaceno
modulusuintA positive integer used to calculate the modulus of the hashed source label
regexstringA 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
replacementstringThe value against which a regular expression replace is performed, if the regular expression matches the extracted value. Supports previously captured groups."$1"no
separatorstringThe separator used to concatenate the values present in source_labels.;no
source_labelslist(string)The list of labels whose values are to be selected. Their content is concatenated using the separator and matched against
target_labelstringLabel to which the resulting value will be written

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.


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:

receiverMetricsReceiverThe input receiver where samples are sent to be relabeled.
rulesRelabelRulesThe 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.


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.

Compatible components

prometheus.relabel can accept arguments from the following components:

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


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.