Using PromQL Functions

1. Calculating Histogram Quantile

Function	Description	Parameters	Example
histogram_quantile()	Calculates the quantile of a histogram	`quantile` (float), `histogram` (vector)	Example: `histogram_quantile(0.95, http_request_duration_seconds_bucket)`

Note: The histogram_quantile function requires the histogram to be in a bucket format, where each bucket represents an upper bound.

2. Using Rounding Functions

Function	Description	Example	Notes
ceil()	Rounds up to the nearest integer	`ceil(http_requests_total)`	Useful for ensuring resource allocation is at least the required amount
floor()	Rounds down to the nearest integer	`floor(cpu_usage_percent)`	Useful for ensuring resource allocation does not exceed the limit
round()	Rounds to the nearest integer	`round(memory_usage_bytes)`	Useful for converting floating point values to integers

Example: Using ceil() to round up

ceil(http_requests_total)

This function ensures that any fractional part of a value is rounded up to the next integer, which can be useful for calculating resource allocation or capacity planning.

Example: Using floor() to round down

floor(cpu_usage_percent)

This function ensures that any fractional part of a value is rounded down to the previous integer, which can be useful for ensuring that resource limits are not exceeded.

Example: Using round() for nearest integer

round(memory_usage_bytes)

This function rounds to the nearest integer, which can be useful for converting floating point values into whole numbers for display or further processing.

3. Implementing Clamping

Function	Description	Parameters	Example
clamp_min	Clamps values to a minimum threshold	`vector, min`	Example: clamp_min `clamp_min(prometheus_http_requests_total, 100)`
clamp_max	Clamps values to a maximum threshold	`vector, max`	Example: clamp_max `clamp_max(prometheus_http_requests_total, 1000)`
clamp	Clamps values between a minimum and maximum threshold	`vector, min, max`	Example: clamp `clamp(prometheus_http_requests_total, 100, 1000)`

Note: These functions are useful for normalizing metrics or setting hard limits on values to prevent outliers from skewing visualizations.

4. Working with Time Functions

Function	Description	Example	Notes
time()	Returns the Unix timestamp (in seconds) of the current evaluation time	`time()`	Useful for calculating durations or time-based operations
hour()	Returns the hour of the day (0-23) for a given timestamp	`hour(time())`	Can be used to filter or group data by hour
minute()	Returns the minute of the hour (0-59) for a given timestamp	`minute(time())`	Useful for sub-hourly aggregations or filtering
second()	Returns the second of the minute (0-59) for a given timestamp	`second(time())`	Can be used for second-level precision in time-series data
day_of_week()	Returns the day of the week (0-6) for a given timestamp, where 0 is Sunday	`day_of_week(time())`	Useful for filtering or grouping by day of the week
day_of_month()	Returns the day of the month (1-31) for a given timestamp	`day_of_month(time())`	Can be used for daily aggregations or filtering
month()	Returns the month (1-12) for a given timestamp	`month(time())`	Useful for monthly grouping or filtering
year()	Returns the year for a given timestamp	`year(time())`	Can be used for yearly aggregations or filtering

Example: Using time() to calculate duration

rate(http_requests_total[5m]) * 60

This expression calculates the rate of HTTP requests per minute over a 5-minute window, which is useful for monitoring request rates.

Example: Filtering by hour of day

http_requests_total{hour(time()) >= 9 && hour(time()) <= 17}

This expression filters HTTP requests to only those that occurred during business hours (9 AM - 5 PM).

Note: Time functions in PromQL are evaluated at query time, not at scrape time. This means that the timestamp used for calculations is determined by when the query is executed, not when the metric was scraped.

5. Using Sorting Functions

Function	Description	Example	Notes
sort()	Sorts metrics by their value in ascending order	`sort(up)`	Sorts metrics by value
sort_desc()	Sorts metrics by their value in descending order	`sort_desc(up)`	Sorts metrics by value in descending order
sort_by_label()	Sorts metrics by a specific label value	`sort_by_label(up, instance)`	Sorts metrics by the value of the `instance` label
sort_by_label_desc()	Sorts metrics by a specific label value in descending order	`sort_by_label_desc(up, instance)`	Sorts metrics by the value of the `instance` label in descending order

Example: Sorting metrics by value

sort(up)

Example: Sorting metrics by label value

sort_by_label(up, instance)

6. Implementing Vector Matching

Operator	Description	Example
+	Addition of vectors	`rate(http_requests_total[5m]) + rate(http_errors_total[5m])`
-	Subtraction of vectors	`http_requests_total - http_errors_total`
*	Multiplication of vectors	`http_requests_total * 2`
/	Division of vectors	`http_requests_total / http_errors_total`
%	Modulo operation on vectors	`http_requests_total % 10`
^	Exponentiation of vectors	`http_requests_total ^ 2`
==	Equality comparison (returns 1 if true, 0 otherwise)	`http_requests_total == http_errors_total`
!=	Inequality comparison (returns 1 if true, 0 otherwise)	`http_requests_total != http_errors_total`
<	Less than comparison (returns 1 if true, 0 otherwise)	`http_requests_total < http_errors_total`
>	Greater than comparison (returns 1 if true, 0 otherwise)	`http_requests_total > http_errors_total`
<=	Less than or equal comparison (returns 1 if true, 0 otherwise)	`http_requests_total <= http_errors_total`
>=	Greater than or equal comparison (returns 1 if true, 0 otherwise)	`http_requests_total >= http_errors_total`
and	Logical AND between vectors	`http_requests_total and http_errors_total`
or	Logical OR between vectors	`http_requests_total or http_errors_total`
unless	Logical NOT between vectors	`http_requests_total unless http_errors_total`

