A quick reference for PromQL (Prometheus Query Language) syntax and functions.
Select current value of time series:
http_requests_total{job="api"}
http_requests_total{job="api", status="200"}
| 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"}
Select range of samples over time:
http_requests_total{job="api"}[5m]
Time durations:
| Unit | Meaning |
|---|
ms | milliseconds |
s | seconds |
m | minutes |
h | hours |
d | days |
w | weeks |
y | years |
Query past data:
http_requests_total offset 1h
# Range ending 1 hour ago
http_requests_total[5m] offset 1h
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()
| Operator | Description |
|---|
+ | Addition |
- | Subtraction |
* | Multiplication |
/ | Division |
% | Modulo |
^ | Exponentiation |
process_resident_memory_bytes / 1024 / 1024
(node_memory_MemFree_bytes / node_memory_MemTotal_bytes) * 100
| Operator | Description |
|---|
== | Equal |
!= | Not equal |
> | Greater than |
< | Less than |
>= | Greater or equal |
<= | Less or equal |
# Boolean result (1 or 0)
| Operator | Description |
|---|
and | Intersection |
or | Union |
unless | Complement |
(cpu_usage > 80) and (memory_usage > 80)
(cpu_usage > 90) or (memory_usage > 90)
# First without matching second
http_requests_total unless http_requests_total{status="200"}
# Match only on specific labels
metric_a / on(instance) metric_b
# Match ignoring specific labels
metric_a / ignoring(env) metric_b
# 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
| 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 by (job, instance) (http_requests_total)
sum without (instance) (http_requests_total)
topk(5, http_requests_total)
bottomk(3, http_requests_total)
# 90th percentile across series
quantile(0.9, http_request_duration_seconds)
| 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])
| 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])
# Percentile from histogram
histogram_quantile(0.95, rate(http_request_duration_bucket[5m]))
sum by (le, job) (rate(http_request_duration_bucket[5m]))
| Function | Description |
|---|
resets(v) | Count of counter resets |
resets(http_requests_total[1h])
| 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 |
label_join(metric, "new_label", "-", "label1", "label2")
label_replace(metric, "short", "$1", "instance", "(.*):.*")
| 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)
| Function | Description |
|---|
vector(s) | Scalar to vector |
scalar(v) | Vector to scalar |
| 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)
# Linear prediction: value in 4 hours
predict_linear(disk_used_bytes[1h], 4 * 3600)
# Derivative (rate of change for gauges)
| 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])))
| 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
sum(rate(http_requests_total{status=~"5.."}[5m]))
sum(rate(http_requests_total[5m]))
avg_over_time(up[24h]) * 100
sum by (status) (rate(http_requests_total[5m]))
sum by (le) (rate(http_request_duration_seconds_bucket[5m]))
topk(5, sum by (endpoint) (rate(http_requests_total[5m])))
(1 - (node_memory_MemAvailable_bytes / node_memory_MemTotal_bytes)) * 100
# Time until disk full (seconds)
(node_filesystem_avail_bytes / (rate(node_filesystem_avail_bytes[1h]) * -1)) > 0
rate(node_disk_io_time_weighted_seconds_total[5m])
sum by (mode) (rate(node_cpu_seconds_total[5m])) * 100
increase(http_requests_total[24h])
# Requests per second increase/decrease
deriv(http_requests_total[5m])
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>]
