Menu

This is documentation for the next version of Grafana. For the latest stable release, go to the latest version.

Grafana Cloud Enterprise Open source

Graphite template variables

Instead of hard-coding details such as server, application, and sensor names in metric queries, you can use variables. Grafana lists these variables in dropdown select boxes at the top of the dashboard to help you change the data displayed in your dashboard. Grafana refers to such variables as template variables.

For an introduction to templating and template variables, refer to the Templating and Add and manage variables documentation.

Select a query type

There are three query types for Graphite template variables

Query TypeDescription
Default QueryUse functions such as tags(), tag_values(), expand(<metric>) and metrics.
Value QueryReturns all the values for a query that includes a metric and function.
Metric Name QueryReturns all the names for a query that includes a metric and function.

Use tag variables

To create a variable using tag values, use the Grafana functions tags and tag_values.

QueryDescription
tags()Returns all tags.
tags(server=~backend\*)Returns only tags that occur in series matching the filter expression.
tag_values(server)Returns tag values for the specified tag.
tag_values(server, server=~backend\*)Returns filtered tag values that occur for the specified tag in series matching those expressions.

Multiple filter expressions and expressions can contain other variables. For example:

tag_values(server, server=~backend\*, app=~${apps:regex})

For details, refer to the Graphite docs on the autocomplete API for tags.

Use multi-value variables in tag queries

Multi-value variables in tag queries use the advanced formatting syntax for variables: {var:regex}. Non-tag queries use the default glob formatting for multi-value variables.

Tag expression example

Using regex formatting and the Equal Tilde operator, =~:

text
server=~${servers:regex}

For more information, refer to Advanced variable format options.

Use other query variables

When writing queries, use the metric find type of query.

For example, a query like prod.servers.* fills the variable with all possible values that exist in the wildcard position.

The results contain all possible values occurring only at the last level of the query. To get full metric names matching the query, use the expand function: expand(*.servers.*).

Compare expanded and non-expanded metric search results

The expanded query returns the full names of matching metrics. In combination with regular expressions, you can use it to extract any part of the metric name. By contrast, a non-expanded query returns only the last part of the metric name, and doesn’t let you extract other parts of metric names.

Given these example metrics:

  • prod.servers.001.cpu
  • prod.servers.002.cpu
  • test.servers.001.cpu

These examples demonstrate how expanded and non-expanded queries can fetch specific parts of the metrics name:

Non-expanded queryResultsExpanded queryExpanded results
*prod, testexpand(*)prod, test
*.serversserversexpand(*.servers)prod.servers, test.servers
test.serversserversexpand(test.servers)test.servers
*.servers.*001,002expand(*.servers.*)prod.servers.001, prod.servers.002, test.servers.001
test.servers.*001expand(test.servers.*)test.servers.001
*.servers.*.cpucpuexpand(*.servers.*.cpu)prod.servers.001.cpu, prod.servers.002.cpu, test.servers.001.cpu

The non-expanded query is the same as an expanded query, with a regex matching the last part of the name.

You can also create nested variables that use other variables in their definition. For example, apps.$app.servers.* uses the variable $app in its query definition.

Use __searchFilter to filter query variable results

You can use __searchFilter in the query field to filter the query result based on what the user types in the dropdown select box. The default value for __searchFilter is * if you’ve not entered anything, and `` when used as part of a regular expression.

Search filter example

To use __searchFilter as part of the query field to enable searching for server while the user types in the dropdown select box:

Query

bash
apps.$app.servers.$__searchFilter

TagValues

bash
tag_values(server, server=~${__searchFilter:regex})

Choose a variable syntax

variable

The Graphite data source supports two variable syntaxes for use in the Query field:

  • $<varname>, for example apps.frontend.$server.requests.count, which is easier to read and write but does not allow you to use a variable in the middle of a word.
  • ${varname}, for example apps.frontend.${server}.requests.count, to use in expressions like my.server${serverNumber}.count.

Templated dashboard example

To view an example templated dashboard, refer to Graphite Templated Nested dashboard.