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.
This is documentation for the next version of Agent. For the latest stable release, go to the latest version.
discovery.relabel
In Flow, targets are defined as sets of key-value pairs called labels.
discovery.relabel
rewrites the label set of the input targets by applying one
or more relabeling rules. If no rules are defined, then the input targets are
exported as-is.
The most common use of discovery.relabel
is to filter targets or standardize
the target label set that is passed to a downstream component. The rule
blocks are applied to the label set of each target in order of their appearance
in the configuration file. The configured rules can be retrieved by calling the
function in the rules
export field.
Target labels which start with a double underscore __
are considered
internal, and may be removed by other Flow components prior to telemetry
collection. To retain any of these labels, use a labelmap
action to remove
the prefix, or remap them to a different name. Service discovery mechanisms
usually group their labels under __meta_*
. For example, the
discovery.kubernetes component populates a set of __meta_kubernetes_*
labels
to provide information about the discovered Kubernetes resources. If a
relabeling rule needs to store a label value temporarily, for example as the
input to a subsequent step, use the __tmp
label name prefix, as it is
guaranteed to never be used.
Multiple discovery.relabel
components can be specified by giving them
different labels.
Usage
discovery.relabel "LABEL" {
targets = TARGET_LIST
rule {
...
}
...
}
Arguments
The following arguments are supported:
Name | Type | Description | Default | Required |
---|---|---|---|---|
targets | list(map(string)) | Targets to relabel | yes |
Blocks
The following blocks are supported inside the definition of
discovery.relabel
:
Hierarchy | Block | Description | Required |
---|---|---|---|
rule | rule | Relabeling rules to apply to targets. | 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 |
---|---|---|---|---|
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 whereregex
matches the string extracted using thesource_labels
andseparator
.dropequal
- Drop targets for which the concatenatedsource_labels
do matchtarget_label
.hashmod
- Hashes the concatenated labels, calculates its modulomodulus
and writes the result to thetarget_label
.keep
- Keeps metrics whereregex
matches the string extracted using thesource_labels
andseparator
.keepequal
- Drop targets for which the concatenatedsource_labels
do not matchtarget_label
.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.labelmap
- Matchesregex
against all label names. Any labels that match are renamed according to the contents of thereplacement
field.lowercase
- Setstarget_label
to the lowercase form of the concatenatedsource_labels
.replace
- Matchesregex
to the concatenated labels. If there’s a match, it replaces the content of thetarget_label
using the contents of thereplacement
field.uppercase
- Setstarget_label
to the uppercase form of the concatenatedsource_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:
Name | Type | Description |
---|---|---|
output | list(map(string)) | The set of targets after applying relabeling. |
rules | RelabelRules | The currently configured relabeling rules. |
Component health
discovery.relabel
is only reported as unhealthy when given an invalid
configuration. In those cases, exported fields retain their last healthy
values.
Debug information
discovery.relabel
does not expose any component-specific debug information.
Debug metrics
discovery.relabel
does not expose any component-specific debug metrics.
Example
discovery.relabel "keep_backend_only" {
targets = [
{ "__meta_foo" = "foo", "__address__" = "localhost", "instance" = "one", "app" = "backend" },
{ "__meta_bar" = "bar", "__address__" = "localhost", "instance" = "two", "app" = "database" },
{ "__meta_baz" = "baz", "__address__" = "localhost", "instance" = "three", "app" = "frontend" },
]
rule {
source_labels = ["__address__", "instance"]
separator = "/"
target_label = "destination"
action = "replace"
}
rule {
source_labels = ["app"]
action = "keep"
regex = "backend"
}
}
Compatible components
discovery.relabel
can accept arguments from the following components:
- Components that export Targets
discovery.relabel
has exports that can be consumed by the following components:
- Components that consume Targets
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.