Example: Vector Matching with Labels


rate(http_requests_total[5m]) + rate(http_errors_total[5m])

Note: When performing operations between vectors, Prometheus matches the vectors based on their label sets. If labels don't match, the operation results in a scalar or no result.

Warning: Vector matching can lead to unexpected results if labels are not properly aligned. Always ensure that the label sets of vectors being operated on are compatible.

7. Computing Absolute Values

Prometheus provides the abs() function to compute the absolute value of a metric.

Function	Description	Example
abs()	Returns the absolute value of a metric	`abs(metric_name)`

Example: Using abs() function

abs(http_requests_total)

The abs() function is useful when dealing with metrics that may have negative values, such as temperature readings or financial data.

8. Using Label Functions

Function	Description	Example	Notes
label_replace()	Replaces label values using a regular expression.	`label_replace(metric, "new_label", "$1", "old_label", "(.*).com")`	Matches the regex and replaces with capture group.
label_join()	Joins multiple label values into one.	`label_join(metric, "joined_label", ":", "label1", "label2")`	Uses separator to join label values.
label_set()	Sets a label value to a specific string.	`label_set(metric, "env", "production")`	Overwrites or adds a label with fixed value.
label_map()	Maps label values to new values using a mapping function.	`label_map(metric, "status", "map", "error")`	Applies a mapping function to label values.

Example: Using label_replace to Normalize Hostnames

label_replace(up{job="node_exporter"}, "host", "$1", "instance", "(.*):.*")

Example: Using label_join to Combine Environment and Service

label_join(up{job="prometheus"}, "env_service", "_", "environment", "service")

9. Using Mathematical Functions

Function	Description	Example	Notes
abs()	Returns the absolute value of a scalar	`abs(-5)`	Applies to scalar values only
absent()	Returns 1 if the scalar is absent, 0 otherwise	`absent(up)`	Useful for alerting on missing metrics
ceil()	Rounds up to the nearest integer	`ceil(3.14)`	Scalar function
exp()	Natural exponential function (e^x)	`exp(1)`	Returns scalar value
floor()	Rounds down to the nearest integer	`floor(3.9)`	Scalar function
ln()	Natural logarithm (log base e)	`ln(2.718)`	Scalar function
log2()	Base-2 logarithm	`log2(8)`	Scalar function
log10()	Base-10 logarithm	`log10(100)`	Scalar function
sqrt()	Square root of a scalar	`sqrt(16)`	Scalar function
sgn()	Returns the sign of a scalar (-1, 0, or 1)	`sgn(-5)`	Scalar function

Example: Using abs() to handle negative values

abs(http_response_time_seconds)

Example: Using ceil() to round up response times

ceil(http_response_time_seconds)

Note: Mathematical functions in PromQL are scalar-only and do not operate on vector elements directly.

10. Implementing Exponential Functions

Function	Description	Example	Notes
exp()	Calculates the exponential function e^x	`exp(http_requests_total)`	Applies to each sample in the vector
exp10()	Calculates 10^x	`exp10(http_requests_total)`	Useful for logarithmic scales
pow()	Calculates x^y for two vectors	`pow(http_requests_total, 2)`	Can be used for squaring or higher powers
sqrt()	Calculates the square root of each sample	`sqrt(http_requests_total)`	Useful for normalization or variance calculations

Note: Exponential functions in PromQL are vectorized and apply element-wise to time series data.

11. Using Trigonometric Functions

Function	Description	Example	Notes
sin()	Returns the sine of the input value (in radians)	`sin(vector)`	Input must be in radians
cos()	Returns the cosine of the input value (in radians)	`cos(vector)`	Input must be in radians
tan()	Returns the tangent of the input value (in radians)	`tan(vector)`	Input must be in radians
asin()	Returns the arcsine of the input value (in radians)	`asin(vector)`	Input must be in radians
acos()	Returns the arccosine of the input value (in radians)	`acos(vector)`	Input must be in radians
atan()	Returns the arctangent of the input value (in radians)	`atan(vector)`	Input must be in radians
atan2()	Returns the arctangent of y/x in radians	`atan2(y, x)`	Arguments must be in radians

Note: All trigonometric functions in PromQL expect input values to be in radians. These functions are useful for time-series data that represents periodic or oscillating behavior.

12. Understanding sgn Function

Function	Description	Example	Notes
sgn()	Returns the sign of a number: 1 if positive, -1 if negative, 0 if zero.	`sgn(-5.2) = -1 sgn(3.7) = 1 sgn(0) = 0`	Useful for determining the direction of a value in time series data.

Example: Using sgn in a Query

sgn(node_memory_available_bytes)

Note: The sgn function is particularly useful in anomaly detection or when analyzing trends where the sign of a metric is more important than its magnitude.