OpenTSDB template variables

Instead of hard-coding server, application, and sensor names in your metric queries, you can use template variables. Variables appear as drop-down menus at the top of the dashboard, making it easy to change the data being displayed without editing queries.

For an introduction to template variables, refer to the Variables documentation.

Query variable

The OpenTSDB data source supports query-type template variables that fetch values directly from OpenTSDB. These variables dynamically populate based on data in your OpenTSDB database.

Supported query functions

{{< admonition type="note" >}} The tag_names and tag_values functions use the OpenTSDB lookup API, which requires metrics to exist in your database. The suggest_tagk and suggest_tagv functions use the suggest API, which searches across all metrics. {{< /admonition >}}

Create a query variable

To create a query variable:

1. Navigate to Dashboard settings > Variables.
2. Click Add variable.
3. Enter a Name for your variable (for example, host).
4. Select Query as the variable type.
5. Select the OpenTSDB data source.
6. Enter your query using one of the supported query functions.
7. Optionally configure Multi-value to allow selecting multiple values.
8. Optionally configure Include All option to add an "All" option.
9. Click Apply.

Query variable examples

List all metrics:

metrics()

Returns all metric names in your OpenTSDB database. Useful for creating a metric selector.

List metrics with a prefix:

metrics(sys.cpu)

Returns metrics starting with sys.cpu, such as sys.cpu.user, sys.cpu.system, sys.cpu.idle.

List tag keys for a metric:

tag_names(sys.cpu.user)

Returns tag keys like host, env, datacenter that exist on the sys.cpu.user metric.

List tag values for a metric and tag key:

tag_values(sys.cpu.user, host)

Returns all host values for the sys.cpu.user metric, such as webserver01, webserver02, dbserver01.

Search for tag keys by prefix:

suggest_tagk(host)

Returns tag keys matching host across all metrics, such as host, hostname, host_id.

Search for tag values by prefix:

suggest_tagv(web)

Returns tag values matching web across all metrics, such as webserver01, webserver02, web-prod-01.

If template variables aren't populating in the Preview of values section, refer to Troubleshooting.

Nested template variables

You can use one template variable to filter values for another. This creates cascading filters, such as selecting a data center first, then showing only hosts in that data center.

Filter syntax

The tag_values function accepts additional tag filters after the tag key:

tag_values(metric, tagkey, tag1=value1, tag2=value2, ...)

Use template variables as filter values to create dynamic dependencies:

tag_values(metric, tagkey, tag1=$variable1, tag2=$variable2)

Nested variable examples

Create cascading filters

To create a hierarchy of dependent variables:

1. Create the parent variable:

   • Name: datacenter
   • Query: tag_values(sys.cpu.user, datacenter)

2. Create the child variable:

   • Name: host
   • Query: tag_values(sys.cpu.user, host, datacenter=$datacenter)

3. Create additional levels as needed:

   • Name: cpu
   • Query: tag_values(sys.cpu.user, cpu, datacenter=$datacenter, host=$host)

When users change the data center selection, the host variable automatically refreshes to show only hosts in that data center.

Use variables in queries

Reference variables in your queries using the $variablename or ${variablename} syntax. Grafana replaces the variable with its current value when the query executes.

Where to use variables

Variables can be used in these query editor fields:

Variable syntax options

Multi-value variables

When you enable Multi-value for a variable, users can select multiple values simultaneously. The OpenTSDB data source handles multi-value variables using pipe (|) separation, which is compatible with OpenTSDB's literal_or filter type.

Configure multi-value variables

1. When creating the variable, enable Multi-value.
2. Optionally enable Include All option to add an "All" selection.
3. Use the variable in a filter with the literal_or filter type.

Multi-value example

With a host variable configured as multi-value:

If the user selects webserver01, webserver02, and webserver03, the filter value becomes webserver01|webserver02|webserver03.

All value behavior

When the user selects "All", Grafana sends all available values pipe-separated. For large value sets, consider using a wildcard filter instead:

Interval and auto-interval variables

Grafana provides built-in interval variables that are useful with OpenTSDB downsampling:

Use these in the downsample interval field for automatic interval adjustment:

Next steps

• Build queries using your template variables.
• Set up alerting with templated queries.
• Troubleshoot issues if variables aren't populating.