Summary

Add a PromQL function for labelmap available during querying with a similar behavior to the labelmap action in the relabel config.

Explanation

Currently, PromQL supports the label_replace() function, which is an incredibly useful function in manipulating labels during querying for compatibility reasons and to allow for better aggregation.

With that said, there is currently no way to preform that renaming for a group of labels. The label_replace() requires a source label and a destination label - meaning it is bound to a single replacement.

In the case where multiple replacements are needed, the only available solution is to nest these functions one within the other. Apart from increasing the complexity of the query and reducing readability, this approach fails when the labels we wish to manipulate are not fixed or dynamic.

Currently, there is no way to manipulate a changing set of labels at the querying level.

Solution

Prometheus already offers a great solution to a nearly identical problem during relabeling: the labelmap action.

We propose to add a PromQL function which acts exactly like the relabel action.

Note that this idea is a somewhat mix between the classic labelmap action and the label_replace() function.

This approach is simple, and in-short, copies the labelmap action behavior to a usable PromQL function. It syntax goes as follows:

labelmap(query, regex, replacement)

1. query defines the PromQL query being manipulated.

2. regex defines the label name of the labels being manipulated. Only labels matching said regex are affected.

3. replacement defines the new label name used for each affected label. Supports regex capture groups.

Example:

Assume the following PromQL query: up{job="kubernetes_pods"}

Returns the following series:

up{job="kubernetes_pods", kubernetes_cluster="cluster1", kubernetes_namespace="namespace1", kubernetes_pod="pod1"}

up{job="kubernetes_pods", kubernetes_cluster="cluster2", kubernetes_namespace="namespace2", kubernetes_pod="pod2"}

up{job="kubernetes_pods", kubernetes_cluster="cluster3", kubernetes_namespace="namespace3", kubernetes_pod="pod3"}

Notice many of the label names start with kubernetes. For this example, we'd want to drop that prefix from all relevant labels.

Disclaimer: although this is possible to do permanently during relabeling, saving it like that is not always desired and irreversible - unlike a PromQL function, which is relevant only for a specific query.

If we surround our query with the new labelmap function as follows:

labelmap(up{job="kubernetes_pods"},"kubernetes_(.+)", "$1")

We get as a result the following:

up{job="kubernetes_pods", cluster="cluster1", namespace="namespace1", pod="pod1"}

up{job="kubernetes_pods", cluster="cluster2", namespace="namespace2", pod="pod2"}

up{job="kubernetes_pods", cluster="cluster3", namespace="namespace3", pod="pod3"}

Notice how the job label is unaffected.

This way, we achieve an almost identical behavior to the relabel action, while preserving the flexibility a PromQL function offers.

Benefits

1. The best of both worlds: add supports for dynamic “label renaming” that the labelmap action offers while preserving the flexibility the label_replace() function has.
2. Familiar concept: simple and relies on existing behavior.
3. Offers a solution for a use case currently unavailable when querying.

We would love to hear more thoughts on the matter, and hope (if eligible) to see it implemented in the near future!