Template variables allow you to dynamically filter one or more widgets in a dashboard. You can build saved views from your template variable selections which allows your to organize and navigate your visualizations through the dropdown selections.
A template variable is defined by:
- Tag or Attribute:
- Name: A unique name for the template variable that appears in queries on the dashboard. Template variables are automatically named after the selected tag or attribute.
- Default Value: The tag or attribute value that appears automatically when the dashboard is loaded. Defaults to
- Available Values: The tag or attribute values available for selection in the dropdown menu. Defaults to
(all). The list of available values always includes
*, which queries all values of the tag or attribute.
Add a template variable
To add a template variable in a dashboard:
- Click Add Template Variables.
- If template variables are already defined, click the pencil icon to open the template variable editor.
- In edit mode, click + Add Template Variable to create a new template variable.
- (Optional) After creating a template variable, Datadog displays the number of sources using the variable. In the example below, the template variable
team is used in two graphs on the dashboard:
- (Optional) To add this template variable for all widget filters, click the Add to All option. You can also customize the template variables in individual widgets.
- (Optional) To remove a template variable from all widgets, click the Remove From All option.
Click on the Saved Views dropdown menu to the left of the template variables in your dashboard. When you update a template variable value, the value does not automatically save to a view.
To save your current template variables’ values in a view, select Save selections as view from the Saved Views dropdown menu. Enter a unique name for the view and click Save.
Your saved view appears in the dropdown menu. Click on the view to retrieve your previously saved template variable values.
To delete a view, click on the saved views dropdown menu and choose Manage views…. From there, a popup with your saved views is displayed with a trash bin icon next to each view. Click the appropriate trash bin icon to delete a view.
To modify the Default view, click on the pencil icon and update the template variable values. Then click Done to save. If any values in the other views are changed, save the values as a new view, and then delete the original view.
Template variables are used in widgets and event overlays.
Logs, APM, and RUM queries
Template variables work with log, APM, and RUM widgets because they share the same tags. You can define log, APM, and RUM template variables based on facets. These variables start with
@, for example:
On log, APM, and RUM widgets, you can use wildcards in the middle of a value (for example,
email@example.com) or use multiple wildcards in a value (for example,
Note: Using Add to all for this type of template variable adds the variable to all log, APM, and RUM widgets.
When creating or editing a widget, existing template variables display as options in the
from field. For example, if you configure the
environment template variable, the
$environment option is available as a dynamic variable in the widget.
Selecting production for the
environment value dynamically scopes widgets with the
$environment variable to the production environment.
When you change the value of a template variable, the dashboard URL updates to reflect the template variable value with the format
&tpl_var_<TEMPLATE_VARIABLE_NAME>=<TEMPLATE_VARIABLE_VALUE>. For example, a dashboard with the template variable
$env changed to
prod would have the URL parameter
To include the value in the query, append it with the syntax
$<TEMPLATE_VARIABLE_NAME>.value. For example, with a template variable named
Hover over the template variable fields to see at a quick glance, the widgets that use that variable highlighted on the dashboard.
Associated template variables
When selecting a template variable value, associated values are displayed at the top of the selector. Associated values are calculated from other template variable values selected on the page, and seamlessly identify the related values without any configuration.
For text-based widgets, you can display a template variable’s tag/attribute and value with
$<TEMPLATE_VARIABLE_NAME>, its key with
$<TEMPLATE_VARIABLE_NAME>.key, or its value with
$<TEMPLATE_VARIABLE_NAME>.value. This can come after any non-alphanumeric character, and can be followed by whitespace or any of the following characters:
Note: The wildcard syntax is not supported following a template variable.
For example, with a template variable named
env, with tag/attribute
environment, and with a selected value of
$env* looks for the exact value
Use the events overlay search with template variables to find events that share certain tags with the metrics in your dashboard. The event overlay search is applied through an individual graph.
Values from dashboard template variables can be directly captured by using the
$<TEMPLATE_VARIABLE_KEY>.value syntax in the event search field.
Note: Dashboard template variables must be metric tags, not event tags.
From your dashboard, search events with template variables using the format:
For example, searching for
region:$region.value with a value of
us-east1 for the
region template variable displays events tagged with
region:us-east1. Additionally, the timing of the events are marked by pink bars in the graphs.
Use commas to search using multiple template variables, for example:
Note: Once you press enter to search,
$region.value updates to the value in the template variable dropdown menu.
From your widgets, overlay the timing of the events using template variables with the format:
For example, enter
$region in the event overlays search box. This searches for events with the value in the
region template variable dropdown menu.
Additional helpful documentation, links, and articles: