Add a variable to a dashboard

Latest Dynatrace

Use variables to filter your dashboards, to act as variable values in code tiles, and as placeholders in tile titles and Markdown tile text.

Breaking change

Dynatrace version 1.277+ Dashboards app version 1.10.0+

In Dynatrace version 1.276 and earlier, in the Dashboards app, values from query, code, and CSV variables were automatically converted to numbers where possible.
In Dynatrace version 1.277+ (Dashboards app version 1.10.0+), all such variable values are returned as strings.

Issue: Starting with Dynatrace version 1.277, errors might occur in some previously existing Dashboards app dashboards that depend on the previous conversion (for example, your query expects a number, but it now receives a string).

Solution: Use DQL conversion functions in your queries to convert values as needed.

Add a variable

To add a variable to a dashboard

In the upper-right of the dashboard, open the Add menu and select Add variable.
Define the variable.
Select Add variable to save your changes.

How you define a variable depends on the Type: Query, CSV, or Code.

Use a variable

After you create a variable, you're ready to use it in a query.

Always remember to prepend a variable name with $ in your queries.

For example, if you create a variable named MyTotal, you need to refer to it as $MyTotal in your query.

For example

Open the Add menu and select Add variable to add a variable to your dashboard.
Define the following variable:
- Name: Loglevel
- Type: Query
- Query: you can leave the default query.
Turn on Multi-select so you can select more than one value at a time to show in your visualizations.
Select Add variable to save your changes.

Now your dashboard has a multi-select variable called Loglevel.
Open the Add menu and select Query Grail.
Copy and paste the following query into the Query box and select Run query.

Notice that the query refers to our new variable as $Loglevel, with the dollar sign indicating that it's a variable name.
```
1fetch logs, scanLimitGBytes: 20
2| filter in(loglevel,array($Loglevel))
3| summarize count(), by:{bin(timestamp, 5h), loglevel}
```
Because you added a multi-select variable, you can use the value selector to determine with values are displayed in your visualizations.
You can of course use your variable in multiple queries. Here, we used the same query twice to display the results as a pie chart and table.

List variables

After you add at least one variable to a dashboard, a filter icon is displayed in the upper-left corner of the dashboard.

Select to open the Manage variables page, which lists all variables defined for the selected dashboard.
If there is no in the upper-left corner of the dashboard, there are no variables defined for the dashboard.

Edit a variable

In the upper-left corner of the dashboard, select to open the Manage variables page.
In the Name column, select the name of the variable that you want to edit.
Edit the variable.
Select Run query and inspect the results in the Preview section to make sure it works as expected.
Select Save. You can't select Save until you select Run query.
Dismiss the Manage variables page.

How you edit a variable depends on the Type: Query, CSV, or Code.

Delete a variable

To delete a variable from a dashboard

In the upper-left corner of the dashboard, select .

The Manage variables window lists all variables on your dashboard.
Find the filter you want to delete and select in the Delete column.

Change variable values

If a dashboard has one or more variables, they are listed by name along the upper-left of the dashboard, under the dashboard name. When you change variable values, the dashboard contents are recalculated and displayed according to the new values.

To change the value of a variable

In the upper-left of the dashboard, open a variable menu. In this example, a dashboard named My animal colors has two variables, Animal and Color, and we are going to open the Animal variable's menu.

Make your value selection (or selections) for the variable.

If the variable allows just one selection (value) at a time, select the value that you want to apply to the dashboard.

If the variable allows multiple selections (values) at a time, select the checkbox for each value you want to apply to the dashboard.
- The menu name for that variable will show the value of the variable if only one is selected, but it will instead show the number of values selected if you select more than one value.
- At least one value has to be selected. In the example below, you would not be able to clear green unless you first selected one or more other values available for that variable.
  - Before you select a second variable value:
  - After you select a second variable value:

Query variable

To define a query variable

Set Name the name you want to give your variable.
- It will be displayed at the top of the dashboard, listed on the Manage variables page, and referred to in code.
- It can contain only letters (uppercase or lowercase) and numbers, such as status, myHosts, or Variable01.
Set Type to Query.
In Definition, enter a query. Be sure to use summarize and collectDistinct to get distinct values from data sources such as logs.
Select Run query and inspect the results in the Preview section to make sure it works as expected.
If you want to be able to select more than one value at a time, turn on Multi-select.
Select Add variable to save your changes and return to the dashboard.

