Skip to content
Tutorials Center
My learning

Topics

Lesson 26 of 39 ยท Dashboards and Alerts

Using Grafana with InfluxDB

Connect Grafana to InfluxDB with Flux, InfluxQL or SQL, build template variables, and write safe time-series queries. Includes runnable query-building stand-ins.

Grafana is the most popular open-source dashboard tool for time-series data, and it works with every InfluxDB generation. Teams choose it when they want one dashboard tool for several data sources, richer panels than the built-in InfluxDB UI, or alerting that spans systems. For InfluxDB 3 it is the usual dashboard choice, since the built-in 2.x UI does not exist there.

You will learn how a Grafana data source maps to an InfluxDB version, how template variables work, and how to write queries that follow the dashboard's time range. Grafana and InfluxDB cannot run in this browser course, so the configuration is read-only, and the variable and query logic is demonstrated with runnable JavaScript and SQL.

Choosing the query language

When you add an InfluxDB data source in Grafana, you pick a query language, and it must match what your server supports:

Query language Server Notes
InfluxQL 1.x, 2.x (with a compatibility mapping), 3.x SQL-like, simple
Flux 2.x (and 1.8+) Powerful, functional pipelines
SQL 3.x Standard-like SQL on Apache DataFusion

Connection details differ. For 2.x you supply the URL, organization, a default bucket and an API token. For 3.x you supply the URL, database name and a token. Always use a token with read-only permission on just the buckets or databases the dashboard needs.

A provisioning file keeps the data source in version control. Read-only example for 2.x with Flux:

YAML
apiVersion: 1
datasources:
  - name: InfluxDB-Flux
    type: influxdb
    access: proxy
    url: http://influxdb:8086
    jsonData:
      version: Flux
      organization: my-org
      defaultBucket: raw
    secureJsonData:
      token: "${INFLUX_READ_TOKEN}"

Keep the token in an environment variable or secret store, never in the file you commit.

Time range and window in Grafana

In Flux panels Grafana injects the same kind of variables you saw in dashboards and cells:

JavaScript
from(bucket: v.defaultBucket)
  |> range(start: v.timeRangeStart, stop: v.timeRangeStop)
  |> filter(fn: (r) => r._measurement == "cpu" and r.host == "${host}")
  |> aggregateWindow(every: v.windowPeriod, fn: mean)

v.windowPeriod follows the panel width, and v.timeRangeStart follows the picker. In SQL panels, Grafana offers macros for the selected time range and interval; check the data source's query editor help for the exact macro names in your Grafana version, and use them rather than hard-coded timestamps.

The dashboard-level variable ${host} comes from a drop-down.

Template variables

A template variable replaces a hard-coded value with a control. A query variable gets its options from the database, for example every distinct host. In Flux:

JavaScript
import "influxdata/influxdb/schema"

schema.tagValues(bucket: "raw", tag: "host")

In InfluxDB 3 SQL the equivalent is a distinct query:

SQL
SELECT DISTINCT host FROM cpu ORDER BY host

Variables can be multi-value (select many hosts) and include an All option. Grafana then substitutes a list into the query, in the syntax the language needs: for Flux you often use a regex or contains() with an array; for SQL an IN (...) list.

Stand-in: building the query like Grafana does

Grafana does simple text substitution before sending the query. This JavaScript stand-in does the same for a multi-value variable and shows why quoting matters. It escapes single quotes so that a hostile or odd value cannot break the SQL string.

JS Stand-in: substitute a multi-value variable safely

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The second line stays one harmless string literal: the single quote is doubled so it is data, not syntax. Grafana does proper escaping for its own variables, but this shows why you must never paste raw user text into a query by hand.

Stand-in: a variable query and a panel query

This SQL run shows the two kinds of query behind a typical Grafana panel: the variable query that fills the drop-down, and a panel query that applies the selected value.

SQL Stand-in: variable query then panel query

Press Run (or Ctrl + Enter) to see the result here.

Alerting in Grafana

Grafana alert rules run a query on a schedule, reduce the result to a number, compare it with a threshold, and notify a contact point (email, Slack, webhook). This is how you alert on InfluxDB 3, which has no built-in checks. Follow the guidance in checks and notifications: alert on durations, notify on change, and add a "no data" rule so a silent source does not look healthy.

Performance tips for Grafana panels

  • Always bound the query with the dashboard time range.
  • Aggregate to the panel's window instead of plotting raw points.
  • Select only the columns or fields you chart.
  • Query a downsampled bucket for long ranges (see downsampling).
  • Avoid many panels with an auto-refresh of a few seconds against a small server.
  • Use a read-only token and a dedicated user per dashboard group.

Common mistakes

  • Choosing the wrong query language for the server version, giving confusing errors.
  • Using an admin token in the data source, so anyone who can edit the data source can reach everything.
  • Hard-coding timestamps, so the time picker does nothing.
  • Forgetting the All option behaviour: with many hosts the query may return thousands of series.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which query language does InfluxDB 3 use in Grafana?

    InfluxDB 3 supports SQL and InfluxQL. Flux belongs to 2.x (and 1.8+).
  2. 2. What kind of token should a dashboard data source use?

    Least privilege keeps a dashboard compromise from becoming a data compromise.
  3. 3. What does a query variable do?

    A query variable runs a query and offers the results as dashboard options.
  4. 4. Why escape variable values before putting them in SQL text?

    Escaping keeps the value as data and prevents injection.

Summary

  • Match the Grafana query language to the server: InfluxQL, Flux or SQL.
  • Use a read-only token, stored as a secret.
  • Follow the time range with variables or macros and aggregate to the panel window.
  • Query variables fill drop-downs; multi-value variables expand into lists, safely quoted.
  • Grafana alerting covers InfluxDB 3.

Next: Series Cardinality