Skip to main content
Sumo Logic

Filter with template variables

Template variables are a feature of Dashboard (New) that allow you to analyze specific data on demand. They give you the ability to filter the data displayed on your dashboard so you can quickly troubleshoot a problem. Queries can be changed on the fly by choosing values for variables from drop-down lists without having to manually edit queries.

This feature requires two parts to work:

  1. You have created a template variable.
  2. You add the template variable to your query.

Once the variable is created you can edit queries to use it and apply them to Dashboards (New).

Create a template variable

There are three types of template variables you can use as a dashboard filter:

Add a Custom List variable

A custom list variable allows you to specify random string values for a variable. These are helpful when you know the values of fields you want to reference on-the-fly. For example, if your data had a field named color and you knew the potential values you wanted to reference were redgreen, and purple. A custom list variable would be assigned the Variable Name color and the Custom List would be given the value red, green, purple. Then in your panel query you would provide the variable as {{color}}. With these set up you can use the variable to filter your data by color.

To add a Custom List variable to a dashboard, do the following:

  1. In the Dashboard (New) top menu bar, click the plus (+) icon. The Create Template Variable panel appears.

create dashboard filter.png

  1. In the Create Template Variable panel, enter a unique Variable Name. Spaces and special characters, with the exception of an underscore (_), are not allowed in value names.

Create Template Variable dialog.png

  1. Select Custom List as the Variable Type.
  2. List Items are your variable values. Use a comma separated list for variable options, separating individual options with a comma. For example, small, medium, large.
  3. Optional: Provide a Default Value for the variable.
  4. Optional: Toggle ON Include the option to select all values (*) to include a wildcard asterisk (*) in the available options.
  5. Click Create Template Variable to apply the variable to the dashboard. 

Add a metric Metadata Search variable

A Metadata Search variable allows you to specify metric metadata to act as a variable. You'll be able to select from previously collected metrics as your filter.

To add a Metadata Search variable to a dashboard, do the following:

  1. In the Dashboard (New) top menu bar, click the plus (+) icon. The Create Template Variable panel appears.

create dashboard filter.png

  1. In the Create Template Variable panel, enter a unique Variable Name. Spaces and special characters, with the exception of an underscore (_), are not allowed in value names.

create variable with metadata.png

  1. Select Metadata Search as the Variable Type.
  2. The Fields (key) is the metadata field you want to use as the filter.
  3. Optional: Filters allow you to filter the scope of your data before choosing the field you want to use. Click in the Filter input, begin typing, and choose a filter from the pop-up list. A list of valid values appears. Select a value for the filter, and add other filters as needed.
  4. Optional: Toggle ON Include the option to select all values (*) to include a wildcard asterisk (*) in the available options.
  5. Optional: Provide a Default Value for the variable.
  6. Click Create Template Variable to apply the variable to the dashboard.

Add a Logs Search variable

A Logs Search variable allows you to specify log metadata fields to act as a variable. You'll be able to select from previously parsed fields to build your filter.

To add a Logs Search variable to a dashboard, do the following:

  1. In the Dashboard (New) top menu bar, click the plus (+) icon. The Create Template Variable panel appears.

create dashboard filter.png

  1. In the Create Template Variable panel, enter a unique Variable Name. Spaces and special characters, with the exception of an underscore (_), are not allowed in value names.

Variable for logs search.png

  1. Select Logs Search as the Variable Type.
  2. Click in the Query field and begin typing your query. Select valid options from the pop-up list as they appear until your query is complete.
  3. The Key is the metadata field you want to use as the filter.
  4. Optional: Toggle ON Include the option to select all values (*) to include a wildcard asterisk (*) in the available options.
  5. Optional: Enter a Default Value for the variable.
  6. Click Create Template Variable to apply the variable to the dashboard.

Edit a template variable

This task shows you how to modify an existing template variable in a Dashboard (New) so you can rescope your data on the fly. This is helpful for troubleshooting a problem to a fast resolution to the root cause.

To edit a template variable, do the following:

  1. Hover the cursor over the end of the template variable field to display the options icon.options menu for variable.png
  2. Click the Details icon and select Edit from the drop-down menu. The Edit Variable dialog appears.
    edit variable.png
  3. Edit the variable as needed.
    edit variable dialog.png
  4. Click Save Template Variable to apply your changes.

Delete a template variable

This task shows you how you can easily delete a template variable from Dashboard (New).

To delete a template variable, do the following:

  1. Hover the cursor over the end of the template variable field to display the options icon.options menu for variable.png
  2. Click the options icon and select Delete from the drop-down menu. The variable along with the resulting data transformations are automatically removed from the dashboard.
    delete variable.png

Example: Using variables in queries

Logs and metrics variables allow you to interject metadata into your queries. This section shows you how to use a variable you created in a query.

How to use a logs variable in a query

To use a variable in a logs query, do the following:

  1. Go to your logs query and add the variable name wrapped in double brackets {{<variable_name>}} to your query. In the following example cluster is the name of the variable.

Logs_variable_query_example.png

At run time, the value inside the curly braces is replaced with the value of the variable you specified from the variable drop-down list.

How to use a metrics variable in a query

To use a metrics variable in a query working with the structured query builder, do the following:

  1. In the structured query builder, enter the Key for the variable followed by an equals sign.
  2. Select the desired variable from the drop-down list. It appears in curly braces to indicate it is a variable.

Metrics_variable_query_example1.png

The variable is inserted into the query and will convert the variable into the appropriate value, as shown in the following example.

Metrics_variable_query_example2.png

To use a metrics variable in a query working in advanced query mode, do the following:

  1. Locate the name of the variable you'd like to use in the drop-down list and copy it.
  2. Go to your metrics query and insert {{ var_name }} in the query, substituting var_name with the actual name of the variable.