PromQL is Prometheus’s query language for selecting, aggregating, and calculating time-series metrics. It supports operational analysis, Grafana visualizations, and alert conditions. section 2.4.2 section 7.2.1
A common pattern calculates an HTTP error rate by dividing the five-minute rate of status-code-500 requests by the five-minute rate of all requests, then multiplying by 100. section 2.4.2
PromQL supports several practical workflows:
- Filter metric series with label matchers, such as selecting a particular HTTP status code or handler. section 6.1.1
- Aggregate and transform series with functions such as rate and sum for service-level measurements. section 2.4.2
- Parameterize Grafana dashboards with variables so users can choose label values, including HTTP status codes and handlers. section 6.1.1
- Define alert expressions that Prometheus evaluates periodically before handing firing alerts to Alertmanager. section 7.2.1
Service error-rate query
sum (rate(echo_total{http_status_code="500"}[5m])) / sum (rate(echo_total[5m])) * 100 produces the percentage of recent requests returning HTTP 500. The same metric can be explored in Grafana through a Prometheus data source.
Parameterized dashboard query
rate(prometheus_http_requests_total{code="$test"}[5m]) lets a Grafana dashboard variable choose the HTTP status code. Selecting a label value that does not exist can leave the panel empty. section 6.1.1
