promql-validator_skill

Overview

This skill is a comprehensive toolkit for validating, optimizing, and explaining Prometheus Query Language (PromQL) expressions. It checks syntax, enforces semantic rules, detects anti-patterns, and helps plan queries interactively with the user. Use it to make queries correct, efficient, and fit-for-purpose for alerts, dashboards, or analysis.

How this skill works

The validator runs multi-stage checks: syntax validation first, then semantic checks (e.g., correct use of rate() on counters), followed by anti-pattern detection and performance analysis. It produces a plain-English explanation of the query, lists output labels and result structure, and then enters an interactive planning phase that asks clarifying questions before making tailored fixes. The workflow enforces a two-phase dialogue: validate and explain, STOP and wait for the user’s intent, then proceed with intent-aware corrections and optimizations.

When to use it

• Review a new PromQL query before adding it to a dashboard or alerting rule
• Diagnose slow or high-cardinality queries in Prometheus
• Teach team members how a query works and why it matters
• Refactor repeated complex queries into recording rules
• Check queries for correct use of counters, gauges, histograms, and summaries

Best practices

• Always validate syntax and semantic usage (rate/increase only on counters)
• Add specific label matchers to reduce cardinality instead of using open selectors
• Prefer exact matches (=) over regex (=~) when possible
• Use rate() with a range at least 4x the scrape interval; use irate() for short ranges
• Use recording rules for expensive or frequently-run complex queries

Example use cases

• Convert raw counter metrics to per-second rates for dashboards: rate(http_requests_total[5m])
• Detect and fix high-cardinality wildcard queries like metric{} by adding label filters
• Rewrite averaged summary quantiles into histogram_quantile() using buckets and rate()
• Optimize subqueries or suggest recording rules for long-range processing
• Interactive session to confirm alerting thresholds and precise aggregation labels