Using PromQL Special Functions

1. Calculating Time Deltas

Function	Description	Example	Notes
delta()	Calculates the difference between the first and last value in a time series over a given range.	`delta(http_requests_total[5m])`	Useful for calculating total changes over a time window.
idelta()	Calculates the difference between the last two values in a time series.	`idelta(http_requests_total)`	Best for instantaneous changes or deltas between samples.
increase()	Calculates the increase in a counter over a given time range, handling resets.	`increase(http_requests_total[1h])`	Essential for counter metrics that reset over time.
rate()	Calculates the per-second average rate of increase for a counter over a time range.	`rate(http_requests_total[5m])`	Useful for rate-based alerting and monitoring.
irate()	Calculates the per-second rate of increase based on the last two samples.	`irate(http_requests_total[5m])`	Better for short-term rate calculations with less smoothing.

Example: Using delta() to calculate total requests over time

delta(http_requests_total[1h])

This expression calculates the total number of HTTP requests over the last hour, assuming http_requests_total is a counter metric.

Example: Using increase() to handle counter resets

increase(http_requests_total[1d])

This expression calculates the increase in HTTP requests over a day, correctly handling any counter resets that may have occurred during that period.

2. Using Vector Constructors

Function	Description	Example	Notes
vector()	Constructs a vector from a scalar value.	`vector(10)`	Creates a vector with one element having the value 10.
time()	Returns the current UNIX timestamp as a vector.	`time()`	Useful for time-based calculations or metric creation.
now()	Returns the current UNIX timestamp as a scalar.	`now()`	Similar to `time()`, but returns a scalar.
group()	Groups all samples in a vector into one sample.	`group(metric)`	Useful for aggregating metrics into a single value.
clamp()	Clamps values to a specified range.	`clamp(metric, 0, 100)`	Ensures values stay within a defined min/max range.

3. Implementing Scalar Conversion

Function	Description	Example	Notes
scalar()	Converts a single-element vector to a scalar.	`scalar(up{job="prometheus"})`	Must contain exactly one element, otherwise returns an error.
time()	Returns the current Unix timestamp as a scalar.	`time() - scalar(up)`	Useful for calculating durations or time differences.
vector()	Converts a scalar to a vector with a single element.	`vector(100)`	Creates a vector with the scalar value as its value and no labels.

Example: Using scalar() to calculate uptime

time() - scalar(up{job="prometheus"})

This expression calculates the time elapsed since the Prometheus server was last up.

4. Using Changes Function

The changes() function in PromQL calculates the number of times a metric's value has changed within a specified time range.

Function	Signature	Description
changes()	`changes(metric[time_range])`	Returns the number of times the value of the metric has changed in the specified time range.

Example: Using changes() to count value changes in a time window

changes(http_requests_total[5m])

This query returns the number of times http_requests_total has changed in the last 5 minutes.

Note: The changes() function is particularly useful for identifying metrics that are frequently updated or experiencing high volatility.

Warning: If the metric has a very high rate of change, changes() may return a large number and could impact query performance.

5. Implementing Resets Detection

Resets in Prometheus occur when a counter metric drops to zero or decreases, which can happen due to counter resets, process restarts, or metric recreation. Detecting resets is crucial for accurate metric analysis.

Method	Description	Usage
rate()	Calculates the per-second average rate of increase of a counter over a time window.	`rate(counter_metric[5m])`
increase()	Calculates the increase in a counter over a time window, accounting for resets.	`increase(counter_metric[1h])`
delta()	Calculates the difference between the last and first value in a range vector.	`delta(counter_metric[1h])`

Example: Detecting Counter Resets with `rate()`

rate(http_requests_total[5m])

This query returns the per-second rate of increase for http_requests_total. If a reset occurs, the rate will spike or become negative.

Example: Using `increase()` to Detect Resets

increase(http_requests_total[1h])

This query calculates the total increase in http_requests_total over the last hour. If a reset occurs, it will show a negative value or zero.

Note: rate() and increase() are designed to handle counter resets automatically, but they may not always provide clear signals in the presence of complex resets or resets due to metric recreation.

Warning: When using rate(), if a counter resets, it can cause a spike in the returned rate. This is not an error but a signal that requires attention.

6. Using Deriv Function

The deriv() function in PromQL is used to calculate the per-second derivative of a time series, which represents the rate of change of the metric over time. It's particularly useful for identifying trends and anomalies in metrics that are monotonically increasing.

Function	Description	Example
deriv(metric)	Calculates the derivative of a metric over time	`deriv(http_requests_total)`

Example: Calculating Derivative of Counter

deriv(http_requests_total)

This expression calculates the per-second rate of increase for http_requests_total, which is useful for understanding how quickly the number of HTTP requests is growing.

Note: The deriv() function is best suited for counter metrics that are monotonically increasing. It may not provide meaningful results for gauges or other metric types.

Warning: When using deriv(), be cautious of metrics that reset to zero, as this can cause large spikes in the derivative value.

7. Using Absent Functions

Prometheus provides several functions to detect and handle missing data, particularly useful for alerting or monitoring systems where data gaps may indicate issues.

Function	Description	Example
absent()	Returns 1 if the vector is empty, otherwise 0. Useful for detecting missing metrics.	`absent(http_requests_total{method="GET"})`
absent_over_time()	Checks if a metric has been absent over a specified time range. Returns 1 if no samples were found in the window.	`absent_over_time(http_requests_total[5m])`

Note: These functions are particularly useful in alerting rules to detect when metrics stop being scraped or when a metric is missing entirely.

8. Implementing Day of Week

Function	Description	Example	Notes
day_of_week()	Returns the day of the week for a given timestamp (0 = Sunday, 1 = Monday, ..., 6 = Saturday)	`day_of_week(timestamp)`	Useful for time-series analysis based on day of the week

Example: Extracting Day of Week from a Metric

day_of_week(time() + 3600 * 24 * 5)

Note: The function day_of_week() operates on Unix timestamps and returns an integer between 0 and 6.

9. Using Hour of Day

The hour() function in PromQL returns the hour of the day for a given timestamp, expressed as an integer from 0 to 23.

Function	Description	Example
hour()	Returns the hour of the day (0-23) for a given timestamp.	`hour(time())`

Example: Hour of Day in a Query

hour(node_cpu_seconds_total{cpu="cpu0"})

Note: The hour() function is useful for analyzing time-series data by hour, such as identifying peak CPU usage during specific hours of the day.

10. Calculating Year and Month

Function	Description	Example	Notes
year()	Returns the year of a timestamp in UTC	`year(timestamp)`	Useful for time-based grouping or filtering
month()	Returns the month of a timestamp in UTC (1-12)	`month(timestamp)`	Useful for monthly aggregation or analysis

Note: These functions operate on timestamps in unix_timestamp format (seconds since epoch).

11. Implementing Days in Month

Function	Description	Example	Notes
days_in_month()	Returns the number of days in a given month for a specific year	`days_in_month(2024, 2)`	Supports leap year calculations
days_in_month(timestamp)	Calculates the number of days in the month of a given timestamp	`days_in_month(time() + 3600)`	Uses the current time if no timestamp is provided

Example: Calculating Days in a Month

days_in_month(2024, 2) // Returns 29 (leap year)
days_in_month(2023, 2) // Returns 28 (non-leap year)
days_in_month(2024, 1) // Returns 31

12. Using Day of Month

Function	Description	Example	Notes
day_of_month()	Returns the day of the month for a given timestamp.	`day_of_month(timestamp)`	Accepts a timestamp in seconds since Unix epoch.

Note: The function day_of_month() is useful for filtering or grouping metrics by day of the month in queries.