promql

Write, validate, and optimize PromQL queries for Prometheus and Grafana Cloud Metrics.

213|18|Updated Mar 17, 2026
One-click install
npx skills add https://github.com/grafana/skills --skill promql-grafana
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: promql
Source: https://github.com/grafana/skills/tree/main/skills/grafana-core/promql
Command: npx skills add https://github.com/grafana/skills --skill promql-grafana

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

This Skill helps engineers and SREs write, validate, and optimize PromQL expressions to produce correct, performant queries and avoid common pitfalls like wrong aggregation order, missing range vectors, and high cardinality.

Core Features & Use Cases

  • Query authoring and validation: Guidance on rate(), increase(), irate(), and correct aggregation placement to ensure accurate per-second or total calculations.
  • Performance and cardinality advice: Recommendations for scrape-interval-aware window sizes, controlling label cardinality, and using topk/count patterns to diagnose heavy series.
  • Recording rules and SLOs: Templates and examples for recording rules, SLO calculations, histogram_quantile usage, and alert-friendly query patterns.

Quick Start

Generate a PromQL query to compute the 5m per-second rate of http_requests_total per service and a recording rule for the p95 request duration.

Frequently Asked Questions about promql

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I write a PromQL query to calculate the per-second rate of requests?

To calculate the per-second rate in PromQL, apply the rate() function to a range vector like http_requests_total[5m]. Ensure you include the time window in brackets and aggregate labels after computing the rate to maintain accuracy.

Why does my Prometheus histogram_quantile query return incorrect percentiles?

Prometheus histogram_quantile returns incorrect percentiles when the le label is missing from the aggregation. You must group by le inside the sum() function before passing the result to histogram_quantile to compute accurate p95 or p99 latency values.

What is the best way to optimize slow Prometheus queries with high cardinality?

To optimize slow Prometheus queries caused by high cardinality, use topk() or count() patterns to identify heavy series. Choose scrape-interval-aware window sizes and apply recording rules to pre-compute expensive expressions for dashboard performance.

How do I create recording rules for SLO calculations in Prometheus?

Create recording rules for SLO calculations by defining PromQL expressions that compute error rates and latency budgets, then saving them as rules in your Prometheus configuration. This pre-computes alert-friendly query patterns for faster dashboard rendering.

Does this work with Grafana Cloud Metrics and Mimir?

Yes, the PromQL queries generated are compatible with Grafana Cloud Metrics and Mimir. The validation covers correct range vectors, aggregation placement, and window sizing to ensure performant time-series expressions across these platforms.

When should I aggregate labels before or after using rate() in PromQL?

You should always aggregate labels after using rate() in PromQL. Aggregating before applying rate() to a counter produces mathematically incorrect results because it sums counter resets, leading to inaccurate per-second calculations.