Caution

Grafana Agent has reached End-of-Life (EOL) on November 1, 2025. Agent is no longer receiving vendor support and will no longer receive security or bug fixes. Current users of Agent Static mode, Agent Flow mode, and Agent Operator should proceed with migrating to Grafana Alloy. If you have already migrated to Alloy, no further action is required. Read more about why we recommend migrating to Grafana Alloy.

Documentationbreadcrumb arrow Grafana Agentbreadcrumb arrow Flow modebreadcrumb arrow Referencebreadcrumb arrow Components referencebreadcrumb arrow loki.relabel
Open source

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

Alloy 
loki.relabel "LABEL" {
  forward_to = RECEIVER_LIST

  rule {
    ...
  }

  ...
}

Arguments

The following arguments are supported:

NameTypeDescriptionDefaultRequired
forward_tolist(receiver)Where to forward log entries after relabeling.yes
max_cache_sizeintThe maximum number of elements to hold in the relabeling cache10,000no

Blocks

The following blocks are supported inside the definition of loki.relabel:

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

NameTypeDescriptionDefaultRequired
actionstringThe relabeling action to perform.replaceno
modulusuintA positive integer used to calculate the modulus of the hashed source label values.no
regexstringA 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
replacementstringThe value against which a regular expression replace is performed if the regular expression matches the extracted value. Supports previously captured groups."$1"no
separatorstringThe separator used to concatenate the values present in source_labels.;no
source_labelslist(string)The list of labels whose values are to be selected. Their content is concatenated using the separator and matched against regex.no
target_labelstringLabel to which the resulting value is written to.no

You can use the following actions:

  • drop - Drops logs where regex matches the string extracted using the source_labels and separator.
  • dropequal - Drop targets for which the concatenated source_labels do match target_label.
  • hashmod - Hashes the concatenated labels, calculates its modulo modulus, and writes the result to the target_label.
  • keep - Keeps logs where regex matches the string extracted using the source_labels and separator.
  • keepequal - Drop targets for which the concatenated source_labels do not match target_label.
  • labeldrop - Matches regex against all label names. Any labels that match are removed from the log’s label set.
  • labelkeep - Matches regex against all label names. Any labels that don’t match are removed from the log’s label set.
  • labelmap - Matches regex against all label names. Any labels that match are renamed according to the contents of the replacement field.
  • lowercase - Sets target_label to the lowercase form of the concatenated source_labels.
  • 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.
  • uppercase - Sets target_label to the uppercase form of the concatenated source_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:

NameTypeDescription
receiverreceiverThe input receiver where log lines are sent to be relabeled.
rulesRelabelRulesThe 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'.

Alloy 
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:

loki.relabel has exports that can be consumed by the following components:

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.