PromQL Basics

PromQL is the query language used to retrieve and process metrics stored in Prometheus. This section covers fundamental syntax for filtering, aggregating, and transforming time series data. Key concepts include time series selectors, aggregation functions, and pipeline operations that enable you to derive actionable insights from raw metrics.

Filtering Time Series Data¶

PromQL queries start with a time series selector, which filters metrics by label sets. Use curly braces {} to specify label matchers.

Example: Selecting Metrics by Label¶

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

This query retrieves all time series for http_requests_total where the job label is "api-server" and the status label is "200".

Handling Missing Data¶

Use absent() to detect missing metrics:

absent(http_requests_total{job="api-server"})

This returns 1 if no time series matches the selector, 0 otherwise.

Aggregation and Reduction¶

Aggregation functions collapse multiple time series into a single time series. Use by to group results by specific labels.

Example: Calculating Average Requests¶

avg(http_requests_total{job="api-server"}) by (method)

This computes the average http_requests_total per HTTP method (e.g., GET, POST).

Reduction Functions¶

Common reduction functions include:
- sum(): Sum all values in the time series.
- max(): Find the maximum value.
- count(): Count the number of time series.
- top_k(): Return the top k values.

Example: Counting Active Instances¶

count by (instance)(up{job="web-server"})

This counts how many up metrics are reported for each instance label.

Transforming Metrics with Pipeline Functions¶

Pipeline functions modify metrics in a streaming fashion, enabling operations like rate calculation or anomaly detection.

Example: Calculating Request Rate¶

rate(http_requests_total{job="api-server"}[5m])

This computes the per-second rate of http_requests_total over the last 5 minutes.

Time-Shift and Changes¶

Use time_shift() to compare metrics across time:

time_shift(http_requests_total{job="api-server"}[5m], 1h)

Use changes() to detect how many times a metric changed:

changes(http_errors_total{job="api-server"}[5m])

Combining Queries¶

Use operators like and, or, and unless to combine selectors. Group time series using on() or by() for reduction.

Example: Cross-Metric Analysis¶

http_requests_total{job="api-server"} 
  and 
http_errors_total{job="api-server"} 
  on (job)

This combines metrics from two different time series by the job label.

Example: Grouping by Multiple Labels¶

avg(http_requests_total{job="api-server"}) 
  by (method, status)

This groups results by both method and status labels.

Key takeaways¶

Use {label="value"} to filter metrics and absent() to detect missing data.
Aggregation functions like avg(), sum(), and count() collapse time series for analysis.
Pipeline functions (e.g., rate(), changes()) transform metrics for trend analysis.
Combine queries with and, or, and on() to correlate metrics across labels.
Always use by to group results by relevant labels when aggregating.