How Relabel Rules Work

Relabel rules let you rewrite, add, and remove labels on incoming data, drop data you do not want to store, and assign data to a retention policy, before Kloudfuse stores it. The rules run in the ingester and use the Prometheus relabel_config format.

Each stream has its own list of rules. Logs are covered in the logs-parser pipeline. It has its own relabel and transform functions; see Logs Relabel Rules.

Where to configure rules

Add each stream’s rules to its relabelConfigs list under ingester.config in your custom-values.yaml file:

Stream Helm values key

Metrics

ingester.config.aggregator.metric.relabelConfigs

Traces

ingester.config.traces.relabelConfigs

Events

ingester.config.events.relabelConfigs

RUM

ingester.config.rum.relabelConfigs

All lists are empty by default. Rules for one stream never apply to another.

To apply a change, run a Helm upgrade:

helm upgrade --install kfuse oci://us-east1-docker.pkg.dev/mvp-demo-301906/kfuse-helm/kfuse \
  -n kfuse \
  --version <VERSION> \ (1)
  -f custom-values.yaml
bash
1 Replace <VERSION> with a valid Kloudfuse release value. See Release Notes for the latest release.

Rule fields

Field Description

source_labels

The labels whose values the rule reads. Their values are joined with separator, and the result is matched against regex.

separator

The string placed between the source_labels values. Default: ;.

regex

A regular expression matched against the joined value, or against label names for labeldrop, labelkeep, and labelmap. It must match the whole value: abc matches abc but not xabcx. Default: (.*).

target_label

The label that replace, lowercase, uppercase, and hashmod write to.

replacement

The value written to target_label. It can refer to capture groups in regex, for example ${1}. Default: $1.

modulus

The modulus for hashmod.

retention_policy

The retention policy that the retention action assigns.

action

What the rule does. Default: replace.

Actions

Action What it does

replace

If regex matches, writes replacement to target_label. If the replacement is empty, removes target_label.

lowercase, uppercase

Writes the joined source_labels value, in lower or upper case, to target_label.

hashmod

Hashes the joined source_labels value, divides the hash by modulus, and writes the remainder to target_label.

labelmap

For every label whose name matches regex, copies its value to a label named by replacement.

labeldrop

Removes every label whose name matches regex.

labelkeep

Removes every label whose name does not match regex.

drop

Drops the data point if regex matches the joined source_labels value.

keep

Drops the data point if regex does not match the joined source_labels value.

retention

If regex matches, assigns the data point to the retention policy named in retention_policy. Custom retention policies are supported for metrics, events, and traces; see Configure relabel rules.

The ingester skips rules with any other action and logs a warning. The Prometheus keepequal and dropequal actions are not supported.

How rules are evaluated

  • Rules run in order. Each rule sees the labels as the previous rules left them, so a rule can match a label that an earlier rule added or changed.

  • A drop ends evaluation. When a drop or keep rule drops a data point, the remaining rules do not run.

  • The last matching retention rule wins. If several retention rules match, the data point gets the policy of the last one.

  • Ingestion API key labels are protected. If the data was sent with an ingestion API key that adds labels, rules can match those labels but cannot change or remove them.

What happens after relabeling

Relabel rules run before the rest of ingestion, so everything later sees the relabeled data:

  • Rate control class matchers match the relabeled labels, and dropped data never counts against a rate control limit.

  • Consumption tracking counts the data as received, then counts data dropped by a rule with the drop reason relabel.

  • Consumption tracking labels are read from the relabeled labels.

Stream pages