Promql Generator

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

1. 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

1. 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

1. 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

1. 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

1. 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"}

1. Aggregation: Should the data be aggregated?

• No aggregation: Return all time series as-is
• Aggregate by labels: sum by (job, endpoint), avg by (instance)
• Aggregate without labels: sum without (instance, pod), avg without (job)
• Common aggregations: sum, avg, max, min, count, topk, bottomk

1. Thresholds or Conditions: Are there specific conditions?

• For alerting: threshold values (e.g., error rate > 5%)
• For filtering: only show series above/below a value
• For comparison: compare against historical data (offset)

Use the AskUserQuestion tool to gather or confirm these parameters. When the user has already provided values (e.g., "5-minute window", "> 5%"), present them as the default option for confirmation.

Stage 4: Present the Query Plan

BEFORE GENERATING ANY CODE, present a plain-English query plan and ask for user confirmation:

## PromQL Query Plan

Based on your requirements, here's what the query will do:

**Goal**: [Describe the monitoring goal in plain English]

**Query Structure**:
1. Start with metric: `[metric_name]`
2. Filter by labels: `{label1="value1", label2="value2"}`
3. Apply function: `[function_name]([metric][time_range])`
4. Aggregate: `[aggregation] by ([label_list])`
5. Additional operations: [any calculations, ratios, or transformations]

**Expected Output**:
- Data type: [instant vector/scalar]
- Labels in result: [list of labels]
- Value represents: [what the number means]
- Typical range: [expected value range]

**Example Interpretation**:
If the query returns `0.05`, it means: [plain English explanation]

**Does this match your intentions?**
- If yes, I'll generate the query and validate it
- If no, let me know what needs to change

Use the AskUserQuestion tool to confirm the plan with options:

• "Yes, generate this query"
• "Modify [specific aspect]"
• "Show me alternative approaches"

When the user chooses:

• "Modify [specific aspect]": ask one focused follow-up question about what to change (metric, labels, function, time range, threshold, or output shape), then present an updated plan before generating.