Template Variables
Datadog's Research Report: The State of Serverless Report: The State of Serverless

Template Variables

Template variables allow you to dynamically filter one or more widgets in a dashboard.

Create

To create your first template variable in the dashboard, click Add Template Variables. If template variables are already defined, click on the pencil icon to open the template variable editor. Once in edit mode, click on Add Variable + to add a template variable.

A template variable is defined by:

  • Name: A unique name for the template variable. This name is used to filter content on your dashboard.
  • Tag or Attribute:
  • Default Value: The default value for your template variable tag or attribute.

After creating a template variable, Datadog displays the number of sources using the variable. In the example below, the template variable is used in one out of two graphs:

Use the template variables in individual widgets or click the Add to All option. To remove a template variable from all widgets, click the Remove From All option.

Logs, APM, and RUM queries

Template variables work with log, APM, and RUM widgets because metrics, logs, APM, and RUM share the same tags. Additionally, you can define log, APM, and RUM template variables based on log, APM, or RUM facets. These variables start with @, for example: @http.status_code.

Note: Using Add to all for this type of template variable adds the variable to all log, APM, and RUM widgets.

Saved views

Create

To the left of the template variables on a dashboard, there is a dropdown listed as (Default Value). When you make a change to a template variable value, the value is not automatically saved to a view. To save the current values of the template variables in a view, click on the dropdown menu and click Save selections as view. From there, you are prompted to enter a unique name for the view. After saving, this view is listed in the dropdown menu. Click on this view to retrieve the previously saved values for the template variables.

Delete

To delete a view, click on the saved views dropdown 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.

Modify

To modify the (Default Value) 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.

Use

Template variables are used in widgets and event overlays.

Widgets

When creating or editing a widget, existing template variables display as options in the from field. For example, if you create the template variable env, the option $env is available.

After the widget is saved, the value of the template variable is the one selected from the top of your dashboard:

Text

For text based widgets, you can display a template variable name and value with $<TEMPLATE_VARIABLE_NAME> or display just the value with $<TEMPLATE_VARIABLE_NAME>.value. For example, with a template variable named env and a selected value of dev:

  • $env displays env:dev
  • $env.value displays dev

Events overlay

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.

Dashboard

From your dashboard, search the event stream with template variables using the format:

tags:<TAG_KEY>:$<TEMPLATE_VARIABLE_NAME>.value

For example, searching for tags: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: tags:role:$role.value,env:$env.value

Note: Once you hit enter to search, $region.value updates to the value in the template variable drop-down.

Widgets

From your widgets, overlay the timing of the events using template variables with the format:

tags:$<TEMPLATE_VARIABLE_NAME>

For example, enter tags:$region in the event overlays search box. This searches for events with the value in the region template variable drop-down:

Further Reading