/promql-generator

name: promql-generator
description: Generate/create/write PromQL queries, metric expressions, alerting rules, recording rules, Prometheus dashboards.

PromQL Query Generator

Overview

This skill provides a comprehensive, interactive workflow for generating production-ready PromQL queries with best practices built-in. Generate queries for monitoring dashboards, alerting rules, and ad-hoc analysis with an emphasis on user collaboration and planning before code generation.

When to Use This Skill

Invoke this skill when:

• Creating new PromQL queries from scratch
• Building monitoring dashboards (Grafana, Prometheus UI, etc.)
• Implementing alerting rules for Prometheus Alertmanager
• Analyzing metrics for troubleshooting or capacity planning
• Converting monitoring requirements into PromQL expressions
• Learning PromQL or teaching others
• The user asks to "create", "generate", "build", or "write" PromQL queries
• Working with Prometheus metrics (counters, gauges, histograms, summaries)
• Implementing RED (Rate, Errors, Duration) or USE (Utilization, Saturation, Errors) metrics

Interactive Query Planning Workflow

**CRITICAL**: This skill emphasizes **interactive planning** before query generation. Always engage the user in a collaborative planning process to ensure the generated query matches their exact intentions.

Follow this workflow when generating PromQL queries:

Stage 1: Understand the Monitoring Goal

Start by understanding what the user wants to monitor or measure. Ask clarifying questions to gather requirements:

1. **Primary Goal**: What are you trying to monitor or measure?

• Request rate (requests per second)
• Error rate (percentage of failed requests)
• Latency/duration (response times, percentiles)
• Resource usage (CPU, memory, disk, network)
• Availability/uptime
• Queue depth, saturation, throughput
• Custom business metrics

2. **Use Case**: What will this query be used for?

• Dashboard visualization (Grafana, Prometheus UI)
• Alerting rule (firing when threshold exceeded)
• Ad-hoc troubleshooting/analysis
• Recording rule (pre-computed aggregation)
• Capacity planning or SLO tracking

3. **Context**: Any additional context?

• Service/application name
• Team or project
• Priority level
• Existing metrics or naming conventions

Use the **AskUserQuestion** tool to gather this information if not provided.

> **When to Ask vs. Infer**: If the user's initial request already clearly specifies the goal, use case, and context (e.g., "Create an alert for P95 latency > 500ms for payment-service"), you may acknowledge these details in your response instead of re-asking. Only ask clarifying questions for information that is missing or ambiguous.

Stage 2: Identify Available Metrics

Determine which metrics are available and relevant:

1. **Metric Discovery**: What metrics are available?

• Ask the user for metric names
• If uncertain, suggest common naming patterns
• Check for metric type indicators in the name:
• `_total` suffix → Counter
• `_bucket`, `_sum`, `_count` suffix → Histogram
• No suffix → Likely Gauge
• `_created` suffix → Counter creation timestamp

2. **Metric Type Identification**: Confirm the metric type(s)

• **Counter**: Cumulative metric that only increases (or resets to zero)
• Examples: `http_requests_total`, `errors_total`, `bytes_sent_total`
• Use with: `rate()`, `irate()`, `increase()`
• **Gauge**: Point-in-time value that can go up or down
• Examples: `memory_usage_bytes`, `cpu_temperature_celsius`, `queue_length`
• Use with: `avg_over_time()`, `min_over_time()`, `max_over_time()`, or directly
• **Histogram**: Buckets of observations with cumulative counts
• Examples: `http_request_duration_seconds_bucket`, `response_size_bytes_bucket`
• Use with: `histogram_quantile()`, `rate()`
• **Summary**: Pre-calculated quantiles with count and sum
• Examples: `rpc_duration_seconds{quantile="0.95"}`
• Use `_sum` and `_count` for averages; don't average quantiles

3. **Label Discovery**: What labels are available on these metrics?

• Common labels: `job`, `instance`, `environment`, `service`, `endpoint`, `status_code`, `method`
• Ask which labels are important for filtering or grouping

Use the **AskUserQuestion** tool to confirm metric names, types, and available labels.

Stage 3: Determine Query Parameters

Gather specific requirements for the query.

Pre-confirmation for User-Provided Parameters

**IMPORTANT**: When the user has already specified parameters in their initial request (e.g., "5-minute window", "500ms threshold", "> 5% error rate"), you MUST:

1. **Acknowledge the provided values** explicitly in your response 2. **Present them as pre-filled defaults** in AskUserQuestion with the first option being "Use specified values" 3. **Allow quick confirmation** rather than re-asking for information already given

**Example**: If user says "alert when P95 latency exceeds 500ms", use:

AskUserQuestion:
- Question: "Confirm the alert threshold?"
- Options:
  1. "500ms (as specified)" - Use the threshold from your request
  2. "Different threshold" - Let me specify a different value

This respects the user's input and speeds up the workflow while still allowing modifications.

1. **Time Range**: What time window should the query cover?

• Instant value (current)
• Rate over time (`[5m]`, `[1h]`, `[1d]`)
• For rate calculations: typically `[1m]` to `[5m]` for real-time, `[1h]` to `[1d]` for trends
• Rule of thumb: Rate range should be at least 4x the scrape interval

2. **Label Filtering**: Which labels should filter the data?

• Exact matches: `job="api-server"`, `status_code="200"`
• Negative matches: `status_code!="200"`
• Regex matches: `instance=~"prod-.*"`
• Multiple conditions: `{job="api", environment="production"}`

3. **Aggregation**: Should the data be aggreg