Prometheus Label Functions

In Prometheus, labels are key-value pairs associated with time series data. They allow you to add metadata and context to your metrics, enabling more granular and specific querying. Prometheus provides various label functions to manipulate and filter time series data based on these labels. Here are the main label functions in Prometheus:

1. label_replace: This function allows you to replace or modify labels of a time series. It takes four arguments: the input vector, the target label name, a regular expression to match the source label value, and a replacement string.

2. label_join: With this function, you can concatenate label values into a new label. It takes two arguments: the input vector and a delimiter string to join the labels.

3. label_drop: This function removes specified labels from the input vector, effectively reducing the dimensionality of the data.

4. label_keep: The "label_keep" function filters out all labels from the input vector except the specified ones. It helps to focus on specific labels while discarding the rest.

5. label_match: This function selects time series that match a given regular expression pattern for a specific label. It takes two arguments: the input vector and the regular expression pattern.

6. label_replace_all: Similar to "label_replace", this function replaces or modifies multiple labels of a time series in one step. It takes three arguments: the input vector, a set of pairs of regular expressions and replacement strings, and an optional parameter to control the behavior of replacing multiple labels.

7. label_map: This function maps source label values to target label values based on a provided mapping. It takes three arguments: the input vector, a mapping of source to target labels, and an optional default value for unmatched source labels.

8. label_set: With this function, you can add or modify label values of a time series. It takes three arguments: the input vector, the label name to set or modify, and the label value to assign.

These label functions provide powerful capabilities for manipulating and filtering time series data based on their labels in Prometheus. They allow you to modify, transform, or select specific time series based on the metadata associated with them, enabling more targeted and flexible querying and analysis.

Examples

These examples demonstrate how each label function can be used in PromQL to manipulate and transform time series data based on their labels:

1. label_replace:

label_replace(my_metric{job="job1"}, "new_label", "$1", "source_label", "(.*)")

This example replaces the value of the "new_label" with the value of "source_label" for the "my_metric" time series. The regular expression "(.*)" captures the value of "source_label" and assigns it to "new_label".

2. label_join:

label_join(my_metric{job="job1"}, "new_label", ",", "label1", "label2")

This example joins the values of "label1" and "label2" with a comma (",") as the delimiter and assigns the result to "new_label" for the "my_metric" time series.

3. label_drop:

label_drop(my_metric{job="job1"}, "label1", "label2")

This example removes the "label1" and "label2" labels from the "my_metric" time series, reducing its dimensionality.

4. label_keep:

label_keep(my_metric{job="job1"}, "label1", "label2")

This example keeps only the "label1" and "label2" labels for the "my_metric" time series and discards all other labels.

5. label_match:

label_match(my_metric{job="job1"}, "label_name", "regex_pattern")

This example selects time series from the "my_metric" metric that have a "label_name" matching the specified "regex_pattern".

6. label_replace_all:

label_replace_all(my_metric{job="job1"}, {
  source_label1=~"regex_pattern1" => "replacement1",
  source_label2=~"regex_pattern2" => "replacement2"
})

This example replaces multiple labels ("source_label1" and "source_label2") with their corresponding replacement values for the "my_metric" time series, based on the provided regular expression patterns.

7. label_map:

label_map(my_metric{job="job1"}, { "source_label1" => "target_label1", "source_label2" => "target_label2" }, "default_value")

This example maps the values of "source_label1" and "source_label2" to their respective target labels ("target_label1" and "target_label2") for the "my_metric" time series. If a source label value is not present in the mapping, it uses the specified default value.

8. label_set:

label_set(my_metric{job="job1"}, "new_label", "new_value")

This example adds or modifies the label new_label to have the value new_value for the my_metric time series.