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.

Documentation Grafana Agent Grafana Agent Flow Reference Components loki.relabel

loki.relabel

The loki.relabel component rewrites the label set of each log entry passed to its receiver by applying one or more relabeling rules 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

river Copy

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

Here’s a list of the available actions, along with a brief description of their usage.

• 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.
• keep - Keeps metrics where regex matches the string extracted using the source_labels and separator.
• drop - Drops metrics where regex matches the string extracted using the source_labels and separator.
• hashmod - Hashes the concatenated labels, calculates its modulo modulus and writes the result to the target_label.
• labelmap - Matches regex against all label names. Any labels that match are renamed according to the contents of the replacement field.
• 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.

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:

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

river Copy

loki.relabel "keep_error_only" {
  forward_to = [loki.write.onprem.receiver]

  rule {
    action        = "keep"
    source_labels = ["level"]
    regex         = "error"
  }
}