Prometheus: Up & Running, 2nd Edition

Chapter 16. Functions

PromQL has 69 functions as of 2.37.0, and offers you a wide variety of functionality, from common math to functions specifically for dealing with counter and histogram metrics. In this chapter you will learn about how all the functions work and how they can be used.

Almost all PromQL functions return instant vectors, and the three that don’t (time, pi, and scalar) return scalars. No functions return range vectors, though multiple functions, including rate and avg_over_time that you have already seen, take a range vector as input.

Put another way, functions generally work either across the samples of a single time series at a time or across the samples of an instant vector. If you want to process an entire range vector at once, you would need to use subqueries.

PromQL is statically typed, functions do not change their return value based on the input types. In fact, the input types for each function are also fixed. Where a function needs to work with two different types, two different names are used. For example, you use the avg aggregator on instant vectors and the avg_over_time function on range vectors.

There are no official categories for the functions, but we have grouped related functions together.

Changing Type

At times you will have a vector but need a scalar, or vice versa. There are two functions that allow you to do so: vector and scalar.

vector

The vector function takes a scalar value, and converts it into an instant vector with one sample without ...