Datadog Synthetics is now available!

Template Variables


Dashboard template variables apply a new scope to one or more graphs on your dashboard, allowing you to dynamically explore metrics across different sets of tags by using variables instead of specific tags.

Define a Template Variable

New dashboards start with a keyless template variable applied. Click on the pencil icon to open the template variable edit mode:

Edit template variable

Once in the edit mode click on Add Variable + to create your first Template Variable, it is defined by:

  • A Name -Mandatory-: Value of your Template Variable displayed in your graphs query.
  • A Tag Group -Mandatory-: If your tags follow the tags best practice with a key:value format, the Tag Group is the key of your tags.
  • A Default Tag -Optional-: Default value for your Template Variable Tag Group.

Once created, notice that you have statistics upon your template variables usage in your graphs. In the picture below, the template variable is not used in both graph of the dashboard:

statistic TV

Decide if you want to remove/add this Template Variable to all of your graphs with the respective Remove From All and Add to All buttons.

Template Variable in Graphs

Once you have defined a template variable, it appears in the options displayed in the from field:

Template variable in graphs

After the graph is saved, the value of this template variable is the one selected on top of your dashboard:

Selecting template variables

Template variables and events

The event overlay search is helpful to correlate metrics to events, and you can use template variables to find events that share certain tags with the metrics on your dashboard. The event overlay search is applied through an individual graph.

Values from dashboard template variables can be directly captured by using the $variable.value syntax in the event search field.

Note: Dashboard template variables must be metric tags; event-supplied tags cannot be used as dashboard template variables)

For example, to search for events in the event stream with the same region tag, use: tags:region:$region.value.


In the following example, the template variable resolves to tags:region:ap-south-1. After those events are brought up in the event search overlay, the timing of the events are marked by pink bars in the graphs to show the timing of events:


Use multiple template variables in the search field and the event overlay search displays all events tagged with the same values from the template variables. The following example uses the query tags:role:$role.value,env:$env.value


Since the $variable.value syntax captures the resolved key value from the template variable, it can be used with other filters, such as hosts:. Here is an example that uses the tags field together with the hosts: field in the search term tags:env:$env.value hosts:$host.value


Template variables and Logs

Template variables work by default on Log widgets, as Metrics and Logs share the same tags. Additionally, it is possible to define specific Log Template variables based on your Log Facets. Those template variables start with @.

log template variables

Using the Add to all button adds this template variable to all log widgets. Wildcards can be used in the template variable value.

Further Reading