Documentation Plugins Wavefront Template variables

Wavefront template variables

Use template variables to build dynamic, reusable dashboards with the Wavefront data source. For general information about template variables in Grafana, refer to Variables.

Before you begin

• Configure the Wavefront data source.
• Create a dashboard where you want to use variables.

Supported variable types

For ad hoc filter setup, refer to Ad hoc filters on the query editor page.

Query variable types

Wavefront query variables have a Query Type, a Query expression, and (for the Tag Values type) a Tag field. All query types require a non-empty Query; an empty query returns invalid query.

The Query expression

The data source sends the Query field to Wavefront’s key lookup API after variable interpolation. Enter a metric pattern or expression that Wavefront can use to find matching metrics, sources, or tags, including:

• A metric name, for example sample.cpu.loadavg.1m.
• A wildcard metric pattern, for example sample.cpu.*.
• The ~ prefix for internal or demo metrics, for example ~sample.cpu.*.
• A pattern combined with tag filters, for example sample.cpu.*, env="prod".

The field’s placeholder, ~sample.cpu.*, is a safe default because it targets the built-in Wavefront sample metrics.

Template variables in the Query field

You can reference other dashboard variables in the Query and Tag fields. The data source interpolates them before calling the Wavefront API, which makes it easy to build dependent variables:

text Copy

~kubernetes.$cluster.pod.cpu.usage_rate

When a variable has multiple values selected, the plugin expands key=$var into (v1 or v2) so Wavefront receives a valid filter. You don’t need to configure a special variable format.

Legacy query formats

Variables created before plugin v2.0.0 used string-based queries such as metrics: ts(...) or sources: cpu.*. The plugin automatically migrates those queries when they load:

You don’t need to edit migrated variables unless you want to use the newer UI fields.

Create a query variable

To create a Wavefront query variable:

1. Open your dashboard and click the gear icon to open dashboard settings.
2. Select Variables and click Add variable.
3. Set Select variable type to Query.
4. Set Data source to your Wavefront data source.
5. In the query editor, set Query Type to one of the types listed in the preceding table.
6. Enter a Query expression. For Tag Values, also fill in the Tag field.
7. Optionally enable Multi-value or Include All option to let users select multiple values.
8. Click Run query to preview results.
9. Click Apply to save the variable.

Query examples

List all sample CPU metrics:

• Query Type: Metrics
• Query: ~sample.cpu.*

List all sources reporting CPU metrics:

• Query Type: Hosts / Sources
• Query: ~sample.cpu.*

List the source tag keys available on sources reporting CPU metrics:

• Query Type: Host Tags / Source Tags
• Query: ~sample.cpu.*

List the tag keys that apply to the subset of sources matched by a WQL expression:

• Query Type: Matching Host Tags
• Query: ~sample.cpu.*

List the metric (point) tag keys attached to Kubernetes pod CPU metrics:

• Query Type: Tag Names
• Query: kubernetes.pod_container.cpu.usage_rate

List the values of the env metric tag across all CPU metrics:

• Query Type: Tag Values
• Query: ~sample.cpu.*
• Tag: env

Scope tag values to a single environment by referencing another variable (dependent variable pattern):

• Query Type: Tag Values
• Query: ~sample.cpu.*, env="$environment"
• Tag: host

List the services reporting HTTP request metrics:

• Query Type: Tag Values
• Query: http.requests.total
• Tag: service

Use variables in queries

Reference variables in queries using $variable or ${variable} syntax. For details, refer to Variable syntax.

In Query Builder

Select a variable from the filter Value drop-down, or type $variable into a filter Value field. For example, setting Key to env and Value to $environment filters the query to the environment selected in the variable drop-down.

You can also reference a variable in the Metric or Aggregate fields by typing $variable as the value.

In Raw Query

Interpolate variables directly into WQL or PromQL expressions.

WQL:

SQL Copy

avg(ts("sample.cpu.loadavg.1m", env="$environment"))

SQL Copy

mavg(5m, sum(rate(ts("http.requests.total", service="$service"))))

PromQL:

SQL Copy

rate(http_requests_total{env="$environment"}[5m])

Multi-value and Include All behavior

The Wavefront data source handles multi-value and Include All variables automatically in both query modes.

• In Query Builder: When a filter value is $variable and the variable has multiple values selected, the data source expands it into (v1 or v2 or v3) and sends the resulting WQL to Wavefront. Use multi-value variables in filters without additional configuration.

• In Raw Query (WQL): When a query contains key=$variable and the variable has multiple values selected, the data source expands the variable value into (v1 or v2 or v3). For example, with a multi-value variable $namespace:

  SQL Copy

  avg(ts("kubernetes.pod.cpu.usage_rate", cluster="grafana" and namespace_name=$namespace))

  expands to:

  SQL Copy

  avg(ts("kubernetes.pod.cpu.usage_rate", cluster="grafana" and namespace_name=(prod or stage)))

• In Raw Query (PromQL): PromQL uses regular-expression matching. Use the regex format option to expand a multi-value variable into a regex:

  SQL Copy

  rate(http_requests_total{service=~"${service:regex}"}[5m])

To inspect the final expanded query, open the panel’s query inspector and review the Request tab.

Next steps

• Build queries with the Wavefront query editor.
• Create alert rules from Wavefront queries.
• Annotate panels with Wavefront events.