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:
Blocks
The following blocks are supported inside the definition of loki.relabel
:
rule block
The rule
block contains the definition of any relabeling rules that can be applied to an input log.
The transformations are applied in top-down order if more than one rule
block is defined.
You can use the following arguments to configure a rule
.
All arguments are optional. Omitted fields take their default values.
You can use the following actions:
drop
- Drops logs 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 logs 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 log’s label set.labelkeep
- Matchesregex
against all label names. Any labels that don’t match are removed from the log’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:
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"
}
}
Compatible components
loki.relabel
can accept arguments from the following components:
- Components that export Loki
LogsReceiver
loki.relabel
has exports that can be consumed by the following components:
- Components that consume Loki
LogsReceiver
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.