Prometheus Aggregation Functions on Range Vectors

In Prometheus, aggregation functions like sum, avg, max, and min are often used to work with "instant vectors," which represent a snapshot of data at a specific moment in time. However, sometimes you need to analyze the data over a period of time, like the last 15 minutes or the past 24 hours. Prometheus provides powerful functions for this purpose, which work with "range vectors" (data over a time range).

 

In this blog post, we'll introduce these aggregation functions and demonstrate how they can help you gain more insights from your time-series data.

 

What is a Range Vector?

A range vector in Prometheus is a set of data points collected over a specific time interval. For example, you can query data for the past 1 hour or the past 24 hours using a range vector, which lets you analyze the data across that period.

 

For example, the query:

scrape_duration_seconds[2m]

 

gives you the scrape durations (over the last 15 minutes) for the scrape_duration_seconds metric.

 

Aggregation Functions on Range Vectors

Prometheus provides several aggregation functions that you can use to analyze range vectors. Here are some of the most commonly used functions:

 

Function	Description	Example
avg_over_time	Calculates the average value of all points in the specified interval.	avg_over_time(cpu_usage_seconds[15m])
min_over_time	Finds the minimum value of all points in the specified interval.	min_over_time(cpu_temperature_celsius[1h])
max_over_time	Finds the maximum value of all points in the specified interval.	max_over_time(http_requests_total[30m])
sum_over_time	Sums all values in the specified interval.	sum_over_time(memory_usage_bytes[10m])
count_over_time	Counts the number of values in the specified interval.	count_over_time(disk_reads_total[5m])
quantile_over_time	Calculates the φ-quantile (where 0 ≤ φ ≤ 1) of the values in the specified interval.	quantile_over_time(0.95, response_latency_seconds[1h])
last_over_time	Returns the most recent point value in the specified interval.	last_over_time(up[30m])
present_over_time	Returns the value 1 for any series that has data in the specified interval (indicating whether data is present).	present_over_time(up[24h])

 

Example

max_over_time(scrape_duration_seconds[24h]) 

 

Response JSON

{
  "status": "success",
  "data": {
    "resultType": "vector",
    "result": [
      {
        "metric": {
          "instance": "localhost:9090",
          "job": "prometheus"
        },
        "value": [1744434361.088, "0.070034167"]
      },
      {
        "metric": {
          "instance": "localhost:9100",
          "job": "node_exporter"
        },
        "value": [1744434361.088, "0.252153542"]
      }
    ]
  }
}

 

This query returns the maximum scrape duration for the past 24 hours, grouped by the instance and job labels.

 

Special Considerations

·      Histogram Handling: Some functions, such as avg_over_time, sum_over_time, count_over_time, last_over_time, and present_over_time, handle native histograms in a straightforward way, but other functions (like max_over_time) ignore histogram samples.

 

·      Uniform Weighting: All values within the specified range have the same weight, regardless of whether they are evenly spaced over time or not.

 

·      Experimental Functions: If you enable the feature flag --enable-feature=promql-experimental-functions, you can use additional functions like mad_over_time, which computes the median absolute deviation.

 

In summary, Prometheus aggregation functions on range vectors allows you to analyze your time-series data over time rather than just at a single point. These functions are powerful tools for gaining insights into how your data changes over specified periods. Whether you're calculating averages, finding maximum values, or counting occurrences, these aggregation functions provide the flexibility to work with your data effectively.

 

Previous                                                    Next                                                    Home