Customize panel queries with dashboard variables

Dashboard variables are uniquely named placeholders that you can use in dashboards to dynamically replace their values with user-defined values. For instance, you can add variables to panels to let users customize them across all panels on a dashboard without editing each individually.

After you create a dashboard variable, you can add it to a panel using the syntax $<NAME>, where <NAME> is the variable's name. Variables are most often used in queries but also work in panel names and descriptions, and also in the content of Markdown panels. Expressions also support variables.

For example, part of a panel's query might match a service named production:

service=~"production"

You can create a dashboard variable named service and replace the string value with $service:

service=~"$service"

Dashboard viewers can then change all uses of $service in each panel by changing that dashboard variable in one place, instead of editing each panel manually.

Dashboard variables can accept either user-defined text values or offer a list of values, whether manually defined or or dynamically generated from labels or a query, for the user to select.

View dashboard variables

Dashboard variables add a dropdown selector to the dashboard's header for each variable.

To view a list of all of a dashboard's variables:

1. Open the dashboard. You can view a list of all dashboards or select from a list of dashboards in a collection.
2. Click Edit on the dashboard.
3. Click Variables.

The Dashboard variables panel lists all dashboard variables defined for this dashboard in a table. Columns indicate each variable's visibility, name, and type. Each variable includes controls to reorder, edit, and delete variables.

Create a dashboard variable

To add a dashboard variable to a dashboard:

1. View the list of dashboard variables.
2. In the Dashboard variables panel, click Add variable. By default, this creates a new text variable.
3. Enter the variable's Name, which defines the name used to address the variable in a query or text.
4. Click Apply.

Configure a dashboard variable

To configure a dashboard variable:

1. View the list of dashboard variables.
2. In the Dashboard variables panel, click Add variable. By default, this creates a new text variable.
3. On the row of the variable you want to edit, click Edit variable.
4. After configuring the variable, click Apply to confirm the changes.

Configure a text variable

In a text variable, the dashboard user can define the variable's value by entering it into a text field.

To configure a text variable:

1. Configure or create a dashboard variable.
2. If the variable Type isn't Text, click Type, then click Text.
3. Optional: Set a Display label, which appears in the variable's field instead of its name.
4. Optional: Set a Description.
5. Optional: Enter a Value for the template variable.
6. After configuring the variable, click Apply to confirm the changes.

Configure a list variable

In a list variable, the dashboard user can define the variable's value by selecting it from a list.

To configure a list variable:

1. Configure or create a dashboard variable.
2. If the variable Type isn't List, click Type, then click List.
3. Select a Source.
   • In a [Static] Custom list source, define the available options by entering them into the Values field.
   • In a [Prometheus] Label values source, select a label name and Chronosphere adds the values of labels of the matching series to the list. You can filter the values by series by using PromQL time series selectors (opens in a new tab). If you don't define any series selectors, Chronosphere defaults to using all series. To select from multiple series, click Add series selector.
   • In a [Prometheus] Label names source, Chronosphere adds all label names to the list. You can also filter these names by series using PromQL time series selectors.
   • In a [Prometheus] PromQL result values source, enter a PromQL query and Chronosphere adds values from the result to the list. You can also filter the results by label name.
4. Optional: Filter the results further by entering a Capturing regex filter, which includes only the results that match the expression.
5. Optional: Set the variable's Refresh toggle to define whether Chronosphere updates its list values On dashboard load or On time range change.
6. Optional: To allow the user to select multiple values from the list, enable Select multiple values.
7. Optional: To add an option to select all values from the list, enable Include "All" option. You can also define the regular expression representing all values by setting the Custom "All" value.
8. To confirm and apply the new variable configuration, click Apply.
9. Optional: To cancel any changes to the variable, click Cancel.

As you configure the variable, Chronosphere reflects any changes you make to the list variable and reports any errors in the Preview values list. You can also Refresh the preview to update its values and Copy the list of previewed values as a comma-separated list.

Define the order of dashboard variables

Dashboards present dashboard variables from left to right in the same order as they appear in the Dashboard Variables list.

To reorder dashboard variables:

1. View the list of dashboard variables.
2. On the row of the variable you want to reorder, click Reorder variable up or Reorder variable down to move the variable within the list to the desired position.
3. To confirm and apply the new variable order and other changes to dashboard variables, click Apply.
4. Optional: To cancel any changes to dashboard variables, click Cancel.

Toggle dashboard variable visibility

You can define whether a dashboard variable appears on its dashboard. This helps you create and test dashboard variables without disrupting other users, and helps users curate large lists of dashboard variables to focus on what they want to analyze.

Delete a dashboard variable

To delete a dashboard variable:

1. View the list of dashboard variables.

2. On the row of the variable you want to edit, click the Delete variable.

   This immediately deletes the variable without confirmation. Ensure that you want to delete the variable before clicking the icon.

3. To confirm and apply the variable deletion and other changes to dashboard variables, click Apply.

4. Optional: To cancel any deletions and other changes to dashboard variables, click Cancel.