Create and Manage Variables

Overview

A variable is like a placeholder for a value used in queries. Once set up in Custom Dashboards, your dashboard panel's queries will update to show data for that value.

Variables make dashboards more interactive and dynamic. Instead of putting specific names for servers, applications, or sensors in your queries, you can use variables instead. Once set up, you can easily switch between different data views. This means that if you have very complex, high-cardinality metrics, you can add variables to zoom in on specific values you care about, across widgets for all data types and regardless of the variable source type.

Variable types

Choose from any of the following variable types:

Variable type	Description
Static-value variable	Manually define a fixed list of variable values, such as a number or a string of numbers separated by a comma. For example, if you have country names that never change, you might want to create them as a static-value variable rather than a data source variable.
Query variable	Variable values are retrieved from a data source query using logs, metrics, or spans. For example, a query variable can generate a list of server names, sensor IDs, or data centers, dynamically updating the values by fetching options via a data source query. Query variables prove beneficial when managing multiple data source instances, especially across diverse environments.

Getting started

Navigate to Dashboards > Custom Dashboards.

In a new or existing dashboard, click the Manage Variable icon { } in the upper left-hand corner of your dashboard. Then click + Variable.

General options

Define the following fields for all variable types:

Variable type

Select a variable type.

Variable name

Text entered in this field determines how the variable name will appear in your query, e.g, {{ podvalues }}. No capitals or spaces are allowed.

Display name

[Optional] Text entered in this field will appear in the top bar selection as part of the drop-down, e.g., "My Pods".

Selection options

Once you have defined your variable, you may choose from these selection options:

• Multi-value: Allows multiple selection of values within a specific variable. Note that some queries do not support multiple values, such as {{ variablename }}. Choose this option only if your query supports multiple values.

• Include all: You may enable this option when the multi-value option is enabled. The query will select all available and future values for a specific timeframe, regardless of your specific selection.

When both options are selected, all variable options are selected by default, and one or more may be deselected. Opting out of both options will allow you to select one variable value at a time.

Create a static-value variable

Create a logs-based query variable

Create a spans-based query variable

Create a metrics-based query variable

Metric names

Metric labels

Metric label values

Manage variables

Easily view and manage the variables from the Custom Dashboards upper toolbar.

Edit or delete

To edit or delete a variable, hover over the variable at the top of your dashboard and click the more actions menu , then select Edit or Delete from the dropdown.

Query with template variables

You can use template variables in Lucene, PromQL, or DataPrime queries to build reusable dashboards. This eliminates the need to input the same data points into each widget, and instead allows you to filter all the widgets on your dashboard simultaneously with one variable.

To edit the query, select the widget and navigate to the query builder at the bottom of the screen.

Lucene

In a Lucene query, a template variable is referenced with {{ variable_name }} syntax.

Example:

 product_id:{{ pid }} 

In this example, the pid is the variable name, which must match the name you defined in the dashboard.

PromQL

In a PromQL query, a template variable is referenced with ${variable_name} syntax.

Example:

sum(kube_pod_owner{pod=~${pod}})

In this example, {pod=~${pod}} is a label selector that filters the kube_pod_owner metric for the specific pod whose name matches the name selected in the ${pod} template variable. The ${pod} is dynamically replaced with the selected pod when the query runs.

Predefined variables

You may use predefined variables in your PromQL query.

Variable	Description	Example
${__range}	This variable represents the duration of the dashboard time range. It is rendered as an interval string supported by PromQL. e.g., If one selects a time range from 13.00 to 14.30, then ${__range} variable will be rendered as 90m.	1d, 5m
${__range_s}	Rendered as the number of seconds in the selected time frame	60s, 180s
${__range_ms}	Rendered as the number of milliseconds in the selected time frame	60ms, 180ms

Example:

sum_over_time(kube_pod_owner[${__range}])

In this example, the ${__range_s} returns the time range in seconds as a number (e.g., 60, 1800). This is useful when using PromQL function to calculate a numeric value over time.

DataPrime

In a DataPrime query, a template variable is accessed with $p.<variable_name> syntax.

Example:

source logs 
| filter $l.applicationname.inArray($p.application) 
| groupby $l.applicationname as Application
, $m.timestamp / 10m as timestamp agg count() as count

In this example, the DataPrime query groups log activity into 10 minute intervals and filters them by the selected application dashboard variable, using a parameter that dynamically updates based on the variable you select. This allows you to compare log volume across one or more applications.

Learn more about query parameters.

Additional resources

Previous Query Builder

Next Create Annotations

Theme

Light

light

dark