Documentation Grafana Cloud Observe and act Connect to data sources Data sources Graphite Template variables

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 drop-down selection 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.

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

Use query variables

Graphite populates Query variables. You can still use other variable types, such as Custom, Interval, and Text box, on a dashboard that queries Graphite. Those types don’t send a query to Graphite.

To create a Graphite query variable, choose the query type from the Select query type drop-down and enter your query in the Query field. Grafana supports three query types for Graphite variables:

Choose a variable syntax

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

Grafana allows two ways to reference variables in a query:

• Shorthand syntax ($varname) is convenient for standalone path segments but doesn’t work when the variable is adjacent to other characters (for example, cpu$coreLoad).
• Full syntax (${varname}) is more flexible and works in any part of the string, including embedded within words.

Choose the format that best fits the structure of your Graphite metric path.

Use tag variables

Grafana supports tag-based variables for Graphite, allowing you to dynamically populate drop-downs based on tag keys and values in your metric series. To do this, use the Graphite functions tags() and tag_values() in your variable queries.

You can use multiple filter expressions, and those expressions can include other Grafana variables. For example:

text Copy

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

This query returns all server tag values from series where the server tag matches backend* and the app tag matches the regular expression-filtered values from another variable, ${apps}.

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

Using regular expression formatting and the equal tilde operator =~:

text Copy

server=~${servers:regex}

This query tells Grafana to format the selected values in the servers variable as a regular expression (for example, (server1|server2) if two servers are selected).

For more information, refer to Advanced variable format options.

Filter with multiple expressions

When using multi-value variables in tag queries, append ${var:regex} to the variable name to apply regular expression formatting.

text Copy

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

This query returns only series where the app tag matches the selected values in ${apps}, formatted as a regular expression. =~ is the regular expression operator.

Non-tag queries use the default glob formatting for multi-value variables.

Use other query variables

When writing queries, use the Default Query type to retrieve dynamic metric values.

For example, the query prod.servers.* populates the variable with all values that exist at the wildcard position (*).

Note that the results include only the values found at the last level of the query path.

To return full metric paths that match your query, use the expand() function:

text Copy

expand(*.servers.*)

Compare expanded and non-expanded metric search results

When querying Graphite metrics in Grafana, you can choose between using an expanded or non-expanded query:

• Expanded queries (using the expand() function) return the full metric paths that match your query.
• Non-expanded queries return only the last segment of each matching metric path, which limits your ability to extract or filter based on deeper parts of the metric name.

Expanded queries are especially useful when working with regular expressions to match or extract specific parts of the metric path.

Suppose your Graphite database contains the following metrics:

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

The following table illustrates the difference between expanded and non-expanded queries:

Grafana also supports nested variables, which allow you to reference other variables in a query.

For example:

text Copy

apps.$app.servers.*

This query uses the selected value of the $app variable to dynamically filter the metric path. The variable $app contains one or more application names and servers.* matches all servers for the given application.

Filter query variable results with __searchFilter

Grafana provides the variable __searchFilter, which you can use to dynamically filter query results based on what the user types into the variable drop-down. When the drop-down is empty or blank, __searchFilter defaults to *, which means it returns all possible values. If you type a string, Grafana replaces __searchFilter with that input.

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

Query:

text Copy

apps.$app.servers.$__searchFilter

TagValues:

text Copy

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