Relabeling Rules¶

Relabeling is the process of the manipulation of the metrics, based on labels. The manipulation rules are applied on the collector level via a relabel configuration. The rule set contains one or more relabeling rules, each one performing one or more tasks:

replace - Create or update labels basing on context of the other labels.
drop - Drop matched metrics.
drop_if_equal - Drop metrics if values of labels are equal.
keep - Keep matched metrics.
labeldrop - Drop matched labels.
labelkeep - Keep matched labels.
labelmap - Map one or more label name to different label names.
dump - Dump active labels.

Virtual Labels¶

Unlike the measure labels, virtual labels are available only during the relabeling process and are not exposed to the database. The following virtual labels are available:

Label	Description
`__name__`	The metric's name
`__address__`	`<address>:<port>` for the source, exposed by scrape collector
`__meta_`	The prefix for a labels generated by collectors which are available only on relabeling stage

... note

Virtual labels are not removed by actions.

Actions¶

Replace¶

replace action creates or updates labels basing on context of the other labels. The configuration is:

Parameter	Default	Description
`action`	`replace`	Must be `replace`
`source_labels`		The list of label names to be extracted
`separator`	`;`	The separator
`regex`	`(.+)`	The regular expression to match
`replacement`		The resulting expression. `regex` matching groups should be referred by number (i.e. `$1`, `$2`) or by name (i.e. `$first`, `$second`)
`target_label`		The name of the label to be created or replaced

The replace rule performs the following steps:

Extracts the values of the all labels specified in source_labels. If any of the source_labels is missed, the rule is considered failed and the processing passed to the next rule.
The extracted values are concatenated together using separator building the value string
The value string is matched against the regex. If the regex is failed to match the rule is considered failed and processing is passed to the next rule.
replacement expression is used to build the result. It may contain the references to the capture groups of the regex:
- $0 - expands to the whole match.
- $<n> - where <n> is a number: match n-th capture group. I.e. $1, $2, ...
- $<name> - match a named capture group, i.e $first, $last.
The result of the expansion of the replacement is placed into label defined by target_label.
The processing is passed to the next rule.

Note

The rewriting of the __name__ virtual label changes the metric's name.

Examples:

Rewrite the user label as the <user>@<zone>:

- source_labels: [__name__, user, zone]
  separator: "@"
  regex: "ps_write_count@(.+)"
  replacement: "$1"
  target_label: user
  action: replace

Rewrite ps_write_count metric name to total_writes:

- source_labels: [__name__]
  regex: ps_write_count
  replacement: total_writes
  target_label: __name__

Drop¶

drop actions drops matched metrics. The configuration is:

Parameter	Default	Description
`action`		Must be `drop`
`source_labels`		The list of label names to be extracted
`separator`	`;`	The separator
`regex`	`(.+)`	The regular expression to match

The drop rule performs the following steps:

Extracts the values of the all labels specified in source_labels. If any of the source_labels is missed, the rule is considered failed and the processing passed to the next rule.
The extracted values are concatenated together using separator building the value string
The value string is matched against the regex. If the regex is failed to match the rule is considered failed and processing is passed to the next rule.
The metric is considered as matched and discarded.
Processing is stopped.

Examples:

Drop ps_write_count metric:

- source_labels: [__name__]
  regex: ps_write_count
  action: drop

Drop ps_write_count metric for user scott in zone tiger:

- source_labels: [__name__, user, zone]
  regex: "ps_write_count;scott;tiger"
  action: drop

Drop If Equal¶

drop_if_equal action drops metric if the values of labels are equal. The configuration is:

Parameter	Default	Description
`action`		Must be `drop_if_equal`
`source_labels`		The list of label names to be evaluated. Must contain two or more names.

The drop_if_equal rule performs the following steps:

Extracts the values of the all labels specified in source_labels.
If all extracted values are the same, rule is considered matcheed and the metric is discarded.
Processing is stopped.

