PromQL Reference

Professional

A quick reference for PromQL (Prometheus Query Language) syntax and functions.

Selectors

Instant Vector Selectors

Select current value of time series:

# By metric name
http_requests_total

# With label filter
http_requests_total{job="api"}

# Multiple filters (AND)
http_requests_total{job="api", status="200"}

Label Matchers

Matcher	Description	Example
`=`	Equal	`job="api"`
`!=`	Not equal	`job!="test"`
`=~`	Regex match	`job=~"api\|web"`
`!~`	Regex not match	`job!~"test.*"`

# Regex: job starts with "prod"
http_requests_total{job=~"prod.*"}

# Regex: status is 4xx or 5xx
http_requests_total{status=~"[45].."}

# Exclude multiple values
http_requests_total{env!~"dev|staging"}

Range Vector Selectors

Select range of samples over time:

# Last 5 minutes
http_requests_total[5m]

# Last 1 hour
http_requests_total[1h]

# With label filter
http_requests_total{job="api"}[5m]

Time durations:

Unit	Meaning
`ms`	milliseconds
`s`	seconds
`m`	minutes
`h`	hours
`d`	days
`w`	weeks
`y`	years

Offset Modifier

Query past data:

# Value 1 hour ago
http_requests_total offset 1h

# Range ending 1 hour ago
http_requests_total[5m] offset 1h

@ Modifier

Query at specific timestamp:

# Value at specific Unix timestamp
http_requests_total @ 1609459200

# Value at start of query range
http_requests_total @ start()

# Value at end of query range
http_requests_total @ end()

Operators

Arithmetic Operators

Operator	Description
`+`	Addition
`-`	Subtraction
`*`	Multiplication
`/`	Division
`%`	Modulo
`^`	Exponentiation

# Bytes to megabytes
process_resident_memory_bytes / 1024 / 1024

# Percentage
(node_memory_MemFree_bytes / node_memory_MemTotal_bytes) * 100

# Power
metric ^ 2

Comparison Operators

Operator	Description
`==`	Equal
`!=`	Not equal
`>`	Greater than
`<`	Less than
`>=`	Greater or equal
`<=`	Less or equal

# Filter: CPU > 80%
cpu_usage > 80

# Boolean result (1 or 0)
cpu_usage > bool 80

Logical/Set Operators

Operator	Description
`and`	Intersection
`or`	Union
`unless`	Complement

# Both conditions true
(cpu_usage > 80) and (memory_usage > 80)

# Either condition true
(cpu_usage > 90) or (memory_usage > 90)

# First without matching second
http_requests_total unless http_requests_total{status="200"}

Vector Matching

On / Ignoring

# Match only on specific labels
metric_a / on(instance) metric_b

# Match ignoring specific labels
metric_a / ignoring(env) metric_b

Group Modifiers

# Many-to-one: keep labels from left side
requests / on(instance) group_left(env) instance_info

# One-to-many: keep labels from right side
instance_info * on(instance) group_right(path) requests

Aggregation Operators

Basic Aggregations

Operator	Description
`sum`	Sum of values
`min`	Minimum value
`max`	Maximum value
`avg`	Average value
`count`	Count of elements
`count_values`	Count by value
`stddev`	Standard deviation
`stdvar`	Standard variance
`group`	Group (returns 1)

sum(http_requests_total)
avg(cpu_usage)
max(memory_usage)
count(up)

Aggregation Clauses

# Keep specific labels
sum by (job, instance) (http_requests_total)

# Remove specific labels
sum without (instance) (http_requests_total)

TopK / BottomK

# Top 5 by value
topk(5, http_requests_total)

# Bottom 3 by value
bottomk(3, http_requests_total)

Quantile

# 90th percentile across series
quantile(0.9, http_request_duration_seconds)

Functions

Rate Functions

Function	Description
`rate(v)`	Per-second rate over range
`irate(v)`	Instant per-second rate (last 2 points)
`increase(v)`	Total increase over range
`delta(v)`	Difference (for gauges)
`idelta(v)`	Instant difference (last 2 points)

# Requests per second (recommended)
rate(http_requests_total[5m])

# Instant rate (more volatile)
irate(http_requests_total[1m])

# Total increase over 1 hour
increase(http_requests_total[1h])

# Change in gauge value
delta(temperature[1h])

Aggregation Over Time

Function	Description
`avg_over_time(v)`	Average over time
`min_over_time(v)`	Minimum over time
`max_over_time(v)`	Maximum over time
`sum_over_time(v)`	Sum over time
`count_over_time(v)`	Count over time
`quantile_over_time(φ, v)`	Quantile over time
`stddev_over_time(v)`	Std deviation over time
`stdvar_over_time(v)`	Std variance over time
`last_over_time(v)`	Last value in range
`present_over_time(v)`	1 if any value present