If you add both examples below to your dashboard, you can filter your dashboard by host and log severity level. Be sure to turn on Multi-select if you want to select more than one at a time.

Example query variable 1

Name: Hosts
Type: Query
Definition:
```
1fetch dt.entity.host
2  | fields id
```

If you want to use a human-readable name, use | fields entity.name instead of | fields id.

Example query variable 2

Name: Loglevel
Type: Query

Definition:

1fetch logs
2  | fields loglevel
3  | filterOut loglevel == "NONE"
4  | sort loglevel asc
5  | summarize distinctLoglevels = collectDistinct(loglevel)

CSV variable

To define a CSV (comma-separated values) variable

Set Name to the name you want to give your variable.
- Name is displayed at the top of the dashboard, listed on the Manage variables page, and referred to in code.
- Name can contain only letters (uppercase or lowercase) and numbers, such as status, myHosts, or Variable01.
Set Type to CSV.
In Definition, enter a comma-separated list of possible values for this variable, such as dog, cat, horse.

Be sure to use the correct value type. Dynatrace distinguishes values as numeric or string depending on how you specify them—with or without quotes. For example, 111 is a numeric value, while "111" is a string.
Inspect the results in the Preview section to make sure it works as expected.
If you want to be able to select more than one value at a time, turn on Multi-select.
Select Add variable to save your changes and return to the dashboard.

Example CSV variable 1

This example would add a $Status variable to your dashboard with the ability to select more than one status at a time, and with four possible values: WARN, ERROR, INFO, NONE.

Name: Status
Type: CSV
Definition:
```
1WARN, ERROR, INFO, NONE
```
Multi-select: on

Code variable

To define a code variable

Set Name the name you want to give your variable.
- It will be displayed at the top of the dashboard, listed on the Manage variables page, and referred to in code.
- It can contain only letters (uppercase or lowercase) and numbers, such as status, myHosts, or Variable01.
Set Type to Code.
In Definition, enter the JavaScript code.
Select Run query and inspect the results in the Preview section to make sure it works as expected.
If you want to be able to select more than one value at a time, turn on Multi-select.
Select Add variable to save your changes and return to the dashboard.

Example code variable 1

Name: CodeVariable
Type: Code

Definition:

1/*
2* This will run JavaScript in the DYNATRACE
3* serverless environment.
4* To generate variable options return string array.
5*/
6export default async function () {
7return ["val1", "val2", "val3"]
8}

Limitations when using variables in tiles

Variables in your tiles can be of string or numeric type. Cases requiring a different data type (for example, duration) lead to failed queries. Below are some examples of how to work around such situations.

Resolution in DQL command

Straightforward usage of a $resolution variable (as in the following query) doesn't work because resolution requires a predefined data format, while a variable returns a string value.

1fetch logs
2    | ...
3    | summarize count(), by: {loglevel, bin(timestamp, $resolution)}

As a workaround, you can use the duration function together with a DQL conversion function. This provides the required output based on your $resolution value.

1fetch logs
2    | ...
3    | summarize count(), by: {loglevel, bin(timestamp, duration(toLong($resolution), unit:"m"))}

Troubleshooting

Dynatrace version 1.277+ Dashboards app version 1.10.0+

In Dynatrace version 1.276 and earlier, in the Dashboards app, values from query, code, and CSV variables were automatically converted to numbers where possible.
In Dynatrace version 1.277+ (Dashboards app version 1.10.0+), all such variable values are returned as strings.

Solution: Use DQL conversion functions in your queries to convert values as needed.

Add a variable to a dashboard

Add a variable

Use a variable

List variables

Edit a variable

Delete a variable

Change variable values

Query variable

Example query variable 1

Example query variable 2

CSV variable

Example CSV variable 1

Code variable

Example code variable 1

Limitations when using variables in tiles

Resolution in DQL command

Troubleshooting

Related topics