Skip to content
Tutorials Center
My learning

Topics

Lesson 24 of 39 ยท Dashboards and Alerts

Building Dashboards and Cells

Build InfluxDB dashboards with cells, time-range and window variables, and queries that return the right number of points. Includes runnable stand-ins.

A dashboard turns a stream of timestamps and numbers into something a person can read in two seconds. InfluxDB 2.x ships with a built-in dashboard editor: you create a dashboard, add cells, and give each cell a query and a visualization type. The InfluxDB server and its web UI cannot run in this course, so the queries below are read-only, and the arithmetic behind them is demonstrated with SQL and JavaScript stand-ins.

By the end you will know how a dashboard cell asks for data, what the special variables v.timeRangeStart, v.timeRangeStop and v.windowPeriod mean, and why picking the right window keeps charts fast and readable.

Dashboards, cells and visualizations

  • A dashboard is a page with a time range selector (for example "past 1h") and optional variables.
  • A cell is one panel. Each cell holds one or more queries.
  • A visualization type controls how the result is drawn.

Common visualization types:

Type Good for
Graph (line) Trends over time
Single stat The latest value, such as current temperature
Gauge A value against known bounds
Table Exact values, last seen per device
Heatmap or histogram Distributions and latency buckets
Band A range such as min and max together

Pick the simplest type that answers the question. A "current value" needs a single stat, not a line chart.

What a cell query looks like

Here is a Flux query for a line chart cell, read-only:

JavaScript
from(bucket: "raw")
  |> range(start: v.timeRangeStart, stop: v.timeRangeStop)
  |> filter(fn: (r) => r._measurement == "cpu" and r._field == "usage_user")
  |> filter(fn: (r) => r.host == v.host)
  |> aggregateWindow(every: v.windowPeriod, fn: mean, createEmpty: false)
  |> yield(name: "mean")

The three v. items are dashboard variables that the editor fills in:

  • v.timeRangeStart and v.timeRangeStop come from the time-range picker. When a user switches from "past 1h" to "past 7d", every cell re-queries with new bounds.
  • v.windowPeriod is a duration the UI computes so that the result has a sensible number of points for the chart width. You never hard-code 1m in a dashboard query unless you want that exact resolution.
  • v.host is a custom variable. It can be a constant, a CSV list, or a query such as the distinct values of the host tag.

A single-stat cell for the latest value would end with |> last() instead of aggregateWindow.

For InfluxDB 3, dashboards are usually built in a separate tool such as Grafana or Apache Superset, with SQL queries. The next lessons cover Grafana.

flowchart LR
  P["Time range picker<br/>past 6h"] --> V["Variables<br/>timeRangeStart, windowPeriod, host"]
  V --> C1["Cell 1: line chart"]
  V --> C2["Cell 2: single stat"]
  V --> C3["Cell 3: table"]

Every cell on a dashboard receives the same variables, so changing one control updates all panels.

Why windowPeriod exists

A chart 800 pixels wide cannot show 86,400 points; it shows about one point per pixel at most. Asking the database for more is wasted work and may time out. So the UI divides the selected time range by a target number of points to get a window. A longer range gives a longer window.

This stand-in reproduces the idea. It computes a window that gives about 360 points and rounds it up to a "nice" duration.

JS Stand-in: pick a window period from the time range

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

No output.

The real Flux window logic is the same shape: range divided by a point budget, then snapped to a readable step. You can override it in a cell by writing every: 1m, but then a 30-day chart would need 43,200 points per series.

Stand-in: panel data from SQL

The next example builds the data for three cells on one dashboard from a single readings table: a time series for a line chart, a "latest value" for a single stat, and a "last seen per host" table.

SQL Stand-in: queries behind three dashboard cells

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

In the third query SQLite returns the usage from the row holding the MAX(ts), a feature specific to SQLite. In portable SQL you would join back to the table or use a window function. Flux has last() and group() for this.

Designing a good dashboard

  1. Start from questions. "Is the service healthy right now?" "What changed in the last hour?" Group cells by question.
  2. Top row = health. Put single stats and gauges for the most important values at the top.
  3. One unit per axis. Do not plot bytes and percent on one axis.
  4. Label units and thresholds. Draw threshold colors (green, orange, red) on gauges and single stats so people do not guess.
  5. Limit series. A line chart with 200 lines is unreadable. Filter, or show top N.
  6. Use variables for host, region, or environment so one dashboard serves many targets.
  7. Set an auto-refresh that matches your write rate. Refreshing every 5 seconds against 1-minute data wastes queries.

Sharing and templates

InfluxDB 2.x lets you export a dashboard as a JSON template and import it elsewhere, and community templates exist for common Telegraf inputs. Keep dashboards in version control by exporting templates, so they can be reviewed and restored.

Common mistakes

  • Hard-coding time ranges inside the query, so the picker does nothing.
  • Hard-coding every: 1s and overloading the browser on long ranges.
  • Showing raw high-cardinality series without a filter.
  • Mixing missing data and zero: a gap means "no data", while zero is a real value. See checks and notifications for alerting on missing data.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is v.windowPeriod for?

    The UI divides the range by a point budget to pick a window, keeping queries fast and charts readable.
  2. 2. Which visualization suits 'what is the current temperature?'

    A single stat shows the latest value at a glance.
  3. 3. Why use a dashboard variable such as v.host?

    Variables let viewers choose a host, region or environment without editing queries.
  4. 4. A cell queries a 30-day range with a fixed every: 1s. What is the likely problem?

    30 days at one-second resolution is about 2.6 million points per series.

Summary

  • A dashboard has cells; each cell has a query and a visualization.
  • v.timeRangeStart, v.timeRangeStop and v.windowPeriod tie queries to the time picker.
  • Windows keep the number of points proportional to chart width.
  • Use variables, units, thresholds and a small number of series.
  • InfluxDB 3 dashboards are typically built in Grafana with SQL.

Next: Checks and Notifications