avg_over_time(cpu_usage[1h])
max_over_time(memory_usage[24h])
quantile_over_time(0.95, latency[1h])

Histogram Functions

# Percentile from histogram
histogram_quantile(0.95, rate(http_request_duration_bucket[5m]))

# With aggregation
histogram_quantile(0.95,
  sum by (le, job) (rate(http_request_duration_bucket[5m]))
)

Counter Functions

Function	Description
`resets(v)`	Count of counter resets

resets(http_requests_total[1h])

Label Functions

Function	Description
`label_join(v, dst, sep, src...)`	Join labels into new label
`label_replace(v, dst, repl, src, regex)`	Replace/create label via regex

# Join labels
label_join(metric, "new_label", "-", "label1", "label2")

# Replace label value
label_replace(metric, "short", "$1", "instance", "(.*):.*")

Math Functions

Function	Description
`abs(v)`	Absolute value
`ceil(v)`	Round up
`floor(v)`	Round down
`round(v, to)`	Round to nearest
`clamp(v, min, max)`	Clamp to range
`clamp_min(v, min)`	Clamp minimum
`clamp_max(v, max)`	Clamp maximum
`exp(v)`	Exponential
`ln(v)`	Natural log
`log2(v)`	Binary log
`log10(v)`	Decimal log
`sqrt(v)`	Square root
`sgn(v)`	Sign (-1, 0, 1)

abs(delta(temperature[1h]))
round(avg(latency), 0.001)
clamp(cpu_usage, 0, 100)

Type Functions

Function	Description
`vector(s)`	Scalar to vector
`scalar(v)`	Vector to scalar

Time Functions

Function	Description
`time()`	Current Unix timestamp
`timestamp(v)`	Timestamp of samples
`day_of_month(v)`	Day of month (1-31)
`day_of_week(v)`	Day of week (0-6)
`day_of_year(v)`	Day of year (1-366)
`days_in_month(v)`	Days in month (28-31)
`hour(v)`	Hour (0-23)
`minute(v)`	Minute (0-59)
`month(v)`	Month (1-12)
`year(v)`	Year

# Hours since last scrape
(time() - timestamp(up)) / 3600

# Filter by day of week (Monday=1)
metric and on() (day_of_week() == 1)

Prediction Functions

# Linear prediction: value in 4 hours
predict_linear(disk_used_bytes[1h], 4 * 3600)

# Derivative (rate of change for gauges)
deriv(temperature[1h])

Sorting

Function	Description
`sort(v)`	Sort ascending
`sort_desc(v)`	Sort descending
`sort_by_label(v, label)`	Sort by label
`sort_by_label_desc(v, label)`	Sort by label desc

sort_desc(sum by (job) (rate(http_requests_total[5m])))

Other Functions

Function	Description
`absent(v)`	Returns 1 if no series
`absent_over_time(v)`	Returns 1 if no series in range
`changes(v)`	Count of value changes
`histogram_count(v)`	Count from native histogram
`histogram_sum(v)`	Sum from native histogram

# Alert if metric is missing
absent(up{job="api"})

# Count of value changes
changes(config_hash[1h])

Common Patterns

Error Rate (%)

sum(rate(http_requests_total{status=~"5.."}[5m]))
/
sum(rate(http_requests_total[5m]))
* 100

Availability (%)

avg_over_time(up[24h]) * 100

Request Rate by Status

sum by (status) (rate(http_requests_total[5m]))

P95 Latency

histogram_quantile(0.95,
  sum by (le) (rate(http_request_duration_seconds_bucket[5m]))
)

Top 5 by Request Rate

topk(5, sum by (endpoint) (rate(http_requests_total[5m])))

Memory Usage %

(1 - (node_memory_MemAvailable_bytes / node_memory_MemTotal_bytes)) * 100

Disk Full Prediction

# Time until disk full (seconds)
(node_filesystem_avail_bytes / (rate(node_filesystem_avail_bytes[1h]) * -1)) > 0

Saturation (Queue Depth)

rate(node_disk_io_time_weighted_seconds_total[5m])

CPU by Mode

sum by (mode) (rate(node_cpu_seconds_total[5m])) * 100

Increase Over Time Period

# Total requests today
increase(http_requests_total[24h])

Rate of Change

# Requests per second increase/decrease
deriv(http_requests_total[5m])

Subqueries

Run range functions on instant vector results:

# Max of 5-minute rates over 1 hour
max_over_time(rate(http_requests_total[5m])[1h:])

# With explicit resolution
max_over_time(rate(http_requests_total[5m])[1h:1m])

Syntax: <instant_query>[<range>:<resolution>]