Documentation Grafana Cloud AI and machine learning Grafana Assistant Query assistance PromQL workflows

PromQL workflows

Lean on this guide when you want to generate or refine PromQL without memorizing syntax. The steps help you draft, validate, and apply queries safely.

What you’ll achieve

• Draft PromQL expressions for range or instant queries based on natural language prompts.
• Validate and iterate on existing queries to add aggregations, filters, and intent metadata.
• Apply queries to dashboards or Explore sessions and capture summaries for stakeholders.

Before you begin

• Prometheus data source: Mention the data source with @ so the Assistant uses the right handler.
• Time window: Know the timeframe you want to analyze.

Draft the query

Explain the metric and aggregations you need so the Assistant can produce PromQL that matches your goal.

1. Describe the metric, labels, and aggregation you need using natural language; you do not need to remember PromQL syntax.

Copy

Create a PromQL query in @prometheus-ds that shows p95 latency for checkout_service over the last hour.

2. Ask for variations if you need instant vs. range queries or different rollups.

Copy

Provide both a range query and an instant query version.

Validate and iterate

Check the generated expression for syntax and intent, refining filters and groupings until the output matches your expectations.

• Use the Assistant to validate syntax and catch missing labels:

Copy

Validate this query and ensure it ignores retries and focuses on namespace=production.

• Request grouping, sorting, or rate conversions, for example, Group by region and sort by highest error rate.
• If the query returns too much data, ask the Assistant to suggest filters or downsampling strategies.
• Correct mistakes politely, mention the label, threshold, or data source that needs to change, so the Assistant stays aligned with your intent.

Apply the query

Put the finished query to work by embedding it in dashboards or Explore sessions and summarizing what it reveals.

• Ask the Assistant to insert the query into a dashboard panel or Explore session.
• Request a summary of what the query reveals to confirm the output matches your intent.

Share the finished PromQL

You now have a tested PromQL query and a summary you can share with teammates or include in dashboards, alerts, or investigations.

Troubleshooting

• Query returns nothing: confirm the metric name and labels exist, for example, Search for metrics matching http_request_duration_seconds.
• Interval mismatches: specify the evaluation period, for example, Use a 5-minute rate window.
• Cardinality concerns: ask for alternative aggregations or label filtering to keep the result manageable.
• Switching to a different problem: open a new conversation so previous PromQL context does not bleed into the new request.

Next steps

• Learn LogQL workflows to query logs alongside your metrics.
• Use queries in Dashboard management to create visualizations.
• Convert stable PromQL expressions into alerts after validation.
• Share finalized queries in your team’s runbooks.