This is documentation for the next version of Alloy. For the latest stable release, go to the latest 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 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.
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 is written to. | no |
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:
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"
}
}
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.