Prometheus: Up & Running

Chapter 16. Functions

PromQL has 46 functions as of 2.2.1, 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 two that don’t (time 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. There is no single function or feature of PromQL that you can use to process an entire range vector at once.

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 I 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

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