Tech

PromQL cheat sheet

PromQL cheat sheet. Explore our ultimate quick reference for PromQL.

Search in this cheat sheet:

Here’s a PromQL (Prometheus Query Language) cheat sheet to help you quickly grasp its essential concepts and syntax. PromQL is a powerful language used to query and extract meaningful insights from Prometheus time-series data. This cheat sheet covers key query types, functions, and operators, making it easier to analyze system metrics effectively. Use it as a handy reference for building PromQL queries efficiently.

Basic Query Elements

Metric Names

Directly query a metric by its name:
```
http_requests_total
```

Labels & Filtering

Filter metrics using labels:

http_requests_total{job="api-server", status="500"}

Use regex matching:
```
http_requests_total{method=~"GET|POST"}
```
Negation example:
```
http_requests_total{status!="200"}
```

Operators

Arithmetic Operators

Basic math operations:
```
rate(http_requests_total[5m]) * 100
```

Comparison Operators

Compare two expressions:
```
http_requests_total > 100
```
Keep matching labels using bool:
```
http_requests_total > bool 100
```

Logical Operators

and, or, unless:

http_requests_total{job="api-server"} and up

Aggregation

Common Aggregation Functions

Sum:
```
sum(http_requests_total)
```
Average:
```
avg(http_requests_total)
```

Minimum & Maximum:

min(http_requests_total)
max(http_requests_total)

Standard Deviation & Variance:

stddev(http_requests_total)
stdvar(http_requests_total)

Grouping

Aggregate by a label:
```
sum by (status) (http_requests_total)
```

Removing a label from aggregation:

sum without (instance) (http_requests_total)

Time Ranges & Rate Calculations

Instant & Range Vectors

Instant query (current value):
```
http_requests_total
```
Range query (past 5 minutes):
```
http_requests_total[5m]
```

Rate & Increase

Rate of increase per second:
```
rate(http_requests_total[5m])
```
Total increase over a period:
```
increase(http_requests_total[1h])
```

Delta & Resets

Change in value over time:
```
delta(http_requests_total[5m])
```
Ignore counter resets:
```
resets(http_requests_total[1h])
```

Advanced Functions

Histogram Quantiles

90th percentile of request durations:

histogram_quantile(0.90, rate(http_request_duration_seconds_bucket[5m]))

Time Functions

Current Unix timestamp:
```
time()
```

Label Manipulation

Rename labels:

label_replace(up, "new_label", "$1", "instance", "(.*):.*")

Drop specific labels:

label_join(up, "group", "-", "datacenter", "rack")

Tips and Sources

Useful Tips

Always use rate() for counters to avoid misinterpretations.
Use sum by (label) when grouping metrics by a specific dimension.
Be cautious with large queries to avoid high computational costs.
histogram_quantile() works with histograms, not normal counters.

Reliable Sources

Prometheus Documentation: https://prometheus.io/docs/querying/basics/
PromQL Examples: https://promlabs.com/promql-cheat-sheet
Grafana PromQL Guide: https://grafana.com/docs/grafana/latest/datasources/prometheus/promql/