Skip to content

HOME

PromQL

PromQL

PromQL

Basic Concepts

Metric: A time series data point.
Labels: Key-value pairs associated with metrics.
Selectors: Expressions to filter time series based on labels.

Data Types

Instant Vector: Set of time series containing a single sample per time series, all sharing the same timestamp.
Range Vector: Set of time series containing a range of data points over time.
Scalar: A single numerical value.
String: A single string value.

Selectors

Instant Vector Selector: metric_name{label_name="label_value"}

Operators

Arithmetic Operators: +, -, *, /, %, ^
Comparison Operators: ==, !=, >, <, >=, <=
Logical/Set Operators: and, or, unless

Functions

Aggregation Functions

sum(): Sum of values.
avg(): Average of values.
max(): Maximum value.
min(): Minimum value.
count(): Count of values.
stddev(): Standard deviation of values.
stdvar(): Variance of values.
topk(k, metric): Top k elements by value.
bottomk(k, metric): Bottom k elements by value.
count_values(): Count of occurrences of each distinct value.

Special Functions

rate(): Per-second average rate of increase.
increase(): Increase in the value over a specified range.
delta(): Difference between the first and last value.
irate(): Instantaneous rate of increase.
idelta(): Instantaneous difference.
histogram_quantile(): Quantile of histogram data.

Time Functions

time(): Current time as a UNIX timestamp.
timestamp(): Return the UNIX timestamp of a given time series.

Examples

Basic Metric Selection

All metrics named http_requests_total:
```
http_requests_total
```
All metrics named http_requests_total with label job="api":
```
http_requests_total{job="api"}
```

Range Queries

Rate of increase per second for http_requests_total over the last 5 minutes:
```
rate(http_requests_total[5m])
```
Sum of rates of increase per second for http_requests_total over the last 5 minutes:
```
sum(rate(http_requests_total[5m]))
```

Aggregation

Average value of http_requests_total by job:
```
avg(http_requests_total) by (job)
```
Sum of http_requests_total by instance:
```
sum(http_requests_total) by (instance)
```

Mathematical Operations

Increase in http_requests_total over the last 5 minutes:
```
increase(http_requests_total[5m])
```
Requests per second:
```
rate(http_requests_total[1m])
```

Conditional Expressions

All http_requests_total metrics where instance is not "localhost:9090":
```
http_requests_total{instance!="localhost:9090"}
```
All http_requests_total metrics where instance label regex matches "app":
```
http_requests_total{instance=~"app.*"}
```

Time-based Queries

Current UNIX timestamp:
```
time()
```
Timestamp of the up metric:
```
timestamp(up)
```

Quantiles

90th percentile of http_request_duration_seconds histogram:

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

Combining Metrics

Divide metric_a by metric_b:
```
metric_a / metric_b
```
Sum of metric_a and metric_b:
```
metric_a + metric_b
```

Best Practices

Use Aggregation for Large Data Sets: Aggregate data to avoid overwhelming the system with too many time series.
Leverage Label Filters: Use labels to filter and refine queries for more precise results.
Avoid Overuse of rate(): Use rate() judiciously, especially over short intervals, to avoid misleading spikes.

For more detailed use cases and advanced queries, refer to the Prometheus documentation.