These functions are used to manipulate labels—they allow you to join labels to other ones, extract parts of label values, and even drop labels (though that particular operation is easier and more ergonomic to do with standard aggregation operators). In both functions, if the defined target label is a new one, it will get added to the label set; if it's an existing label, it will get replaced.

When using label_join, you're required to provide an instant vector, define a resulting label, identify the separator of the resulting concatenation, and establish the labels to join, as exemplified in the following syntax:

label_join(<vector>, <resulting_label>, <separator>, source_label1, source_labelN)

For example, say that we use the following sample data:

http_requests_total{code="200",endpoint="hey-port", handler="/",instance="172.17.0.10:8000",job="hey-service",method="get"} 1366
http_requests_total{code="200",endpoint="hey-port", handler="/health",instance="172.17.0.10:8000",job="hey-service",method="get"} 942

We then apply the following expression:

label_join(http_requests_total{instance="172.17.0.10:8000"}, "url", "", "instance", "handler")

We end up with the following instant vector:

http_requests_total{code="200",endpoint="hey-port", handler="/",instance="172.17.0.10:8000",job="hey-service", method="get",url="172.17.0.10:8000/"} 1366
http_requests_total{code="200",endpoint="hey-port", handler="/health",instance="172.17.0.10:8000",job="hey-service", method="get",url="172.17.0.10:8000/health"} 942

When you need to arbitrarily manipulate labels, label_replace is the function to use. The way it works is by applying a regular expression to the value of a chosen source label and storing the matched capture groups on the destination label. Both source and destination can be the same label, effectively replacing its value. This sounds complex, but it really isn't; let's have a look at the syntax of label_replace:

label_replace(<vector>, <destination_label>, <regex_match_result>, <source_label>, <regex>)

Say that we take the preceding sample data and apply the following expression:

label_replace(http_requests_total{instance="172.17.0.10:8000"}, "port", "$1", "instance", ".*:(.*)")

The result will then be the matching elements with the new label, called port:

http_requests_total{code="200",endpoint="hey-port",handler="/", instance="172.17.0.10:8000", job="hey-service",method="get",port="8000"} 1366
http_requests_total{code="200",endpoint="hey-port",handler="/health", instance="172.17.0.10:8000", job="hey-service",method="get",port="8000"} 942

When using label_replace, if the regular expression doesn't match the label value, the originating time series will be returned unchanged.