Sometimes you may want to take a whole set of source labels and map their values onto a new set of differently prefixed new label names. The labelmap action allows you to do this. The most common use case for the labelmap action is taking a group of __meta-prefixed metadata labels from a service discovery source and mapping them into permanent target labels.

Rule structure

A labelmap relabeling rule has the following structure:

action: labelmap
regex: <regular expression>               # Defaults to '(.*)' (matching any value)
replacement: <replacement string>         # Defaults to '$1' (using the first capturing group as a replacement)

In contrast to the previous relabeling actions we learned about, the labelmap action regex-matches and acts on label names, not label values.

The labelmap action performs the following steps, in sequence:

1. It matches the regular expression in regex against all label names.
2. It then copies the values of matching label names to a set of new label names that are determined by the replacement string. The replacement string may contain regex capture group references ($1, $2, ...) to insert extracted parts of the original label name into the destination label name.

Use case examples

Let's look at an example use case for the labelmap action.

Mapping Kubernetes service labels

When using Kubernetes-based service discovery to discover pod endpoints, you may want the final target labels for each endpoint to also contain the Kubernetes service labels. The Kubernetes service discovery provides these in a set of labels with the naming pattern __meta_kubernetes_service_label_<labelname>. We can extract the <labelname> part of those metadata labels and map the corresponding label values over to a new set of label names that start with a k8s_ prefix, like this:

action: labelmap
regex: __meta_kubernetes_service_label_(.+)
replacement: 'k8s_$1'