Note

drop_if_equal rule matches if all the labels in source_labels are missed.

Examples:

Drop metric if prev_label and new_label is matched:

- source_labels: [prev_label, new_label]
  action: drop_if_equal

Keep¶

keep actions keeps matched metrics. The configuration is:

Parameter	Default	Description
`action`		Must be `keep`
`source_labels`		The list of label names to be extracted
`separator`	`;`	The separator
`regex`	`(.+)`	The regular expression to match

The replace rule performs the following steps:

Extracts the values of the all labels specified in source_labels. If any of the source_labels is missed, the rule is considered failed and the processing passed to the next rule.
The extracted values are concatenated together using separator building the value string
The value string is matched against the regex. If the regex is failed the metric is discarded and processing is stopped.
Otherwise, processing is passed to the next rule.

Examples:

Drop all metrics except ps_read_count and ps_write_count:

- source_labels: [__name__]
  regex: ps_read_count|ps_write_count
  action: keep

Label Drop¶

labeldrop action drops all matching labels. The configuration is:

Parameter	Default	Description
`action`		Must be `labelkeep`
`regex`		The regular expression to match

The labeldrop rule perform following steps:

All labels are matched against the regex. Matching labels are discarded.
Processing is passed to the next rule.

Note

labeldrop doesn't affect virtual labels.

Example:

Drop user and zone labels.

- action: labeldrop
  regex: user|zone

Label Keep¶

labelkeep action keeps all matching labels and drops all non-matching. The configuration is:

Parameter	Default	Description
`action`		Must be `labelkeep`
`regex`		The regular expression to match

The labelkeep rule perform following steps:

All labels are matched against the regex. Matching labels are kept, not matched ones are discarded.
Processing is passed to the next rule.

Note

labelkeep doesn't affect virtual labels.

Example:

Keep only mount and dev labels.

- action: labelkeep
  regex: mount|dev

Label Map¶

labelmap action maps one or more label names to the different label names. The configuration is:

Parameter	Default	Description
`action`		Must be `labelmap`
`regex`		The regular expression to match
`replacement`		The resulting expression. `regex` matching groups should be referred by number (i.e. `$1`, `$2`) or by name (i.e. `$first`, `$second`)

The labelmap rule perform following steps:

All labels are matched against the regex. Matching labels are applied to the replacement and are renamed.
Processing is passed to the next rule.

Note

labelmap doesn't remove virtual labels after rename.

Examples:

Rename dc label to datacenter:

- action: labelmap
  regex: dc
  replacement: datacenter

Rename virtual labels started with __meta_kubernetes_:

- action: labelmap
  regex: __meta_kubernetes_(.+)
  replacement: k8s_$1

Dump¶

dump action dumps effective labels to the log and cotinues processing. The configuration is:

Parameter	Default	Description
`action`		Must be `dump`

Examples:

- action: dump

Sample output:

[2023-06-19T11:41:23.625Z INFO  relabel::dump] ===[START OF LABELS]==========
[2023-06-19T11:41:23.625Z INFO  relabel::dump] __meta_cmd = ./target/release/gufo-agent -vv --config=var/config.yml --test
[2023-06-19T11:41:23.625Z INFO  relabel::dump] __name__ = ps_write_bytes
[2023-06-19T11:41:23.625Z INFO  relabel::dump] agent = gufo
[2023-06-19T11:41:23.625Z INFO  relabel::dump] collector = procstat
[2023-06-19T11:41:23.625Z INFO  relabel::dump] host = test
[2023-06-19T11:41:23.625Z INFO  relabel::dump] process_name = gufo-agent
[2023-06-19T11:41:23.625Z INFO  relabel::dump] user = root
[2023-06-19T11:41:23.625Z INFO  relabel::dump] zone = DC1
[2023-06-19T11:41:23.625Z INFO  relabel::dump] ===[END OF LABELS]============