Terminal
Terminal/Skill
Writes, validates, and optimizes PromQL queries for Prometheus, Mimir, and Grafana Cloud Metrics, including percentiles, error rates, and SLO burn rates.
By Grafana Labs
Works with
npx skills add grafana/skills --skill promqlDocs: https://prometheus.io/docs/prometheus/latest/querying/basics/
PromQL returns either an instant vector, a range vector, or a scalar.
Golden rule: rate() / increase() require a range vector ≥ 4× the scrape interval. 60s scrape → use [5m] minimum.
/api/v1/query or via Grafana Explore)references/patterns.md# 0. Point at your Prometheus/Mimir. For Grafana Cloud, use the metrics endpoint
# and add basic auth (-u "<metrics_user>:<token>") to each curl below.
PROM=http://localhost:9090 # or https://prometheus-prod-XX.grafana.net/api/prom
# 1. Sketch the query — for "5xx error rate per service":
EXPR='sum(rate(http_requests_total{status_code=~"5.."}[5m])) by (service)'
# 2. Validate syntax + that the metric/labels exist
curl -sG --data-urlencode "query=${EXPR}" \
"$PROM/api/v1/query" | jq '.status, (.data.result|length)'
# Expect: "success" and result count > 0. If 0 — check label spelling and scrape activity:
curl -sG --data-urlencode "match[]=http_requests_total" "$PROM/api/v1/series" | jq '.data | length'
# 3. Sanity-check the magnitude — open Grafana Explore, paste the expr,
# confirm the values look right against a known ground truth (k6 run, log count, etc.)
Per-status request rate (aggregate AFTER rate):
sum(rate(http_requests_total{job="api"}[5m])) by (status_code)
p95 latency (must keep le in the inner aggregation):
histogram_quantile(0.95,
sum(rate(http_request_duration_seconds_bucket[5m])) by (le, service))
Error rate with divide-by-zero guard:
sum(rate(http_requests_total{status_code=~"5.."}[5m]))
/ (sum(rate(http_requests_total[5m])) > 0)
Full library (recording rules, SLO burn-rate, offsets, cardinality hunt, native histograms): references/patterns.md.
# 1. Pick the slow expression, give it a recording-rule name
groups:
- name: http_request_rates
interval: 1m
rules:
- record: job:http_request_duration_p95:rate5m
expr: |
histogram_quantile(0.95,
sum(rate(http_request_duration_seconds_bucket[5m])) by (le, job))
# 2. After rules load, verify the new metric exists
curl -sG --data-urlencode "query=job:http_request_duration_p95:rate5m" \
"$PROM/api/v1/query" | jq '.data.result | length' # → > 0
# 3. Verify it matches the original expression for at least one sample window
# (Both queries should produce the same value at the same timestamp.)
# 4. Replace the dashboard panel expression with the recording-rule metric.
histogram_quantile returns NaN → forgot by (le) in the inner aggregation/api/v1/series) and the window ≥ 4× scrape intervalrate() (always rate() first)topk(...) + a recording rule + drop high-cardinality labels (see references/patterns.md)