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.
loki.relabel
The loki.relabel
component rewrites the label set of each log entry passed to
its receiver by applying one or more relabeling rule
s and forwards the
results to the list of receivers in the component’s arguments.
If no labels remain after the relabeling rules are applied, then the log entries are dropped.
The most common use of loki.relabel
is to filter log entries 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 log entry in order of their
appearance in the configuration file. The configured rules can be retrieved by
calling the function in the rules
export field.
If you’re looking for a way to process the log entry contents, take a look at
the loki.process
component instead.
Multiple loki.relabel
components can be specified by giving them
different labels.
Usage
loki.relabel "LABEL" {
forward_to = RECEIVER_LIST
rule {
...
}
...
}
Arguments
The following arguments are supported:
Name | Type | Description | Default | Required |
---|---|---|---|---|
forward_to | list(receiver) | Where to forward log entries after relabeling. | yes | |
max_cache_size | int | The maximum number of elements to hold in the relabeling cache | 10,000 | no |
Blocks
The following blocks are supported inside the definition of loki.relabel
:
Hierarchy | Name | Description | Required |
---|---|---|---|
rule | rule | Relabeling rules to apply to received log entries. | 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
.
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 log lines are sent to be relabeled. |
rules | RelabelRules | The currently configured relabeling rules. |
Component health
loki.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
loki.relabel
does not expose any component-specific debug information.
Debug metrics
loki_relabel_entries_processed
(counter): Total number of log entries processed.loki_relabel_entries_written
(counter): Total number of log entries forwarded.loki_relabel_cache_misses
(counter): Total number of cache misses.loki_relabel_cache_hits
(counter): Total number of cache hits.loki_relabel_cache_size
(gauge): Total size of relabel cache.
Example
The following example creates a loki.relabel
component that only forwards
entries whose ’level’ value is set to ’error'.
loki.relabel "keep_error_only" {
forward_to = [loki.write.onprem.receiver]
rule {
action = "keep"
source_labels = ["level"]
regex = "error"
}
}