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.

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.

The Variable panel is displayed.
Define the variable.
- Name: the name of the variable.
  - Only alpha-numerical values are allowed
  - A variable name must not start with dt_
- Type: can be one of the following:
  - Query: the value is returned from a query you enter when you define the variable.
    Select Run query to test your query.
  - Code: the value is returned from code you enter when you define the variable.
  - CSV: a comma-separated values (CSV) list of values.
    To define possible values, enter them (separated by commas) in the box under Type.
    To define a default value, select one from the Default value list.
    To allow multiple values to be selected at the same time, turn on Multi-select.
  - Text: free text. You can enter a Default value. Your changes are saved automatically.
If you want to add another variable, select Variable.
When you're finished, select < Variable to go to the Variables panel or close the panel to display the dashboard.

How you edit a variable depends on the Type. For details and examples, see Query variable, CSV variable, Code variable, or Text variable below.

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: Host
- Type: Query
- Query:
```
fetch dt.entity.host
| fields entity.name
```
Turn on Multi-select so you can select more than one value at a time to show in your visualizations.

Your changes are saved automatically.
Close the Variable panel.

Use with a Query Grail tile

Open the and select Query Grail.
Copy and paste the following query into the Query box and select Run.

Notice that the query refers to our new variable as $Host, with the dollar sign indicating that it's a variable name.
```
fetch logs, scanLimitGBytes: 20
| filter in(host.name,array($Host))
| summarize count(), by:{bin(timestamp, 5h), host.name}
```
or when not using a multi-select variable you can reference it like
```
fetch logs, scanLimitGBytes: 20
| filter host.name=$Host
| summarize count(), by:{bin(timestamp, 5h), host.name}
```
Because you added a multi-select variable, you can use the value selector to determine which values are displayed in your visualizations.
You can of course use your variable in multiple queries.

Use with an Explore tile

Open the Add menu and select Explore > Logs.
Select and then select host.name from the Available filters.
In the added filter field, type $ to get suggestions for all available variables and then select $Host.

Note: Adding variables in Explore tiles only works for single-select variables in combination with the = operator.

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 Variables panel, 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 Variables panel.
In the Name column, select the name of the variable that you want to edit.
Edit and verify the variable.
Dismiss the Variables panel.

How you edit a variable depends on the Type. For details and examples, see Query variable, CSV variable, Code variable, or Text variable below.

Delete a variable

To delete a variable from a dashboard

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

The Variables panel lists all variables on your dashboard.
Find the variable you want to delete and select in the Actions 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, locate the variable name in the upper-left of the dashboards.
Use the menu or edit box under the variable name to change the value.
- 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 shows how many values are selected.
- For a text variable, you can edit the text in the box under the variable name.

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 Variables panel, and referred to in code.
- It can contain only letters (uppercase or lowercase) and numbers (for example, status, myHosts, or Variable01) and it can't start with dt_.
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.

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:
```
fetch dt.entity.host
  | 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:

fetch logs
  | fields loglevel
  | filterOut loglevel == "NONE"
  | sort loglevel asc
  | 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.
- It will be displayed at the top of the dashboard, listed on the Variables panel, and referred to in code.
- It can contain only letters (uppercase or lowercase) and numbers (for example, status, myHosts, or Variable01) and it can't start with dt_.
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.

Your changes are saved automatically.
Close the Variable panel.

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:
```
WARN, 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 Variables panel, and referred to in code.
- It can contain only letters (uppercase or lowercase) and numbers (for example, status, myHosts, or Variable01) and it can't start with dt_.
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.

Your changes are saved automatically.
Close the Variable panel.

Example code variable 1

Name: CodeVariable
Type: Code

Definition:

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

Text variable

To define a text variable

Set Name the name you want to give your variable.
- It will be displayed at the top of the dashboard, listed on the Variables panel, and referred to in code.
- It can contain only letters (uppercase or lowercase) and numbers (for example, status, myHosts, or Variable01) and it can't start with dt_.
Set Type to Text.
You can enter a Default value.

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.

fetch logs
    | ...
    | 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.

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

Convert your variable values to other data types

If you want to filter a numeric value but compare it with a string representation, you can use a native DQL conversion function such as toString.

fetch logs
    | filter amount = toString($amount)
    | ...

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.

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.