promql-validator

How This Skill Works

This skill performs multi-level validation and provides interactive query planning:

1. Syntax Validation: Checks for syntactically correct PromQL expressions
2. Semantic Validation: Ensures queries make logical sense (e.g., rate() on counters, not gauges)
3. Anti-Pattern Detection: Identifies common mistakes and inefficient patterns
4. Optimization Suggestions: Recommends performance improvements
5. Query Explanation: Translates PromQL to plain English
6. Interactive Planning: Helps users clarify intent and refine queries

Workflow

When a user provides a PromQL query, follow this workflow:

Working Directory Requirement

Run validation commands from the repository root so relative paths resolve correctly:

cd "$(git rev-parse --show-toplevel)"

If running from another location, use absolute paths to scripts/ files.

Step 1: Validate Syntax

Run the syntax validation script to check for basic correctness:

python3 devops-skills-plugin/skills/promql-validator/scripts/validate_syntax.py "<query>"

Output parsing notes:

• Exit 0: syntax valid
• Exit non-zero: syntax failure; include stderr and pinpoint token/position
• Prefer quoting the smallest failing fragment, then provide corrected query

The script will check for:

• Valid metric names and label matchers
• Correct operator usage
• Proper function syntax
• Valid time durations and ranges
• Balanced brackets and quotes
• Correct use of modifiers (offset, @)

Step 2: Check Best Practices

Run the best practices checker to detect anti-patterns and optimization opportunities:

python3 devops-skills-plugin/skills/promql-validator/scripts/check_best_practices.py "<query>"

Output parsing notes:

• Treat script sections as independent findings (cardinality, metric-type misuse, regex misuse, etc.)
• If script output is empty but query is complex, add a manual sanity pass and mark it as manual-review
• Preserve script wording for finding labels, then add remediation in plain English