public/grafana
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Docs: Updated the Graphite data source docs (#105426)

Browse Source 
* initial edits

* edits to config doc

* query editor updates

* ran prettier

* updates

* made more updates

* final edits

* ran prettier, updated some descriptions

* a few more quick edits

* one more definition
This commit is contained in:
Larissa Wandzura
2025-06-30 21:37:49 +00:00
committed by GitHub
parent d28594d2f9
commit dec2df8379
4 changed files with 372 additions and 189 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/sources/datasources/graphite/template-variables/index.md
+99 -68
View File
@@ -1,7 +1,7 @@
---
aliases:
- ../../data-sources/graphite/template-variables/
description: Guide for using template variables when querying the Graphite data source
description: Guide for using template variables when querying the Graphite data source.
keywords:
- grafana
- graphite
@@ -37,122 +37,153 @@ refs:
# 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 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](ref:variables) and [Add and manage variables](ref:add-template-variables) documentation.
## Select a query type
To view an example templated dashboard, refer to [Graphite Templated Nested dashboard](https://play.grafana.org/d/cvDFGseGz/graphite-templated-nested).
There are three query types for Graphite template variables
## Use query variables
| Query Type | Description |
| ----------------- | ------------------------------------------------------------------------------- |
| Default Query | Use functions such as `tags()`, `tag_values()`, `expand(<metric>)` and metrics. |
| Value Query | Returns all the values for a query that includes a metric and function. |
| Metric Name Query | Returns all the names for a query that includes a metric and function. |
With Graphite data sources, you can only create query variables. Grafana supports three specific query types for Graphite-based variables:
| Query type | Description | Example usage |
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- |
| **Default query** | Allows you to dynamically list metrics, nodes, or tag values using Graphite functions. | `tag_values(apps.*.requests.count, app)` |
| **Value query** | Returns all the values for a query that includes a metric and function. | `tag_values(apps.*.status.*, status)` |
| **Metric name query** | Returns all the names for a query that includes a metric and function. | `apps.*.requests.count` |
### Choose a variable syntax
The Graphite data source supports two variable syntaxes for use in the **Query** field.
![Variable syntax example](/static/img/docs/v2/templated_variable_parameter.png)
Grafana allows two ways to reference variables in a query:
| **Syntax** | **Example** |
| ------------ | ---------------------------------------- |
| `$varname` | `apps.frontend.$server.requests.count` |
| `${varname}` | `apps.frontend.${server}.requests.count` |
- **Shorthand syntax (`$varname`)** is convenient for simple paths but doesn't work when the variable is adjacent to characters (e.g., `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
To create a variable using tag values, use the Grafana functions `tags` and `tag_values`.
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.
| Query | Description |
| --------------------------------------- | -------------------------------------------------------------------------------------------------- |
| `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. |
| Query | Description |
| --------------------------------------- | ------------------------------------------------------------------------------------------ |
| `tags()` | Returns a list of all tag keys in the Graphite database. |
| `tags(server=~backend\*)` | Returns tag keys only from series that match the provided filter expression. |
| `tag_values(server)` | Returns all values for the specified tag key. |
| `tag_values(server, server=~backend\*)` | Returns tag values for a given key, filtered to only those that appear in matching series. |
Multiple filter expressions and expressions can contain other variables. For example:
You can use multiple filter expressions, and those expressions can include other Grafana variables. For example:
```
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 regex-filtered values from another variable ${apps}.
For details, refer to the [Graphite docs on the autocomplete API for tags](http://graphite.readthedocs.io/en/latest/tags.html#auto-complete-support).
### Use multi-value variables in tag queries
**Using regular expression formatting and the equal tilde operator `=~`:**
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}
```
This query tells Grafana to format the selected values in the `servers` variable as a regular expression (e.g., (`server1`|`server2`) if two servers are selected).
For more information, refer to [Advanced variable format options](ref:variable-syntax-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 regex formatting.
```
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 metric find type of query.
When writing queries, use the **metric find** query type to retrieve dynamic values.
For example, a query like `prod.servers.*` fills the variable with all possible values that exist in the wildcard position.
For example, the query `prod.servers.*` populates the variable with all values that exist at 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.*)`.
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:
```
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.
When querying Graphite metrics in Grafana, you can choose between using an **expanded** or **non-expanded** query:
Given these example metrics:
- **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`
These examples demonstrate how expanded and non-expanded queries can fetch specific parts of the metrics name:
The following table illustrates the difference between expanded and non-expanded queries:
| Non-expanded query | Results | Expanded query | Expanded results |
| ------------------ | ---------- | ------------------------- | ---------------------------------------------------------------- |
| `*` | prod, test | `expand(*)` | prod, test |
| `*.servers` | servers | `expand(*.servers)` | prod.servers, test.servers |
| `test.servers` | servers | `expand(test.servers)` | test.servers |
| `*.servers.*` | 001,002 | `expand(*.servers.*)` | prod.servers.001, prod.servers.002, test.servers.001 |
| `test.servers.*` | 001 | `expand(test.servers.*)` | test.servers.001 |
| `*.servers.*.cpu` | cpu | `expand(*.servers.*.cpu)` | prod.servers.001.cpu, prod.servers.002.cpu, test.servers.001.cpu |
| **Non-expanded query** | **Results** | **Expanded query** | **Expanded results** |
| ---------------------- | -------------- | ------------------------- | ---------------------------------------------------------------------- |
| `*` | `prod`, `test` | `expand(*)` | `prod`, `test` |
| `*.servers` | `servers` | `expand(*.servers)` | `prod.servers`, `test.servers` |
| `test.servers` | `servers` | `expand(test.servers)` | `test.servers` |
| `*.servers.*` | `001`, `002` | `expand(*.servers.*)` | `prod.servers.001`, `prod.servers.002`, `test.servers.001` |
| `test.servers.*` | `001` | `expand(test.servers.*)` | `test.servers.001` |
| `*.servers.*.cpu` | `cpu` | `expand(*.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.
{{% admonition type="note" %}}
A non-expanded query query works like an expanded query but returns only the final segment of each matched metric.
{{% /admonition %}}
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.
Grafana also supports **nested variables**, which allow you to reference other variables in a query.
### Use `__searchFilter` to filter query variable results
For example:
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.
```
apps.$app.servers.*
```
#### Search filter example
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.
To use `__searchFilter` as part of the query field to enable searching for `server` while the user types in the dropdown select box:
### Filter query variable results with `__searchFilter`
Query
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.
```bash
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:
```
apps.$app.servers.$__searchFilter
```
TagValues
TagValues:
```bash
```
tag_values(server, server=~${__searchFilter:regex})
```
## Choose a variable syntax
![variable](/static/img/docs/v2/templated_variable_parameter.png)
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](https://play.grafana.org/d/cvDFGseGz/graphite-templated-nested).