Dashboard variables and templating

Dashboard variables and templating

Variables make a dashboard reusable and parameterized — one board that works for any host, service, or region.

1. Click Variables in the dashboard toolbar.
2. Add a variable with a name, type, and (for query variables) a data source.
3. Reference it in queries with $variable_name.

Variable type	Populated from
Query	A data source query (for example, the list of hosts)
Custom	A manually defined list of values
Text	Free-form text input

Variables render as dropdown filters at the top of the dashboard, so viewers switch context without editing any query.

Worked example: one dashboard for every host

Goal: a reusable infrastructure board where a $host dropdown swaps which machine you're viewing.

1. Create a dashboard and open Variables.
2. Add a Query variable named host, sourced from a query that lists hosts (for example, the distinct host label on system_cpu_usage_total).
3. In each widget, reference the variable in the query:

-- CPU for the selected host
SELECT $__time(timestamp), avg(value) AS cpu
FROM metrics
WHERE metric_name = 'system_cpu_usage_total'
  AND labels['host'] = $host
GROUP BY ts
ORDER BY ts

4. Save. A host dropdown appears at the top of the dashboard.

Expected result: selecting a host in the dropdown repoints every widget to that host — one board serves your whole fleet instead of one-per-machine.

Common mistakes

• Forgetting the labels['host'] = $host filter in a widget, so it ignores the dropdown.
• Sourcing the query variable from a metric that doesn't carry a host label, leaving the dropdown empty.

Watch out — the "All" option is a literal %. A variable's default % shows in the dropdown as All, but it substitutes as the literal string %. It only means "everything" when the query matches with LIKE (labels['host'] LIKE $host). With = or IN, selecting All compares against '%' and returns nothing.

A variable dropdown is empty

Cause: the variable's source query returns nothing, or the label it lists doesn't exist on the chosen metric. Fix: run the variable's query in the Data Explorer; confirm the label (for example, host) actually exists on the target metric and that the time range covers live data.

Strings substitute quoted and escaped; numbers and booleans raw; a multi-value selection becomes a comma-separated list — write labels['host'] IN ($hosts). See Writing widget queries for the full substitution rules and time macros.