[release-12.1.1] Docs: Refactor Variables page and improve content (#108716)
Co-authored-by: Isabel Matwawana <76437239+imatwawana@users.noreply.github.com>
This commit is contained in:
grafana-delivery-bot[bot]
committed by
GitHub
GitHub
parent
31c9ac9e3e
commit
0e2194e4b8
@@ -15,57 +15,81 @@ weight: 800
|
||||
|
||||
# Variables
|
||||
|
||||
A variable is a placeholder for a value.
|
||||
When you change the value, the element using the variable will change to reflect the new value.
|
||||
|
||||
Variables are displayed as drop-down lists (or in some cases text fields) at the top of the dashboard.
|
||||
These drop-down lists make it easy to update the variable value and thus change the data being displayed in your dashboard.
|
||||
|
||||
For example, if you needed to monitor several servers, you _could_ make a dashboard for each server.
|
||||
Or you could create one dashboard and use panels with variables like this one, where you can change the server using the variable selector:
|
||||
|
||||
{{< figure src="/media/docs/grafana/dashboards/screenshot-selected-variables-v12.png" max-width="750px" alt="Variable drop-down open and two values selected" >}}
|
||||
|
||||
Variables allow you to create more interactive dashboards.
|
||||
Instead of hard-coding things like server, application, and sensor names in your metric queries, you can use variables in their place.
|
||||
They're useful for administrators who want to allow Grafana viewers to adjust visualizations without giving them full editing permissions.
|
||||
|
||||
Using variables also allows you to single-source dashboards.
|
||||
If you have multiple identical data sources or servers, you can make one dashboard and use variables to change what you are viewing.
|
||||
This simplifies maintenance and upkeep enormously.
|
||||
|
||||
{{< youtube id="mMUJ3iwIYwc" >}}
|
||||
|
||||
You can use variables in:
|
||||
|
||||
- Data source queries
|
||||
- [Panel repeating options](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/panels-visualizations/configure-panel-options/#configure-repeating-panels)
|
||||
- [Dashboard and panel links](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/dashboards/build-dashboards/manage-dashboard-links/)
|
||||
- Titles
|
||||
- Descriptions
|
||||
- [Transformations](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/panels-visualizations/query-transform-data/transform-data/)
|
||||
|
||||
To see variable settings, navigate to **Dashboard Settings > Variables**.
|
||||
Click a variable in the list to see its settings.
|
||||
|
||||
{{< docs/play title="Templating - Interactive dashboard" url="https://play.grafana.org/goto/B9Xog68Hg?orgId=1" >}}
|
||||
|
||||
## Template variables {#templates}
|
||||
|
||||
A _template_ is any query that contains a variable.
|
||||
Queries with text that starts with `$` are templates.
|
||||
|
||||
{{< admonition type="note">}}
|
||||
In our documentation and in the application, we typically simply refer to a _template query_ as a _query_, but we often use the terms _variable_ and _template variable_ interchangeably.
|
||||
{{< /admonition >}}
|
||||
|
||||
For example, if you were administering a dashboard to monitor several servers, it could have panels that use template queries like this one:
|
||||
|
||||
```text
|
||||
groupByNode(movingAverage(apps.$app.$server.counters.requests.count, 10), 2, 'sum')
|
||||
```
|
||||
|
||||
The following image shows a panel in edit mode using the query:
|
||||
|
||||
{{< figure src="/media/docs/grafana/dashboards/screenshot-template-query-v12.1.png" max-width="750px" alt="A panel using a template query" >}}
|
||||
|
||||
### Variables in URLs
|
||||
|
||||
Variable values are always synced to the URL using [query parameter syntax](https://grafana.com/docs/grafana/latest/dashboards/variables/variable-syntax/#query-parameters), `var-<varname>=value`.
|
||||
For example:
|
||||
|
||||
```text
|
||||
https://play.grafana.org/d/HYaGDGIMk/templating-global-variables-and-interpolation?orgId=1&from=now-6h&to=now&timezone=utc&var-Server=CCC&var-MyCustomDashboardVariable=Hello%20World%21
|
||||
```
|
||||
|
||||
In the preceding example, the variables and values are `var-Server=CCC` and `var-MyCustomDashboardVariable=Hello%20World%21`.
|
||||
|
||||
## Additional examples
|
||||
|
||||
The following dashboards in Grafana Play provide examples of template variables:
|
||||
|
||||
- [Templating - Repeated panels](https://play.grafana.org/goto/yfZOReUNR?orgId=1) - Using query variables to control how many panels appear in a dashboard.
|
||||
- [Templating - Nested Variables Drilldown](https://play.grafana.org/d/testdata-nested-variables-drilldown/) - Demonstrates how changing one variable value can change the values available in a nested variable.
|
||||
- [Templating - Global variables and interpolation](https://play.grafana.org/d/HYaGDGIMk/) - Shows you how the syntax for Grafana variables works.
|
||||
|
||||
## Next steps
|
||||
|
||||
The following topics describe how to add and manage variables in your dashboards:
|
||||
|
||||
{{< section >}}
|
||||
|
||||
A variable is a placeholder for a value. You can use variables in metric queries and in panel titles. So when you change
|
||||
the value, using the dropdown at the top of the dashboard, your panel's metric queries will change to reflect the new value.
|
||||
|
||||
Variables allow you to create more interactive and dynamic dashboards. Instead of hard-coding things like server, application,
|
||||
and sensor names in your metric queries, you can use variables in their place. Variables are displayed as dropdown lists at the top of
|
||||
the dashboard. These dropdowns make it easy to change the data being displayed in your dashboard.
|
||||
|
||||
{{< figure src="/static/img/docs/v50/variables_dashboard.png" alt="Variable drop-down open and two values selected" >}}
|
||||
|
||||
{{< docs/play title="Templating - Global variables and interpolation" url="https://play.grafana.org/d/HYaGDGIMk/" >}}
|
||||
|
||||
Variables are useful for administrators who want to allow Grafana viewers to adjust visualizations without giving them full editing permissions. Grafana viewers can use variables.
|
||||
|
||||
Variables and templates also allow you to single-source dashboards. If you have multiple identical data sources or servers, you can make one dashboard and use variables to change what you are viewing. This simplifies maintenance and upkeep enormously.
|
||||
|
||||
## Templates
|
||||
|
||||
A _template_ is any query that contains a variable.
|
||||
|
||||
For example, if you were administering a dashboard to monitor several servers, you _could_ make a dashboard for each server. Or you could create one dashboard and use panels with template queries like this one:
|
||||
|
||||
```
|
||||
wmi_system_threads{instance=~"$server"}
|
||||
```
|
||||
|
||||
Variable values are always synced to the URL using the syntax `var-<varname>=value`.
|
||||
|
||||
## Additional Examples
|
||||
|
||||
Variables are listed in drop-down lists across the top of the screen. Select different variables to see how the visualizations change.
|
||||
|
||||
To see variable settings, navigate to **Dashboard Settings > Variables**. Click a variable in the list to see its settings.
|
||||
|
||||
Variables can be used in titles, descriptions, text panels, and queries. Queries with text that starts with `$` are templates. Not all panels will have template queries.
|
||||
|
||||
The following dashboards in Grafana Play provide examples of template variables:
|
||||
|
||||
- [Templating, repeated panels](https://play.grafana.org/d/000000025/) - Using query variables to control how many panels appear.
|
||||
- [Templated Dynamic Dashboard](https://play.grafana.org/d/000000056/) - Uses query variables, chained query variables, an interval variable, and a repeated panel.
|
||||
- [Templating - Nested Variables Drilldown](https://play.grafana.org/d/testdata-nested-variables-drilldown/)
|
||||
|
||||
## Variable best practices
|
||||
|
||||
- Variable drop-down lists are displayed in the order they are listed in the variable list in Dashboard settings.
|
||||
- Put the variables that you will change often at the top, so they will be shown first (far left on the dashboard).
|
||||
- By default, variables don't have a default value. This means that the topmost value in the drop-down is always preselected. If you want to pre-populate a variable with an empty value, you can use the following workaround in the variable settings:
|
||||
1. Select the **Include All Option** checkbox.
|
||||
2. In the **Custom all value** field, enter a value like `+`.
|
||||
|
||||
@@ -35,6 +35,7 @@ keywords:
|
||||
- nested
|
||||
- chained
|
||||
- linked
|
||||
- best practices
|
||||
labels:
|
||||
products:
|
||||
- cloud
|
||||
@@ -138,6 +139,13 @@ To create a variable, follow these steps:
|
||||
|
||||
<!-- vale Grafana.Spelling = YES -->
|
||||
|
||||
### Variable best practices
|
||||
|
||||
- Variable drop-down lists are displayed in the order in which they're listed in the **Variables** in dashboard settings, so put the variables that you will change often at the top, so they will be shown first (far left on the dashboard).
|
||||
- By default, variables don't have a default value. This means that the topmost value in the drop-down list is always preselected. If you want to pre-populate a variable with an empty value, you can use the following workaround in the variable settings:
|
||||
1. Select the **Include All Option** checkbox.
|
||||
2. In the **Custom all value** field, enter a value like `+`.
|
||||
|
||||
## Add a query variable
|
||||
|
||||
Query variables enable you to write a data source query that can return a list of metric names, tag values, or keys. For example, a query variable might return a list of server names, sensor IDs, or data centers. The variable values change as they dynamically fetch options with a data source query.
|
||||
|
||||
@@ -46,9 +46,9 @@ refs:
|
||||
destination: /docs/grafana/<GRAFANA_VERSION>/dashboards/variables/add-template-variables/#add-a-query-variable
|
||||
variable-best-practices:
|
||||
- pattern: /docs/grafana/
|
||||
destination: /docs/grafana/<GRAFANA_VERSION>/dashboards/variables/#variable-best-practices
|
||||
destination: /docs/grafana/<GRAFANA_VERSION>/dashboards/variables/add-template-variables/#variable-best-practices
|
||||
- pattern: /docs/grafana-cloud/
|
||||
destination: /docs/grafana-cloud/visualizations/dashboards/variables/#variable-best-practices
|
||||
destination: /docs/grafana-cloud/visualizations/dashboards/variables/add-template-variables/#variable-best-practices
|
||||
---
|
||||
|
||||
# InfluxDB template variables
|
||||
|
||||
Reference in New Issue
Block a user