Skip to content
Osuite Osuite Docs

Dashboard template variables

Overview

Section titled “Overview”

A template variable is a named placeholder you reference inside a panel’s PromQL and select from a control at the top of the dashboard. Instead of hardcoding a service or namespace into every query and copying the dashboard per target, you define the variable once and repoint the whole dashboard by changing the selector.

You reference a variable in a query by its name with a $ prefix. A variable named service is written $service; a variable named namespace is written $namespace.

sum(rate(http_requests_total{service="$service"}[5m])) by (status_code)

Changing the service selector re-runs every panel that references $service.

Defining a variable

Section titled “Defining a variable”

Each variable has a name (how you reference it in queries) and an order (its position among the selectors). It can also have a display label — a friendlier text shown in the selector control while queries keep using the variable name.

Where a variable’s values come from

Section titled “Where a variable’s values come from”

A variable’s list of selectable values can be populated from your metrics or supplied as a fixed list:

  • Label names — the set of label names available in your metrics.
  • Label values — the values of a particular label, optionally scoped to a specific metric.
  • Metric names — the list of metric names.
  • Custom values — a fixed list of key/value entries you provide, where the value is used in the query and the key is what the selector shows.

Because the query-backed options read from your live metrics, the selector stays in sync with what is actually being ingested — a new service or namespace appears in the dropdown on its own.

Multi-select

Section titled “Multi-select”

A variable can allow a single value or multiple values at once. A multi-select variable is useful when a query should span several targets, for example a set of namespaces in one panel.

Using variables across panels

Section titled “Using variables across panels”

Reference the same variable in as many panels as you like. One $service selector can drive an entire service dashboard — request rate, latency, error rate, and saturation panels all filtered to the selected service. Combine variables (for example $namespace and $service) to narrow further.

The Visualizer Agent reuses existing dashboard variables in the queries it generates, so a dashboard built by the agent respects the variables you already defined.

Next steps

Section titled “Next steps”