How to Query Grafana with Prometheus: Beginner’s Tutorial

If you’ve just started exploring observability stacks, you’ve probably heard the names Grafana and Prometheus tossed around together. They’re a powerful duo: Prometheus gathers time‑series data, while Grafana turns that data into visual dashboards you can actually read. This article walks you through a hands‑on Grafana and Prometheus query tutorial for beginners, covering installation, basic PromQL syntax, and the steps to display those queries in Grafana panels.

Getting Grafana and Prometheus Up and Running

Before you can write any queries, both services need to be installed and talking to each other. The simplest route is to use Docker Compose; a single file can spin up a Prometheus server, a Grafana instance, and even a sample exporter like node_exporter to feed some metrics.

Here’s a minimal docker‑compose.yml snippet:

• version: '3.8'
• services:
•   prometheus:
•     image: prom/prometheus
•     volumes:
•       - ./prometheus.yml:/etc/prometheus/prometheus.yml
•   grafana:
•     image: grafana/grafana
•     ports:
•       - "3000:3000"
•     environment:
•       - GF_SECURITY_ADMIN_PASSWORD=secret

After you run docker compose up -d, point your browser to http://localhost:9090 for Prometheus and http://localhost:3000 for Grafana. The default Grafana login is admin / secret (or whatever password you set).

Next, add Prometheus as a data source in Grafana: Settings → Data Sources → Add data source → Prometheus → URL http://prometheus:9090. Save, and you’re ready to start querying.

Writing Your First PromQL Queries

Prometheus uses its own query language, PromQL, which feels a bit like SQL but is tuned for time‑series. The most basic query is simply the name of a metric, for example node_cpu_seconds_total. That returns a series of values for every CPU core on every host that the node exporter is scraping.

To make the data readable, you’ll often apply a function. rate(node_cpu_seconds_total[5m]) calculates the per‑second average over the last five minutes, turning a cumulative counter into a rate. If you only care about a single core, you can filter with label matchers: rate(node_cpu_seconds_total{cpu="0"}[5m]).

Here are three starter queries you’ll use a lot:

• CPU usage per core: rate(node_cpu_seconds_total[1m])
• Memory usage percentage: 100 - (node_memory_MemAvailable_bytes / node_memory_MemTotal_bytes * 100)
• Disk I/O rates: rate(node_disk_reads_completed_total[5m])

Play with the time range selector in the Prometheus UI to see how the results change. The “instant” mode shows a single snapshot, while “range” mode returns a series you can graph.

Visualizing Queries in Grafana Panels

Now that you have a query, it’s time to bring it into a Grafana dashboard. Click “+ → Dashboard”, then “Add new panel”. In the query editor, select your Prometheus data source and paste the PromQL expression.

Grafana automatically suggests a visualization type based on the data shape. A line chart works well for rates, while a gauge or singlestat is handy for single‑value metrics like node_memory_MemFree_bytes. Adjust the panel title, axis labels, and thresholds to make the information pop.

For a quick health overview, you might combine several panels on one screen: a CPU line chart, a memory gauge, and a table that lists the top five processes by CPU consumption. Remember to set the dashboard’s refresh interval (e.g., every 30 seconds) so the panels stay up‑to‑date.

Common Pitfalls and Tips for Beginners

Don’t forget label selectors. A query without a selector returns data for every instance you’re scraping, which can overwhelm the UI. Narrow the scope with braces, e.g., {job="node"} .

Avoid high‑resolution queries on large time ranges. Asking Prometheus to calculate rate(...[1s]) over a month will strain the server. Stick to a reasonable step size (15s‑1m) for long periods.

Use recording rules. If a query is expensive and you need it often, define a rule in rules.yml to pre‑compute the result. Then query the new metric name instead of the raw expression.

Validate your data source. If a panel stays blank, check the “Explore” view in Grafana. It shows raw query results and any error messages from Prometheus, helping you pinpoint syntax errors or missing labels.

Frequently Asked Questions

What’s the difference between rate() and irate()?

rate() computes an average over the specified range, smoothing short spikes, while irate() uses only the two most recent points, giving a more instantaneous view. Use rate() for general trends and irate() for troubleshooting sudden spikes.

Can I query multiple Prometheus servers from a single Grafana instance?

Yes. Add each server as a separate data source, then create panels that reference the appropriate source. For cross‑server aggregations you’d need a federation setup or a tool like Thanos.

How do I export a Grafana dashboard to share with teammates?

Open the dashboard, click the share icon, and choose “Export JSON”. Your colleagues can import that file via “Create → Import” in their Grafana UI, preserving panels, queries, and layout.

Is there a way to alert on query results?

Absolutely. In Prometheus, define alerting rules in alerts.yml that evaluate a PromQL expression against a threshold. Grafana can then display those alerts, forward them to Slack, PagerDuty, or other notification channels.