Skip to content

N
nexpie-grafana-theme
Commit e7057387 by Diana Payton Committed by GitHub
Options

Docs: Refactor Variables and Templating content (#23952) 

* Moved templating.md

Moved file to a different folder, added alias information, updated menu.yaml

* Split out advanced variable format options from templating.md

* Reworked Advanced variable format options

* Update templating.md

* Moved global variables to another topic

* Moved template files

* Update global-variables.md

* Update global-variables.md

* Update templates-and-variables.md

* made new repeating panels and rows topic

* updated links and menu

* Update advanced-variable-format-options.md

* Update repeat-panels-or-rows.md

* Update menu.yaml

* Update prometheus.md

* Applied Daniel's edits
parent 1bdc9703
Showing with 718 additions and 630 deletions
docs/sources/features/dashboard/dashboards.md
...@@ -41,7 +41,7 @@ The image above shows you the top header for a Dashboard. ...@@ -41,7 +41,7 @@ The image above shows you the top header for a Dashboard.
The time period for the dashboard can be controlled by the [Time range controls]({{< relref "../../reference/timerange.md" >}}) in the upper right of the dashboard. The time period for the dashboard can be controlled by the [Time range controls]({{< relref "../../reference/timerange.md" >}}) in the upper right of the dashboard.
Dashboards can use [templating]({{< relref "../../reference/templating.md" >}}) to make them more dynamic and interactive. Dashboards can use [templating]({{< relref "../../variables/templates-and-variables.md" >}}) to make them more dynamic and interactive.
Dashboards can use [annotations]({{< relref "../../reference/annotations.md" >}}) to display event data across panels. This can help correlate the time series data in the panel with other events. Dashboards can use [annotations]({{< relref "../../reference/annotations.md" >}}) to display event data across panels. This can help correlate the time series data in the panel with other events.
...@@ -61,4 +61,4 @@ We use a unit abstraction so that Grafana looks great on all screens sizes. ...@@ -61,4 +61,4 @@ We use a unit abstraction so that Grafana looks great on all screens sizes.
Collapse a row by clicking on the row title. If you save a dashboard with a row collapsed, then it saves in that state and does not load those graphs until you expand the row. Collapse a row by clicking on the row title. If you save a dashboard with a row collapsed, then it saves in that state and does not load those graphs until you expand the row.
Use the [repeating rows]({{< relref "../../reference/templating.md#repeating-rows" >}}) functionality to dynamically create or remove entire rows, which can be filled with panels, based on the template variables selected. Use the [repeating rows]({{< relref "../../variables/templates-and-variables.md#repeating-rows" >}}) functionality to dynamically create or remove entire rows, which can be filled with panels, based on the template variables selected.
docs/sources/features/datasources/azuremonitor.md
...@@ -146,7 +146,7 @@ Examples: ...@@ -146,7 +146,7 @@ Examples:
{{< docs-imagebox img="/img/docs/v60/azuremonitor-service-variables.png" class="docs-image--no-shadow" caption="Nested Azure Monitor Template Variables" >}} {{< docs-imagebox img="/img/docs/v60/azuremonitor-service-variables.png" class="docs-image--no-shadow" caption="Nested Azure Monitor Template Variables" >}}
Check out the [Templating]({{< relref "../../reference/templating.md" >}}) documentation for an introduction to the templating feature and the different Check out the [Templating]({{< relref "../../variables/templates-and-variables.md" >}}) documentation for an introduction to the templating feature and the different
types of template variables. types of template variables.
### Azure Monitor Metrics Whitelist ### Azure Monitor Metrics Whitelist
...@@ -198,7 +198,7 @@ Examples: ...@@ -198,7 +198,7 @@ Examples:
Use the one of the following queries in the `Query` field in the Variable edit view. Use the one of the following queries in the `Query` field in the Variable edit view.
Check out the [Templating]({{< relref "../../reference/templating.md" >}}) documentation for an introduction to the templating feature and the different Check out the [Templating]({{< relref "../../variables/templates-and-variables.md" >}}) documentation for an introduction to the templating feature and the different
types of template variables. types of template variables.
| Name | Description | | Name | Description |
...@@ -272,13 +272,13 @@ To make writing queries easier there are several Grafana macros that can be used ...@@ -272,13 +272,13 @@ To make writing queries easier there are several Grafana macros that can be used
There are also some Grafana variables that can be used in Azure Log Analytics queries: There are also some Grafana variables that can be used in Azure Log Analytics queries:
- `$__interval` - Grafana calculates the minimum time grain that can be used to group by time in queries. More details on how it works [here]({{< relref "../../reference/templating.md#interval-variables" >}}). It returns a time grain like `5m` or `1h` that can be used in the bin function. E.g. `summarize count() by bin(TimeGenerated, $__interval)` - `$__interval` - Grafana calculates the minimum time grain that can be used to group by time in queries. More details on how it works [here]({{< relref "../../variables/templates-and-variables.md#interval-variables" >}}). It returns a time grain like `5m` or `1h` that can be used in the bin function. E.g. `summarize count() by bin(TimeGenerated, $__interval)`
### Templating with Variables for Azure Log Analytics ### Templating with Variables for Azure Log Analytics
Any Log Analytics query that returns a list of values can be used in the `Query` field in the Variable edit view. There is also one Grafana function for Log Analytics that returns a list of workspaces. Any Log Analytics query that returns a list of values can be used in the `Query` field in the Variable edit view. There is also one Grafana function for Log Analytics that returns a list of workspaces.
Refer to the [Variables]({{< relref "../../reference/templating.md" >}}) documentation for an introduction to the templating feature and the different Refer to the [Variables]({{< relref "../../variables/templates-and-variables.md" >}}) documentation for an introduction to the templating feature and the different
types of template variables. types of template variables.
| Name | Description | | Name | Description |
......
docs/sources/features/datasources/cloudwatch.md
...@@ -184,7 +184,7 @@ To import the pre-configured dashboards, go to the configuration page of your Cl ...@@ -184,7 +184,7 @@ To import the pre-configured dashboards, go to the configuration page of your Cl
Instead of hard-coding things like server, application and sensor name in you metric queries you can use variables in their place. Variables are shown as dropdown select boxes at the top of the dashboard. These dropdowns make it easy to change the data being displayed in your dashboard. Instead of hard-coding things like server, application and sensor name in you metric queries you can use variables in their place. Variables are shown as dropdown select boxes at the top of the dashboard. These dropdowns make it easy to change the data being displayed in your dashboard.
See the [Templating]({{< relref "../../reference/templating.md" >}}) documentation for an introduction to the templating feature and the different types of template variables. See the [Templating]({{< relref "../../variables/templates-and-variables.md" >}}) documentation for an introduction to the templating feature and the different types of template variables.
### Query variable ### Query variable
......
docs/sources/features/datasources/data-sources.md
...@@ -17,6 +17,6 @@ Each data source has a specific query editor that is customized for the features ...@@ -17,6 +17,6 @@ Each data source has a specific query editor that is customized for the features
Use the query editor to build one or more queries in your time series database. The panel instantly updates, allowing you to effectively explore your data in real time and build a perfect query for that particular panel. Use the query editor to build one or more queries in your time series database. The panel instantly updates, allowing you to effectively explore your data in real time and build a perfect query for that particular panel.
You can use [template variables]({{< relref "../../reference/templating.md" >}}) in the query editor within the queries themselves. This provides a powerful way to explore data dynamically based on the templating variables selected on the dashboard. You can use [template variables]({{< relref "../../variables/templates-and-variables.md" >}}) in the query editor within the queries themselves. This provides a powerful way to explore data dynamically based on the templating variables selected on the dashboard.
Grafana allows you to reference queries in the query editor by the row that they’re on. If you add a second query to graph, you can reference the first query by typing in #A. This provides an easy and convenient way to build compound queries. Grafana allows you to reference queries in the query editor by the row that they’re on. If you add a second query to graph, you can reference the first query by typing in #A. This provides an easy and convenient way to build compound queries.
\ No newline at end of file
docs/sources/features/datasources/elasticsearch.md
...@@ -120,7 +120,7 @@ Instead of hard-coding things like server, application and sensor name in your m ...@@ -120,7 +120,7 @@ Instead of hard-coding things like server, application and sensor name in your m
Variables are shown as dropdown select boxes at the top of the dashboard. These dropdowns make it easy to change the data Variables are shown as dropdown select boxes at the top of the dashboard. These dropdowns make it easy to change the data
being displayed in your dashboard. being displayed in your dashboard.
Check out the [Templating]({{< relref "../../reference/templating.md" >}}) documentation for an introduction to the templating feature and the different Check out the [Templating]({{< relref "../../variables/templates-and-variables.md" >}}) documentation for an introduction to the templating feature and the different
types of template variables. types of template variables.
### Query variable ### Query variable
......
docs/sources/features/datasources/graphite.md
...@@ -91,7 +91,7 @@ Instead of hard-coding things like server, application and sensor name in your m ...@@ -91,7 +91,7 @@ Instead of hard-coding things like server, application and sensor name in your m
Variables are shown as dropdown select boxes at the top of the dashboard. These dropdowns make it easy to change the data Variables are shown as dropdown select boxes at the top of the dashboard. These dropdowns make it easy to change the data
being displayed in your dashboard. being displayed in your dashboard.
Check out the [Templating]({{< relref "../../reference/templating.md" >}}) documentation for an introduction to the templating feature and the different Check out the [Templating]({{< relref "../../variables/templates-and-variables.md" >}}) documentation for an introduction to the templating feature and the different
types of template variables. types of template variables.
Graphite 1.1 introduced tags and Grafana added support for Graphite queries with tags in version 5.0. To create a variable using tag values, then you need to use the Grafana functions `tags` and `tag_values`. Graphite 1.1 introduced tags and Grafana added support for Graphite queries with tags in version 5.0. To create a variable using tag values, then you need to use the Grafana functions `tags` and `tag_values`.
...@@ -158,7 +158,7 @@ Example of a tag expression with regex formatting and using the Equal Tilde oper ...@@ -158,7 +158,7 @@ Example of a tag expression with regex formatting and using the Equal Tilde oper
server=~${servers:regex} server=~${servers:regex}
``` ```
Check out the [Advanced Formatting Options section in the Variables]({{< relref "../../reference/templating.md#advanced-formatting-options" >}}) documentation for examples and details. Check out the [Advanced Formatting Options section in the Variables]({{< relref "../../variables/templates-and-variables.md#advanced-formatting-options" >}}) documentation for examples and details.
## Annotations ## Annotations
......
docs/sources/features/datasources/influxdb.md
...@@ -144,7 +144,7 @@ Instead of hard-coding things like server, application and sensor name in your m ...@@ -144,7 +144,7 @@ Instead of hard-coding things like server, application and sensor name in your m
Variables are shown as dropdown select boxes at the top of the dashboard. These dropdowns make it easy to change the data Variables are shown as dropdown select boxes at the top of the dashboard. These dropdowns make it easy to change the data
being displayed in your dashboard. being displayed in your dashboard.
Check out the [Templating]({{< relref "../../reference/templating.md" >}}) documentation for an introduction to the templating feature and the different Check out the [Templating]({{< relref "../../variables/templates-and-variables.md" >}}) documentation for an introduction to the templating feature and the different
types of template variables. types of template variables.
### Query variable ### Query variable
......
docs/sources/features/datasources/loki.md
...@@ -146,7 +146,7 @@ log message you're interested in. ...@@ -146,7 +146,7 @@ log message you're interested in.
Instead of hard-coding things like server, application and sensor name in your metric queries, you can use variables in their place. Variables are shown as drop-down select boxes at the top of the dashboard. These drop-down boxes make it easy to change the data being displayed in your dashboard. Instead of hard-coding things like server, application and sensor name in your metric queries, you can use variables in their place. Variables are shown as drop-down select boxes at the top of the dashboard. These drop-down boxes make it easy to change the data being displayed in your dashboard.
Check out the [Templating]({{< relref "../../reference/templating" >}}) documentation for an introduction to the templating feature and the different types of template variables. Check out the [Templating]({{< relref "../../variables/templates-and-variables" >}}) documentation for an introduction to the templating feature and the different types of template variables.
## Annotations ## Annotations
......
docs/sources/features/datasources/mssql.md
...@@ -39,7 +39,7 @@ Name | Description ...@@ -39,7 +39,7 @@ Name | Description
### Min time interval ### Min time interval
A lower limit for the [$__interval]({{< relref "../../reference/templating/#the-interval-variable" >}}) and [$__interval_ms]({{< relref "../../reference/templating/#the-interval-ms-variable" >}}) variables. A lower limit for the [$__interval]({{< relref "../../variables/templates-and-variables/#the-interval-variable" >}}) and [$__interval_ms]({{< relref "../../variables/templates-and-variables/#the-interval-ms-variable" >}}) variables.
Recommended to be set to write frequency, for example `1m` if your data is written every minute. Recommended to be set to write frequency, for example `1m` if your data is written every minute.
This option can also be overridden/configured in a dashboard panel under data source options. It's important to note that this value **needs** to be formatted as a This option can also be overridden/configured in a dashboard panel under data source options. It's important to note that this value **needs** to be formatted as a
number followed by a valid time identifier, e.g. `1m` (1 minute) or `30s` (30 seconds). The following time identifiers are supported: number followed by a valid time identifier, e.g. `1m` (1 minute) or `30s` (30 seconds). The following time identifiers are supported:
...@@ -300,7 +300,7 @@ Any series lacking a value in a 3 minute window will have a value of zero which ...@@ -300,7 +300,7 @@ Any series lacking a value in a 3 minute window will have a value of zero which
Instead of hard-coding things like server, application and sensor name in your metric queries you can use variables in their place. Variables are shown as dropdown select boxes at the top of the dashboard. These dropdowns make it easy to change the data being displayed in your dashboard. Instead of hard-coding things like server, application and sensor name in your metric queries you can use variables in their place. Variables are shown as dropdown select boxes at the top of the dashboard. These dropdowns make it easy to change the data being displayed in your dashboard.
Check out the [Templating]({{< relref "../../reference/templating.md" >}}) documentation for an introduction to the templating feature and the different types of template variables. Check out the [Templating]({{< relref "../../variables/templates-and-variables.md" >}}) documentation for an introduction to the templating feature and the different types of template variables.
### Query Variable ### Query Variable
...@@ -370,7 +370,7 @@ Grafana automatically creates a quoted, comma-separated string for multi-value v ...@@ -370,7 +370,7 @@ Grafana automatically creates a quoted, comma-separated string for multi-value v
`${servers:csv}` `${servers:csv}`
Read more about variable formatting options in the [Variables]({{< relref "../../reference/templating.md#advanced-formatting-options" >}}) documentation. Read more about variable formatting options in the [Variables]({{< relref "../../variables/templates-and-variables.md#advanced-formatting-options" >}}) documentation.
## Annotations ## Annotations
......
docs/sources/features/datasources/mysql.md
...@@ -41,7 +41,7 @@ Name | Description ...@@ -41,7 +41,7 @@ Name | Description
### Min time interval ### Min time interval
A lower limit for the [$__interval]({{< relref "../../reference/templating/#the-interval-variable" >}}) and [$__interval_ms]({{< relref "../../reference/templating/#the-interval-ms-variable" >}}) variables. A lower limit for the [$__interval]({{< relref "../../variables/templates-and-variables/#the-interval-variable" >}}) and [$__interval_ms]({{< relref "../../variables/templates-and-variables/#the-interval-ms-variable" >}}) variables.
Recommended to be set to write frequency, for example `1m` if your data is written every minute. Recommended to be set to write frequency, for example `1m` if your data is written every minute.
This option can also be overridden/configured in a dashboard panel under data source options. It's important to note that this value **needs** to be formatted as a This option can also be overridden/configured in a dashboard panel under data source options. It's important to note that this value **needs** to be formatted as a
number followed by a valid time identifier, e.g. `1m` (1 minute) or `30s` (30 seconds). The following time identifiers are supported: number followed by a valid time identifier, e.g. `1m` (1 minute) or `30s` (30 seconds). The following time identifiers are supported:
...@@ -238,7 +238,7 @@ This feature is currently available in the nightly builds and will be included i ...@@ -238,7 +238,7 @@ This feature is currently available in the nightly builds and will be included i
Instead of hard-coding things like server, application and sensor name in your metric queries you can use variables in their place. Variables are shown as dropdown select boxes at the top of the dashboard. These dropdowns make it easy to change the data being displayed in your dashboard. Instead of hard-coding things like server, application and sensor name in your metric queries you can use variables in their place. Variables are shown as dropdown select boxes at the top of the dashboard. These dropdowns make it easy to change the data being displayed in your dashboard.
Check out the [Templating]({{< relref "../../reference/templating.md" >}}) documentation for an introduction to the templating feature and the different types of template variables. Check out the [Templating]({{< relref "../../variables/templates-and-variables.md" >}}) documentation for an introduction to the templating feature and the different types of template variables.
### Query Variable ### Query Variable
...@@ -331,7 +331,7 @@ Grafana automatically creates a quoted, comma-separated string for multi-value v ...@@ -331,7 +331,7 @@ Grafana automatically creates a quoted, comma-separated string for multi-value v
`${servers:csv}` `${servers:csv}`
Read more about variable formatting options in the [Variables]({{< relref "../../reference/templating.md#advanced-formatting-options" >}}) documentation. Read more about variable formatting options in the [Variables]({{< relref "../../variables/templates-and-variables.md#advanced-formatting-options" >}}) documentation.
## Annotations ## Annotations
......
docs/sources/features/datasources/opentsdb.md
...@@ -53,7 +53,7 @@ Instead of hard-coding things like server, application and sensor name in your m ...@@ -53,7 +53,7 @@ Instead of hard-coding things like server, application and sensor name in your m
Variables are shown as dropdown select boxes at the top of the dashboard. These dropdowns make it easy to change the data Variables are shown as dropdown select boxes at the top of the dashboard. These dropdowns make it easy to change the data
being displayed in your dashboard. being displayed in your dashboard.
Check out the [Templating]({{< relref "../../reference/templating.md" >}}) documentation for an introduction to the templating feature and the different Check out the [Templating]({{< relref "../../variables/templates-and-variables.md" >}}) documentation for an introduction to the templating feature and the different
types of template variables. types of template variables.
### Query variable ### Query variable
......
docs/sources/features/datasources/postgres.md
...@@ -39,7 +39,7 @@ Name | Description ...@@ -39,7 +39,7 @@ Name | Description
### Min time interval ### Min time interval
A lower limit for the [$__interval]({{< relref "../../reference/templating/#the-interval-variable" >}}) and [$__interval_ms]({{< relref "../../reference/templating/#the-interval-ms-variable" >}}) variables. A lower limit for the [$__interval]({{< relref "../../variables/templates-and-variables/#the-interval-variable" >}}) and [$__interval_ms]({{< relref "../../variables/templates-and-variables/#the-interval-ms-variable" >}}) variables.
Recommended to be set to write frequency, for example `1m` if your data is written every minute. Recommended to be set to write frequency, for example `1m` if your data is written every minute.
This option can also be overridden/configured in a dashboard panel under data source options. It's important to note that this value **needs** to be formatted as a This option can also be overridden/configured in a dashboard panel under data source options. It's important to note that this value **needs** to be formatted as a
number followed by a valid time identifier, e.g. `1m` (1 minute) or `30s` (30 seconds). The following time identifiers are supported: number followed by a valid time identifier, e.g. `1m` (1 minute) or `30s` (30 seconds). The following time identifiers are supported:
...@@ -242,7 +242,7 @@ ORDER BY time ...@@ -242,7 +242,7 @@ ORDER BY time
Instead of hard-coding things like server, application and sensor name in your metric queries you can use variables in their place. Variables are shown as dropdown select boxes at the top of the dashboard. These dropdowns make it easy to change the data being displayed in your dashboard. Instead of hard-coding things like server, application and sensor name in your metric queries you can use variables in their place. Variables are shown as dropdown select boxes at the top of the dashboard. These dropdowns make it easy to change the data being displayed in your dashboard.
Check out the [Templating]({{< relref "../../reference/templating.md" >}}) documentation for an introduction to the templating feature and the different types of template variables. Check out the [Templating]({{< relref "../../variables/templates-and-variables.md" >}}) documentation for an introduction to the templating feature and the different types of template variables.
### Query Variable ### Query Variable
...@@ -333,7 +333,7 @@ Grafana automatically creates a quoted, comma-separated string for multi-value v ...@@ -333,7 +333,7 @@ Grafana automatically creates a quoted, comma-separated string for multi-value v
`${servers:csv}` `${servers:csv}`
Read more about variable formatting options in the [Variables]({{< relref "../../reference/templating.md#advanced-formatting-options" >}}) documentation. Read more about variable formatting options in the [Variables]({{< relref "../../variables/templates-and-variables.md#advanced-formatting-options" >}}) documentation.
## Annotations ## Annotations
......
docs/sources/features/datasources/prometheus.md 100755 → 100644
...@@ -67,7 +67,7 @@ Instead of hard-coding things like server, application and sensor name in your m ...@@ -67,7 +67,7 @@ Instead of hard-coding things like server, application and sensor name in your m
Variables are shown as dropdown select boxes at the top of the dashboard. These dropdowns make it easy to change the data Variables are shown as dropdown select boxes at the top of the dashboard. These dropdowns make it easy to change the data
being displayed in your dashboard. being displayed in your dashboard.
Check out the [Templating]({{< relref "../../reference/templating.md" >}}) documentation for an introduction to the templating feature and the different Check out the [Templating]({{< relref "../../variables/templates-and-variables.md" >}}) documentation for an introduction to the templating feature and the different
types of template variables. types of template variables.
### Query variable ### Query variable
...@@ -89,7 +89,8 @@ For details of what _metric names_, _label names_ and _label values_ are please ...@@ -89,7 +89,8 @@ For details of what _metric names_, _label names_ and _label values_ are please
> Support for `$__range`, `$__range_s` and `$__range_ms` only available from Grafana v5.3 > Support for `$__range`, `$__range_s` and `$__range_ms` only available from Grafana v5.3
You can use some global built-in variables in query variables; `$__interval`, `$__interval_ms`, `$__range`, `$__range_s` and `$__range_ms`, see [Global built-in variables]({{< relref "../../reference/templating/#global-built-in-variables" >}}) for more information. These can be convenient to use in conjunction with the `query_result` function when you need to filter variable queries since You can use some global built-in variables in query variables; `$__interval`, `$__interval_ms`, `$__range`, `$__range_s` and `$__range_ms`, see [Global built-in variables]({{< relref "../../variables/global-variables.md" >}}) for more information. These can be convenient to use in conjunction with the `query_result` function when you need to filter variable queries since
`label_values` function doesn't support queries. `label_values` function doesn't support queries.
Make sure to set the variable's `refresh` trigger to be `On Time Range Change` to get the correct instances when changing the time range on the dashboard. Make sure to set the variable's `refresh` trigger to be `On Time Range Change` to get the correct instances when changing the time range on the dashboard.
......
docs/sources/features/datasources/stackdriver.md
...@@ -133,7 +133,7 @@ The option is called `Stackdriver auto` and the defaults are: ...@@ -133,7 +133,7 @@ The option is called `Stackdriver auto` and the defaults are:
- 5m for time ranges >= 23 hours and < 6 days - 5m for time ranges >= 23 hours and < 6 days
- 1h for time ranges >= 6 days - 1h for time ranges >= 6 days
The other automatic option is `Grafana auto`. This will automatically set the group by time depending on the time range chosen and the width of the graph panel. Read more about the details [here](http://docs.grafana.org/reference/templating/#the-interval-variable). The other automatic option is `Grafana auto`. This will automatically set the group by time depending on the time range chosen and the width of the graph panel. Read more about the details [here](http://docs.grafana.org/variables/templates-and-variables/#the-interval-variable).
It is also possible to choose fixed time intervals to group by, like `1h` or `1d`. It is also possible to choose fixed time intervals to group by, like `1h` or `1d`.
...@@ -231,7 +231,7 @@ Instead of hard-coding things like server, application and sensor name in you me ...@@ -231,7 +231,7 @@ Instead of hard-coding things like server, application and sensor name in you me
Variables are shown as dropdown select boxes at the top of the dashboard. These dropdowns make it easy to change the data Variables are shown as dropdown select boxes at the top of the dashboard. These dropdowns make it easy to change the data
being displayed in your dashboard. being displayed in your dashboard.
Check out the [Templating]({{< relref "../../reference/templating.md" >}}) documentation for an introduction to the templating feature and the different Check out the [Templating]({{< relref "../../variables/templates-and-variables.md" >}}) documentation for an introduction to the templating feature and the different
types of template variables. types of template variables.
### Query Variable ### Query Variable
......
docs/sources/features/panels/graph.md
...@@ -33,7 +33,7 @@ The general tab allows customization of a panel's appearance and menu options. ...@@ -33,7 +33,7 @@ The general tab allows customization of a panel's appearance and menu options.
- **Transparent** - If checked, removes the solid background of the panel (default not checked). - **Transparent** - If checked, removes the solid background of the panel (default not checked).
### Repeat ### Repeat
Repeat a panel for each value of a variable. Repeating panels are described in more detail [here]({{< relref "../../reference/templating.md#repeating-panels" >}}). Repeat a panel for each value of a variable. Repeating panels are described in more detail [here]({{< relref "../../variables/templates-and-variables.md#repeating-panels" >}}).
## Metrics ## Metrics
......
docs/sources/features/panels/panels.md
...@@ -16,7 +16,7 @@ There are a wide variety of styling and formatting options for each panel. Panel ...@@ -16,7 +16,7 @@ There are a wide variety of styling and formatting options for each panel. Panel
Panels like the [Graph]({{< relref "graph.md" >}}) panel allow you to graph as many metrics and series as you want. Other panels like [Singlestat]({{< relref "singlestat.md" >}}) require a reduction of a single query into a single number. Panels like the [Graph]({{< relref "graph.md" >}}) panel allow you to graph as many metrics and series as you want. Other panels like [Singlestat]({{< relref "singlestat.md" >}}) require a reduction of a single query into a single number.
Panels can be made more dynamic with [Dashboard Templating]({{< relref "../../reference/templating.md" >}}) variable strings within the panel configuration. The template can include queries to your data source configured in the Query Editor. Panels can be made more dynamic with [Dashboard Templating]({{< relref "../../variables/templates-and-variables.md" >}}) variable strings within the panel configuration. The template can include queries to your data source configured in the Query Editor.
Panels can be [shared]({{< relref "../../reference/share_panel.md" >}}) easily in a variety of ways. Panels can be [shared]({{< relref "../../reference/share_panel.md" >}}) easily in a variety of ways.
......
docs/sources/guides/what-is-grafana.md
...@@ -44,7 +44,7 @@ Refer to [Annotations]({{< relref "../reference/annotations.md" >}}) for more in ...@@ -44,7 +44,7 @@ Refer to [Annotations]({{< relref "../reference/annotations.md" >}}) for more in
## Dashboard variables ## Dashboard variables
[Template variables]({{< relref "../reference/templating.md" >}}) allow you to create dashboards that can be reused for lots of different use cases. Values aren't hard-coded with these templates, so for instance, if you have a production server and a test server, you can use the same dashboard for both. [Template variables]({{< relref "../variables/templates-and-variables.md" >}}) allow you to create dashboards that can be reused for lots of different use cases. Values aren't hard-coded with these templates, so for instance, if you have a production server and a test server, you can use the same dashboard for both.
Templating allows you to drill down into your data, say, from all data to North America data, down to Texas data, and beyond. You can also share these dashboards across teams within your organization—or if you create a great dashboard template for a popular data source, you can contribute it to the whole community to customize and use. Templating allows you to drill down into your data, say, from all data to North America data, down to Texas data, and beyond. You can also share these dashboards across teams within your organization—or if you create a great dashboard template for a popular data source, you can contribute it to the whole community to customize and use.
......
docs/sources/guides/whats-new-in-v5-1.md
...@@ -95,7 +95,7 @@ New enhancements includes support for mapping a numeric value/range to text and ...@@ -95,7 +95,7 @@ New enhancements includes support for mapping a numeric value/range to text and
## New variable interpolation syntax ## New variable interpolation syntax
We now support a new option for rendering variables that gives the user full control of how the value(s) should be rendered. We now support a new option for rendering variables that gives the user full control of how the value(s) should be rendered.
In the table below you can see some examples and you can find all different options in the [Variables documentation](http://docs.grafana.org/reference/templating/#advanced-formatting-options). In the table below you can see some examples and you can find all different options in the [Variables documentation](http://docs.grafana.org/variables/templates-and-variables/#advanced-formatting-options).
Filter Option | Example | Raw | Interpolated | Description Filter Option | Example | Raw | Interpolated | Description
------------ | ------------- | ------------- | ------------- | ------------- ------------ | ------------- | ------------- | ------------- | -------------
......
docs/sources/menu.yaml
...@@ -29,171 +29,179 @@ ...@@ -29,171 +29,179 @@
- name: Administration - name: Administration
link: /administration/ link: /administration/
children: children:
- name: Configuration - name: Configuration
link: /installation/configuration/ link: /installation/configuration/
- name: Configure Docker image - name: Configure Docker image
link: /installation/configure-docker/ link: /installation/configure-docker/
- name: Security - name: Security
link: /installation/security/ link: /installation/security/
- name: Authentication - name: Authentication
link: /auth/ link: /auth/
children: children:
- link: /auth/overview/ - link: /auth/overview/
name: Overview name: Overview
- link: /auth/auth-proxy/ - link: /auth/auth-proxy/
name: Auth Proxy name: Auth Proxy
- link: /auth/ldap/ - link: /auth/ldap/
name: LDAP name: LDAP
- link: /auth/enhanced_ldap/ - link: /auth/enhanced_ldap/
name: Enhanced LDAP name: Enhanced LDAP
- link: /auth/generic-oauth/ - link: /auth/generic-oauth/
name: Generic OAuth name: Generic OAuth
- link: /auth/google/ - link: /auth/google/
name: Google name: Google
- link: /auth/azuread/ - link: /auth/azuread/
name: Azure AD name: Azure AD
- link: /auth/github/ - link: /auth/github/
name: GitHub name: GitHub
- link: /auth/gitlab/ - link: /auth/gitlab/
name: GitLab name: GitLab
- link: /auth/okta/ - link: /auth/okta/
name: Okta name: Okta
- link: /auth/saml/ - link: /auth/saml/
name: SAML name: SAML
- link: /auth/team-sync/ - link: /auth/team-sync/
name: Team Sync name: Team Sync
- name: Permissions - name: Permissions
link: /permissions/ link: /permissions/
children: children:
- link: /permissions/overview/ - link: /permissions/overview/
name: Overview name: Overview
- link: /permissions/organization_roles/ - link: /permissions/organization_roles/
name: Organization Roles name: Organization Roles
- link: /permissions/dashboard_folder_permissions/ - link: /permissions/dashboard_folder_permissions/
name: Dashboard and Folder name: Dashboard and Folder
- link: /permissions/datasource_permissions/ - link: /permissions/datasource_permissions/
name: Data source name: Data source
- name: Grafana CLI - name: Grafana CLI
link: /administration/cli/ link: /administration/cli/
- name: Internal metrics - name: Internal metrics
link: /administration/metrics/ link: /administration/metrics/
- name: Provisioning - name: Provisioning
link: /administration/provisioning/ link: /administration/provisioning/
- name: Set up Grafana for high availability - name: Set up Grafana for high availability
link: /tutorials/ha_setup/ link: /tutorials/ha_setup/
- name: Troubleshooting - name: Troubleshooting
link: /installation/troubleshooting/ link: /installation/troubleshooting/
- name: Features - name: Panels
link: /features/ link: /features/panels/
children: children:
- name: Panels - link: /features/panels/panels/
link: /features/panels/ name: Overview
children: - link: /features/panels/graph/
- link: /features/panels/panels/ name: Graph
name: Overview - link: /features/panels/table_panel/
- link: /features/panels/graph/ name: Table
name: Graph - link: /features/panels/stat/
- link: /features/panels/table_panel/ name: Stat
name: Table - link: /features/panels/gauge/
- link: /features/panels/stat/ name: Gauge
name: Stat - link: /features/panels/bar_gauge/
- link: /features/panels/gauge/ name: Bar gauge
name: Gauge - link: /features/panels/logs/
- link: /features/panels/bar_gauge/ name: Logs
name: Bar gauge - link: /features/panels/singlestat/
- link: /features/panels/logs/ name: Singlestat
name: Logs - link: /features/panels/heatmap/
- link: /features/panels/singlestat/ name: Heatmap
name: Singlestat - link: /features/panels/alertlist/
- link: /features/panels/heatmap/ name: Alert list
name: Heatmap - link: /features/panels/dashlist/
- link: /features/panels/alertlist/ name: Dashboard list
name: Alert list - link: /features/panels/text/
- link: /features/panels/dashlist/ name: Text
name: Dashboard list - name: Dashboard features
- link: /features/panels/text/ link: /features/dashboard/
name: Text children:
- name: Dashboard features - link: /features/dashboard/dashboards/
link: /features/dashboard/ name: Overview
children: - link: /reference/annotations/
- link: /features/dashboard/dashboards/ name: Annotations
name: Overview - link: /reference/dashboard_folders/
- link: /reference/templating/ name: Folders
name: Variables - link: /reference/playlist/
- link: /reference/annotations/ name: Playlist
name: Annotations - link: /reference/search/
- link: /reference/dashboard_folders/ name: Search
name: Folders - link: /reference/share_dashboard/
- link: /reference/playlist/ name: Sharing a dashboard
name: Playlist - link: /reference/share_panel/
- link: /reference/search/ name: Sharing a panel
name: Search - link: /reference/timerange/
- link: /reference/share_dashboard/ name: Time range
name: Sharing a dashboard - link: /reference/export_import/
- link: /reference/share_panel/ name: Export and import
name: Sharing a panel - link: /reference/datalinks/
- link: /reference/timerange/ name: Data links
name: Time range - link: /reference/dashboard_history/
- link: /reference/export_import/ name: Dashboard version history
name: Export and import - name: Keyboard Shortcuts
- link: /reference/datalinks/ link: /features/shortcuts/
name: Data links - name: Reporting
- name: Navigation links link: /features/reporting/
link: /features/dashboard/links - link: /reference/dashboard/
- link: /reference/dashboard_history/ name: JSON Model
name: Version history - link: /reference/scripting/
- link: /reference/dashboard/ name: Scripted dashboards
name: JSON Model - name: Data sources
- name: Data sources link: /features/datasources/
link: /features/datasources/ children:
children: - link: /features/datasources/add-a-data-source/
- link: /features/datasources/add-a-data-source/ name: Add data source
name: Add data source - link: /features/datasources/cloudwatch/
- link: /features/datasources/cloudwatch/ name: AWS Cloudwatch
name: AWS Cloudwatch - link: /features/datasources/azuremonitor/
- link: /features/datasources/azuremonitor/ name: Azure Monitor
name: Azure Monitor - link: /features/datasources/elasticsearch/
- link: /features/datasources/elasticsearch/ name: Elasticsearch
name: Elasticsearch - link: /features/datasources/stackdriver/
- link: /features/datasources/stackdriver/ name: Google Stackdriver
name: Google Stackdriver - link: /features/datasources/graphite/
- link: /features/datasources/graphite/ name: Graphite
name: Graphite - link: /features/datasources/influxdb/
- link: /features/datasources/influxdb/ name: InfluxDB
name: InfluxDB - link: /features/datasources/loki/
- link: /features/datasources/loki/ name: Loki
name: Loki - link: /features/datasources/mssql/
- link: /features/datasources/mssql/ name: Microsoft SQL Server
name: Microsoft SQL Server - link: /features/datasources/mixed/
- link: /features/datasources/mixed/ name: MixedData
name: MixedData - link: /features/datasources/mysql/
- link: /features/datasources/mysql/ name: MySQL
name: MySQL - link: /features/datasources/opentsdb/
- link: /features/datasources/opentsdb/ name: OpenTSDB
name: OpenTSDB - link: /features/datasources/postgres/
- link: /features/datasources/postgres/ name: PostgreSQL
name: PostgreSQL - link: /features/datasources/prometheus/
- link: /features/datasources/prometheus/ name: Prometheus
name: Prometheus - link: /features/datasources/testdata/
- link: /features/datasources/testdata/ name: TestData DB
name: TestData DB - name: Explore
- name: Explore link: /features/explore/
link: /features/explore/ - name: Alerting
- name: Alerting link: /alerting/
link: /alerting/ children:
children: - link: /alerting/rules/
- link: /alerting/rules/ name: Engine and Rules
name: Engine and Rules - link: /alerting/metrics/
- link: /alerting/metrics/ name: Metrics
name: Metrics - link: /alerting/notifications/
- link: /alerting/notifications/ name: Notifications
name: Notifications - name: Image rendering
- name: Image rendering link: /administration/image_rendering/
link: /administration/image_rendering/ - name: Navigation links
- name: Keyboard Shortcuts link: /features/navigation-links/
link: /features/shortcuts/ - name: Templates and variables
- name: Reporting link: /variables/
link: /features/reporting/ children:
- link: /variables/templates-and-variables/
name: Overview
- link: /variables/global-variables/
name: Global variables
- link: /variables/advanced-variable-format-options/
name: Advanced variable formats
- link: /variables/repeat-panels-or-rows/
name: Repeat panels or rows
- name: What's new in Grafana - name: What's new in Grafana
link: /whatsnew/ link: /whatsnew/
children: children:
......
docs/sources/packages_api/runtime/_index.md
...@@ -58,7 +58,7 @@ A library containing services, configurations etc. used to interact with the Gra ...@@ -58,7 +58,7 @@ A library containing services, configurations etc. used to interact with the Gra
| [MetaAnalyticsEvent](./metaanalyticsevent/) | Describes meta analytics event with predefined [EchoEventType.MetaAnalytics](./runtime/echoeventtype/metaanalytics.md) type. | | [MetaAnalyticsEvent](./metaanalyticsevent/) | Describes meta analytics event with predefined [EchoEventType.MetaAnalytics](./runtime/echoeventtype/metaanalytics.md) type. |
| [PluginCssOptions](./plugincssoptions/) | Option to specify a plugin css that should be applied for the dark and the light theme. | | [PluginCssOptions](./plugincssoptions/) | Option to specify a plugin css that should be applied for the dark and the light theme. |
| [SizeMeta](./sizemeta/) | Describes a size with width/height | | [SizeMeta](./sizemeta/) | Describes a size with width/height |
| [TemplateSrv](./templatesrv/) | Via the TemplateSrv consumers get access to all the available template variables that can be used within the current active dashboard.<!-- -->For a more in-depth description visit: https://grafana.com/docs/grafana/latest/reference/templating | | [TemplateSrv](./templatesrv/) | Via the TemplateSrv consumers get access to all the available template variables that can be used within the current active dashboard.<!-- -->For a more in-depth description visit: https://grafana.com/docs/grafana/latest/variables/templates-and-variables |
## Variables ## Variables
......
docs/sources/packages_api/runtime/templatesrv.md
...@@ -11,7 +11,7 @@ type = "docs" ...@@ -11,7 +11,7 @@ type = "docs"
Via the TemplateSrv consumers get access to all the available template variables that can be used within the current active dashboard. Via the TemplateSrv consumers get access to all the available template variables that can be used within the current active dashboard.
For a more in-depth description visit: https://grafana.com/docs/grafana/latest/reference/templating For a more in-depth description visit: https://grafana.com/docs/grafana/latest/variables/templates-and-variables
<b>Signature</b> <b>Signature</b>
......
docs/sources/reference/templating.md deleted 100644 → 0
+++
title = "Variables"
keywords = ["grafana", "templating", "documentation", "guide", "template", "variable"]
type = "docs"
[menu.docs]
name = "Variables"
parent = "dashboard_features"
weight = 1
+++
# Variables
Variables allows for more interactive and dynamic dashboards. Instead of hard-coding things like server, application
and sensor name in your metric queries you can use variables in their place. Variables are shown as dropdown select boxes at the top of
the dashboard. These dropdowns make it easy to change the data being displayed in your dashboard.
{{< docs-imagebox img="/img/docs/v50/variables_dashboard.png" >}}
## What is a variable?
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.
### Interpolation
Panel titles and metric queries can refer to variables using two different syntaxes:
- `$varname` Example: apps.frontend.$server.requests.count
- `[[varname]]` Example: apps.frontend.[[server]].requests.count
Why two ways? The first syntax is easier to read and write but does not allow you to use a variable in the middle of word. Use
the second syntax in expressions like `my.server[[serverNumber]].count`.
Before queries are sent to your data source the query is **interpolated**, meaning the variable is replaced with its current value. During
interpolation the variable value might be **escaped** in order to conform to the syntax of the query language and where it is used.
For example, a variable used in a regex expression in an InfluxDB or Prometheus query will be regex escaped. Read the data source specific
documentation article for details on value escaping during interpolation.
### Advanced Formatting Options
The formatting of the variable interpolation depends on the data source but there are some situations where you might want to change the default formatting. For example, the default for the MySql data source is to join multiple values as comma-separated with quotes: `'server01','server02'`. In some cases you might want to have a comma-separated string without quotes: `server01,server02`. This is now possible with the advanced formatting options.
Syntax: `${var_name:option}`
#### Glob
Formats multi-value variable into a glob (for Graphite queries).
```bash
servers = ['test1', 'test2']
String to interpolate: '${servers:glob}'
Interpolation result: '{test1,test2}'
```
### Regex
Formats multi-value variable into a regex string.
```bash
servers = ['test1.', 'test2']
String to interpolate: '${servers:regex}'
Interpolation result: '(test1\.|test2)'
```
### Pipe
Formats multi-value variable into a pipe-separated string.
```bash
servers = ['test1.', 'test2']
String to interpolate: '${servers:pipe}'
Interpolation result: 'test1.|test2'
```
### Csv
Formats multi-value variable as a comma-separated string.
```bash
servers = ['test1', 'test2']
String to interpolate: '${servers:csv}'
Interpolation result: 'test1,test2'
```
### Json
Formats multi-value variable as a comma-separated string.
```bash
servers = ['test1', 'test2']
String to interpolate: '${servers:json}'
Interpolation result: '["test1", "test2"]'
```
### Distributed
Formats multi-value variable in custom format for OpenTSDB.
```bash
servers = ['test1', 'test2']
String to interpolate: '${servers:distributed}'
Interpolation result: 'test1,servers=test2'
```
### Lucene
Formats multi-value variable in lucene format for Elasticsearch.
```bash
servers = ['test1', 'test2']
String to interpolate: '${servers:lucene}'
Interpolation result: '("test1" OR "test2")'
```
### Percentencode
Formats single and multi valued variables for use in URL parameters.
```bash
servers = ['foo()bar BAZ', 'test2']
String to interpolate: '${servers:percentencode}'
Interpolation result: 'foo%28%29bar%20BAZ%2Ctest2'
```
### Singlequote
Formats single- and multi-valued variables into a comma-separated string, escapes `'` in each value by `\'` and quotes each value with `'`.
```bash
servers = ['test1', 'test2']
String to interpolate: '${servers:singlequote}'
Interpolation result: "'test1','test2'"
```
### Doublequote
Formats single- and multi-valued variables into a comma-separated string, escapes `"` in each value by `\"` and quotes each value with `"`.
```bash
servers = ['test1', 'test2']
String to interpolate: '${servers:doublequote}'
Interpolation result: '"test1","test2"'
```
### Sqlstring
Formats single- and multi-valued variables into a comma-separated string, escapes `'` in each value by `''` and quotes each value with `'`.
```bash
servers = ["test'1", "test2"]
String to interpolate: '${servers:sqlstring}'
Interpolation result: "'test''1','test2'"
```
Test the formatting options on the [Grafana Play site](https://play.grafana.org/d/cJtIfcWiz/template-variable-formatting-options?orgId=1).
If any invalid formatting option is specified, then `glob` is the default/fallback option.
An alternative syntax (that might be deprecated in the future) is `[[var_name:option]]`.
### Variable options
A variable is presented as a dropdown select box at the top of the dashboard. It has a current value and a set of **options**. The **options**
is the set of values you can choose from.
## Adding a variable
{{< docs-imagebox img="/img/docs/v50/variables_var_list.png" max-width="800px" >}}
You add variables via Dashboard cogs menu > Templating. This opens up a list of variables and a `New` button to create a new variable.
### Basic variable options
Option | Description
------- | --------
*Name* | The name of the variable, this is the name you use when you refer to your variable in your metric queries. Must be unique and contain no white-spaces.
*Label* | The name of the dropdown for this variable.
*Hide* | Options to hide the dropdown select box.
*Type* | Defines the variable type.
### Variable types
Type | Description
------- | --------
*Query* | This variable type allows you to write a data source query that usually returns a list of metric names, tag values or keys. For example, a query that returns a list of server names, sensor ids or data centers.
*Interval* | This variable can represent time spans. Instead of hard-coding a group by time or date histogram interval, use a variable of this type.
*Data source* | This type allows you to quickly change the data source for an entire Dashboard. Useful if you have multiple instances of a data source in for example different environments.
*Custom* | Define the variable options manually using a comma separated list.
*Constant* | Define a hidden constant. Useful for metric path prefixes for dashboards you want to share. During dashboard export, constant variables will be made into an import option.
*Ad hoc filters* | Very special kind of variable that only works with some data sources, InfluxDB and Elasticsearch currently. It allows you to add key/value filters that will automatically be added to all metric queries that use the specified data source.
*Text box* | This variable type will display as a free text input field with an optional default value.
### Query options
This variable type is the most powerful and complex as it can dynamically fetch its options using a data source query.
Option | Description
------- | --------
*Data source* | The data source target for the query.
*Refresh* | Controls when to update the variable option list (values in the dropdown). **On Dashboard Load** will slow down dashboard load as the variable query needs to be completed before dashboard can be initialized. Set this only to **On Time Range Change** if your variable options query contains a time range filter or is dependent on dashboard time range.
*Query* | The data source specific query expression.
*Regex* | Regex to filter or capture specific parts of the names return by your data source query. Optional.
*Sort* | Define sort order for options in dropdown. **Disabled** means that the order of options returned by your data source query will be used.
#### Using regex to filter/modify values in the Variable dropdown
Using the Regex Query Option, you filter the list of options returned by the Variable query or modify the options returned.
Examples of filtering on the following list of options:
```text
backend_01
backend_02
backend_03
backend_04
```
##### Filter so that only the options that end with `01` or `02` are returned:
Regex:
```regex
/.*[01|02]/
```
Result:
```text
backend_01
backend_02
```
##### Filter and modify the options using a regex capture group to return part of the text:
Regex:
```regex
/.*(01|02)/
```
Result:
```text
01
02
```
#### Filter and modify - Prometheus Example
List of options:
```text
up{instance="demo.robustperception.io:9090",job="prometheus"} 1 1521630638000
up{instance="demo.robustperception.io:9093",job="alertmanager"} 1 1521630638000
up{instance="demo.robustperception.io:9100",job="node"} 1 1521630638000
```
Regex:
```regex
/.*instance="([^"]*).*/
```
Result:
```text
demo.robustperception.io:9090
demo.robustperception.io:9093
demo.robustperception.io:9100
```
### Query expressions
The query expressions are different for each data source.
- [Graphite templating queries]({{< relref "../features/datasources/graphite.md#templating" >}})
- [Elasticsearch templating queries]({{< relref "../features/datasources/elasticsearch.md#templating" >}})
- [InfluxDB templating queries]({{< relref "../features/datasources/influxdb.md#templating" >}})
- [Prometheus templating queries]({{< relref "../features/datasources/prometheus.md#templating" >}})
- [OpenTSDB templating queries]({{< relref "../features/datasources/opentsdb.md#templating" >}})
- [AzureMonitor templating queries]({{< relref "../features/datasources/azuremonitor.md#templating-with-variables-for-the-azure-monitor-service" >}})
One thing to note is that query expressions can contain references to other variables and in effect create linked variables.
Grafana will detect this and automatically refresh a variable when one of it's containing variables change.
## Selection Options
Option | Description
------- | --------
*Multi-value* | If enabled, the variable will support the selection of multiple options at the same time.
*Include All option* | Add a special `All` option whose value includes all options.
*Custom all value* | By default the `All` value will include all options in combined expression. This can become very long and can have performance problems. Many times it can be better to specify a custom all value, like a wildcard regex. To make it possible to have custom regex, globs or lucene syntax in the **Custom all value** option it is never escaped so you will have to think about what is a valid value for your data source.
### Formatting multiple values
Interpolating a variable with multiple values selected is tricky as it is not straight forward how to format the multiple values to into a string that
is valid in the given context where the variable is used. Grafana tries to solve this by allowing each data source plugin to
inform the templating interpolation engine what format to use for multiple values.
Note that the *Custom all value* option on the variable will have to be left blank for Grafana to format all values into a single string.
**Graphite**, for example, uses glob expressions. A variable with multiple values would, in this case, be interpolated as `{host1,host2,host3}` if
the current variable value was *host1*, *host2* and *host3*.
**InfluxDB and Prometheus** uses regex expressions, so the same variable
would be interpolated as `(host1|host2|host3)`. Every value would also be regex escaped if not, a value with a regex control character would
break the regex expression.
**Elasticsearch** uses lucene query syntax, so the same variable would, in this case, be formatted as `("host1" OR "host2" OR "host3")`. In this case every value
needs to be escaped so that the value can contain lucene control words and quotation marks.
#### Formatting troubles
Automatic escaping and formatting can cause problems and it can be tricky to grasp the logic is behind it.
Especially for InfluxDB and Prometheus where the use of regex syntax requires that the variable is used in regex operator context.
If you do not want Grafana to do this automatic regex escaping and formatting your only option is to disable the *Multi-value* or *Include All option*
options.
### Value groups/tags
If you have a lot of options in the dropdown for a multi-value variable. You can use this feature to group the values into selectable tags.
Option | Description
------- | --------
*Tags query* | Data source query that should return a list of tags
*Tag values query* | Data source query that should return a list of values for a specified tag key. Use `$tag` in the query to refer the currently selected tag.
{{< docs-imagebox img="/img/docs/v50/variable_dropdown_tags.png" max-width="300px" >}}
### Interval variables
Use the `Interval` type to create a variable that represents a time span (eg. `1m`,`1h`, `1d`). There is also a special `auto` option that will change depending on the current time range. You can specify how many times the current time range should be divided to calculate the current `auto` timespan.
This variable type is useful as a parameter to group by time (for InfluxDB), Date histogram interval (for Elasticsearch) or as a *summarize* function parameter (for Graphite).
Example using the template variable `myinterval` of type `Interval` in a graphite function:
```
summarize($myinterval, sum, false)
```
## Global Built-in Variables
Grafana has global built-in variables that can be used in expressions in the query editor.
### Time range variables
Grafana has two built in time range variables in `$__from` and `$__to`. They are currently always interpolated
as epoch milliseconds. These variables are only available in Grafana v6.0 and above.
### The $__interval Variable
This $__interval variable is similar to the `auto` interval variable that is described above. It can be used as a parameter to group by time (for InfluxDB, MySQL, Postgres, MSSQL), Date histogram interval (for Elasticsearch) or as a *summarize* function parameter (for Graphite).
Grafana automatically calculates an interval that can be used to group by time in queries. When there are more data points than can be shown on a graph then queries can be made more efficient by grouping by a larger interval. It is more efficient to group by 1 day than by 10s when looking at 3 months of data and the graph will look the same and the query will be faster. The `$__interval` is calculated using the time range and the width of the graph (the number of pixels).
Approximate Calculation: `(from - to) / resolution`
For example, when the time range is 1 hour and the graph is full screen, then the interval might be calculated to `2m` - points are grouped in 2 minute intervals. If the time range is 6 months and the graph is full screen, then the interval might be `1d` (1 day) - points are grouped by day.
In the InfluxDB data source, the legacy variable `$interval` is the same variable. `$__interval` should be used instead.
The InfluxDB and Elasticsearch data sources have `Group by time interval` fields that are used to hard code the interval or to set the minimum limit for the `$__interval` variable (by using the `>` syntax -> `>10m`).
### The $__interval_ms Variable
This variable is the `$__interval` variable in milliseconds (and not a time interval formatted string). For example, if the `$__interval` is `20m` then the `$__interval_ms` is `1200000`.
### The $timeFilter or $__timeFilter Variable
The `$timeFilter` variable returns the currently selected time range as an expression. For example, the time range interval `Last 7 days` expression is `time > now() - 7d`.
This is used in the WHERE clause for the InfluxDB data source. Grafana adds it automatically to InfluxDB queries when in Query Editor Mode. It has to be added manually in Text Editor Mode: `WHERE $timeFilter`.
The `$__timeFilter` is used in the MySQL data source.
### The $__name Variable
This variable is only available in the Singlestat panel and can be used in the prefix or suffix fields on the Options tab. The variable will be replaced with the series name or alias.
### The $__range Variable
> Only available in Grafana v5.3+
Currently only supported for Prometheus data sources. This variable represents the range for the current dashboard. It is calculated by `to - from`. It has a millisecond and a second representation called `$__range_ms` and `$__range_s`.
### The $__dashboard Variable
> Only available in Grafana v6.7+
This variable is the UID of the current dashboard.
`${__dashboard.name}` is the name of the current dashboard.
### The $__org Variable
> Only available in Grafana v6.7+
This variable is the ID of the current organization.
`${__org.name}` is the name of the current organization.
## Repeating Panels
Template variables can be very useful to dynamically change your queries across a whole dashboard. If you want
Grafana to dynamically create new panels or rows based on what values you have selected you can use the *Repeat* feature.
If you have a variable with `Multi-value` or `Include all value` options enabled you can choose one panel and have Grafana repeat that panel
for every selected value. You find the *Repeat* feature under the *General tab* in panel edit mode.
The `direction` controls how the panels will be arranged.
By choosing `horizontal` the panels will be arranged side-by-side. Grafana will automatically adjust the width
of each repeated panel so that the whole row is filled. Currently, you cannot mix other panels on a row with a repeated
panel.
Set `Max per row` to tell grafana how many panels per row you want at most. It defaults to *4* if you don't set anything.
By choosing `vertical` the panels will be arranged from top to bottom in a column. The width of the repeated panels will be the same as of the first panel (the original template) being repeated.
Only make changes to the first panel (the original template). To have the changes take effect on all panels you need to trigger a dynamic dashboard re-build.
You can do this by either changing the variable value (that is the basis for the repeat) or reload the dashboard.
> **Note:** Repeating panels require variables to have one or more items selected; you cannot repeat a panel zero times to hide it.
## Repeating Rows
As seen above with the *Panels* you can also repeat *Rows* if you have variables set with `Multi-value` or
`Include all value` selection option.
To enable this feature you need to first add a new *Row* using the *Add Panel* menu. Then by hovering the row title and
clicking on the cog button, you will access the `Row Options` configuration panel. You can then select the variable
you want to repeat the row for.
It may be a good idea to use a variable in the row title as well.
Example: [Repeated Rows Dashboard](https://play.grafana.org/dashboard/db/repeated-rows)
## URL state
Variable values are always synced to the URL using the syntax `var-<varname>=value`.
## Examples
- [Graphite Templated Dashboard](https://play.grafana.org/dashboard/db/graphite-templated-nested)
- [Elasticsearch Templated Dashboard](https://play.grafana.org/dashboard/db/elasticsearch-templated)
- [InfluxDB Templated Dashboard](https://play.grafana.org/dashboard/db/influxdb-templated)
docs/sources/variables/_index.md 0 → 100644
+++
title = "Templates and variables"
type = "docs"
[menu.docs]
identifier = "variables"
weight = 500
+++
docs/sources/variables/advanced-variable-format-options.md 0 → 100644
+++
title = "Advanced variable format options"
keywords = ["grafana", "templating", "documentation", "guide", "template", "variable"]
type = "docs"
[menu.docs]
name = "advanced-variable-format-options"
parent = "variables"
weight = 300
+++
# Advanced variable format options
The formatting of the variable interpolation depends on the data source, but there are some situations where you might want to change the default formatting.
For example, the default for the MySql data source is to join multiple values as comma-separated with quotes: `'server01','server02'`. In some cases, you might want to have a comma-separated string without quotes: `server01,server02`. You can make that happen with advanced variable formatting options listed below.
## General syntax
Syntax: `${var_name:option}`
Test the formatting options on the [Grafana Play site](https://play.grafana.org/d/cJtIfcWiz/template-variable-formatting-options?orgId=1).
If any invalid formatting option is specified, then `glob` is the default/fallback option.
An alternative syntax (that might be deprecated in the future) is `[[var_name:option]]`.
## CSV
Formats multi-value variable as a comma-separated string.
```bash
servers = ['test1', 'test2']
String to interpolate: '${servers:csv}'
Interpolation result: 'test1,test2'
```
## Distributed - OpenTSDB
Formats multi-value variable in custom format for OpenTSDB.
```bash
servers = ['test1', 'test2']
String to interpolate: '${servers:distributed}'
Interpolation result: 'test1,servers=test2'
```
## Doublequote
Formats single- and multi-valued variables into a comma-separated string, escapes `"` in each value by `\"` and quotes each value with `"`.
```bash
servers = ['test1', 'test2']
String to interpolate: '${servers:doublequote}'
Interpolation result: '"test1","test2"'
```
## Glob - Graphite
Formats multi-value variable into a glob (for Graphite queries).
```bash
servers = ['test1', 'test2']
String to interpolate: '${servers:glob}'
Interpolation result: '{test1,test2}'
```
## JSON
Formats multi-value variable as a comma-separated string.
```bash
servers = ['test1', 'test2']
String to interpolate: '${servers:json}'
Interpolation result: '["test1", "test2"]'
```
## Lucene - Elasticsearch
Formats multi-value variable in Lucene format for Elasticsearch.
```bash
servers = ['test1', 'test2']
String to interpolate: '${servers:lucene}'
Interpolation result: '("test1" OR "test2")'
```
## Percentencode
Formats single and multi valued variables for use in URL parameters.
```bash
servers = ['foo()bar BAZ', 'test2']
String to interpolate: '${servers:percentencode}'
Interpolation result: 'foo%28%29bar%20BAZ%2Ctest2'
```
## Pipe
Formats multi-value variable into a pipe-separated string.
```bash
servers = ['test1.', 'test2']
String to interpolate: '${servers:pipe}'
Interpolation result: 'test1.|test2'
```
## Regex
Formats multi-value variable into a regex string.
```bash
servers = ['test1.', 'test2']
String to interpolate: '${servers:regex}'
Interpolation result: '(test1\.|test2)'
```
## Singlequote
Formats single- and multi-valued variables into a comma-separated string, escapes `'` in each value by `\'` and quotes each value with `'`.
```bash
servers = ['test1', 'test2']
String to interpolate: '${servers:singlequote}'
Interpolation result: "'test1','test2'"
```
## Sqlstring
Formats single- and multi-valued variables into a comma-separated string, escapes `'` in each value by `''` and quotes each value with `'`.
```bash
servers = ["test'1", "test2"]
String to interpolate: '${servers:sqlstring}'
Interpolation result: "'test''1','test2'"
```
docs/sources/variables/global-variables.md 0 → 100644
+++
title = "Global variables"
keywords = ["grafana", "templating", "documentation", "guide", "template", "variable", "global", "standard"]
type = "docs"
[menu.docs]
name = "global-variables"
parent = "variables"
weight = 200
+++
# Global variables
Grafana has global built-in variables that can be used in expressions in the query editor. This topic lists them in alphabetical order and defines them.
## $__dashboard
> Only available in Grafana v6.7+
This variable is the UID of the current dashboard.
`${__dashboard.name}` is the name of the current dashboard.
## $__from and $__to
> Only available in Grafana v6.0+
Grafana has two built in time range variables: `$__from` and `$__to`. They are currently always interpolated as epoch milliseconds.
## $__interval
The `$__interval` variable can be used as a parameter to group by time (for InfluxDB, MySQL, Postgres, MSSQL), Date histogram interval (for Elasticsearch) or as a *summarize* function parameter (for Graphite).
Grafana automatically calculates an interval that can be used to group by time in queries. When there are more data points than can be shown on a graph then queries can be made more efficient by grouping by a larger interval. It is more efficient to group by 1 day than by 10s when looking at 3 months of data and the graph will look the same and the query will be faster. The `$__interval` is calculated using the time range and the width of the graph (the number of pixels).
Approximate Calculation: `(from - to) / resolution`
For example, when the time range is 1 hour and the graph is full screen, then the interval might be calculated to `2m` - points are grouped in 2 minute intervals. If the time range is 6 months and the graph is full screen, then the interval might be `1d` (1 day) - points are grouped by day.
In the InfluxDB data source, the legacy variable `$interval` is the same variable. `$__interval` should be used instead.
The InfluxDB and Elasticsearch data sources have `Group by time interval` fields that are used to hard code the interval or to set the minimum limit for the `$__interval` variable (by using the `>` syntax -> `>10m`).
## $__interval_ms
This variable is the `$__interval` variable in milliseconds, not a time interval formatted string. For example, if the `$__interval` is `20m` then the `$__interval_ms` is `1200000`.
## $__name
This variable is only available in the Singlestat panel and can be used in the prefix or suffix fields on the Options tab. The variable will be replaced with the series name or alias.
## $__org
> Only available in Grafana v6.7+
This variable is the ID of the current organization.
`${__org.name}` is the name of the current organization.
## $__range
> Only available in Grafana v5.3+
Currently only supported for Prometheus data sources. This variable represents the range for the current dashboard. It is calculated by `to - from`. It has a millisecond and a second representation called `$__range_ms` and `$__range_s`.
## $timeFilter or $__timeFilter
The `$timeFilter` variable returns the currently selected time range as an expression. For example, the time range interval `Last 7 days` expression is `time > now() - 7d`.
This is used in several places, including:
* The WHERE clause for the InfluxDB data source. Grafana adds it automatically to InfluxDB queries when in Query Editor Mode. It has to be added manually in Text Editor Mode: `WHERE $timeFilter`.
* Log Analytics queries in the Azure Monitor data source.
* SQL queries in MySQL, Postgres, and MSSQL
* The `$__timeFilter` variable is used in the MySQL data source.
\ No newline at end of file
docs/sources/variables/repeat-panels-or-rows.md 0 → 100644
+++
title = "Variables"
keywords = ["grafana", "templating", "documentation", "guide", "template", "variable", "repeat"]
type = "docs"
[menu.docs]
name = "Repeat panels or rows"
parent = "variables"
weight = 400
+++
# Repeat panels or rows
Grafana lets you create dynamic dashboards using _template variables_. Any variables in your queries expands to the current value of the variable before the query is sent to the database. Variables let you reuse a single dashboard for all your services.
Template variables can be very useful to dynamically change your queries across a whole dashboard. If you want
Grafana to dynamically create new panels or rows based on what values you have selected you can use the *Repeat* feature.
## Repeating panels
If you have a variable with `Multi-value` or `Include all value` options enabled you can choose one panel and have Grafana repeat that panel
for every selected value. You find the *Repeat* feature under the *General tab* in panel edit mode.
The `direction` controls how the panels will be arranged.
By choosing `horizontal` the panels will be arranged side-by-side. Grafana will automatically adjust the width
of each repeated panel so that the whole row is filled. Currently, you cannot mix other panels on a row with a repeated
panel.
Set `Max per row` to tell grafana how many panels per row you want at most. It defaults to *4* if you don't set anything.
By choosing `vertical` the panels will be arranged from top to bottom in a column. The width of the repeated panels will be the same as of the first panel (the original template) being repeated.
Only make changes to the first panel (the original template). To have the changes take effect on all panels you need to trigger a dynamic dashboard re-build.
You can do this by either changing the variable value (that is the basis for the repeat) or reload the dashboard.
> **Note:** Repeating panels require variables to have one or more items selected; you cannot repeat a panel zero times to hide it.
## Repeating rows
As seen above with the panels you can also repeat rows if you have variables set with `Multi-value` or
`Include all value` selection option.
To enable this feature you need to first add a new *Row* using the *Add Panel* menu. Then by hovering the row title and
clicking on the cog button, you will access the `Row Options` configuration panel. You can then select the variable
you want to repeat the row for.
It may be a good idea to use a variable in the row title as well.
Example: [Repeated Rows Dashboard](https://play.grafana.org/dashboard/db/repeated-rows)
\ No newline at end of file
docs/sources/variables/templates-and-variables.md 0 → 100644
+++
title = "Variables"
keywords = ["grafana", "templating", "documentation", "guide", "template", "variable"]
type = "docs"
aliases = ["/docs/grafana/latest/reference/templating"]
[menu.docs]
name = "Templates and variables"
parent = "variables"
weight = 100
+++
# Templates and variables
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 allows 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.
{{< docs-imagebox img="/img/docs/v50/variables_dashboard.png" >}}
These can be especially useful for administrators who want to allow Grafana viewers to quickly adjust visualizations but do not want to give 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`.
## Variable syntax
Panel titles and metric queries can refer to variables using two different syntaxes:
- `$varname`
This syntax is easy to read, but it does not allow you to use a variable in the middle of a word.
**Example:** apps.frontend.$server.requests.count
- `[[varname]]`
**Note:** This syntax might be deprecated in the future.
Example: apps.frontend.[[server]].requests.count
Before queries are sent to your data source the query is _interpolated_, meaning the variable is replaced with its current value. During
interpolation the variable value might be _escaped_ in order to conform to the syntax of the query language and where it is used.
For example, a variable used in a regex expression in an InfluxDB or Prometheus query will be regex escaped. Read the data source specific
documentation topic for details on value escaping during interpolation.
For advanced syntax to override data source default formatting, refer to [Advanced variable format options]({{< relref "advanced-variable-format-options.md" >}}).
## Examples of templates and variables
To see variable and template examples, go to any of the dashboards listed below.
- [Elasticsearch Templated dashboard](https://play.grafana.org/dashboard/db/elasticsearch-templated)
- [Graphite Templated Nested dashboard](https://play.grafana.org/dashboard/db/graphite-templated-nested)
- [InfluxDB Templated dashboard](https://play.grafana.org/dashboard/db/influxdb-templated)
Variables are listed in dropdown 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.
Templates are in the query portion of panels. Queries with text that starts with `$` are templates. Not all panels will have template queries.
## Variable types
Grafana also has global built-in variables that can be used in expressions in the query editor. Refer to [Global variables]({{< relref "global-variables" >}}) for more information.
You can also define the following types of variables in Grafana.
Type | Description
------- | --------
*Query* | This variable type allows you to write a data source query that usually returns a list of metric names, tag values or keys. For example, a query that returns a list of server names, sensor ids or data centers.
*Interval* | This variable can represent time spans. Instead of hard-coding a group by time or date histogram interval, use a variable of this type.
*Data source* | This type allows you to quickly change the data source for an entire Dashboard. Useful if you have multiple instances of a data source in for example different environments.
*Custom* | Define the variable options manually using a comma separated list.
*Constant* | Define a hidden constant. Useful for metric path prefixes for dashboards you want to share. During dashboard export, constant variables will be made into an import option.
*Ad hoc filters* | Very special kind of variable that only works with some data sources, InfluxDB, Prometheus, and Elasticsearch currently. It allows you to add key/value filters that will automatically be added to all metric queries that use the specified data source.
*Text box* | This variable type will display as a free text input field with an optional default value.
## Adding a variable
{{< docs-imagebox img="/img/docs/v50/variables_var_list.png" max-width="800px" >}}
You add variables via Dashboard cogs menu > Templating. This opens up a list of variables and a `New` button to create a new variable.
### Basic variable options
Option | Description
------- | --------
*Name* | The name of the variable, this is the name you use when you refer to your variable in your metric queries. Must be unique and contain no white-spaces.
*Label* | The name of the dropdown for this variable.
*Hide* | Options to hide the dropdown select box.
*Type* | Defines the variable type.
### Query options
This variable type is the most powerful and complex as it can dynamically fetch its options using a data source query.
Option | Description
------- | --------
*Data source* | The data source target for the query.
*Refresh* | Controls when to update the variable option list (values in the dropdown). **On Dashboard Load** will slow down dashboard load as the variable query needs to be completed before dashboard can be initialized. Set this only to **On Time Range Change** if your variable options query contains a time range filter or is dependent on dashboard time range.
*Query* | The data source specific query expression.
*Regex* | Regex to filter or capture specific parts of the names return by your data source query. Optional.
*Sort* | Define sort order for options in dropdown. **Disabled** means that the order of options returned by your data source query will be used.
#### Using regex to filter/modify values in the Variable dropdown
Using the Regex Query Option, you filter the list of options returned by the Variable query or modify the options returned.
Examples of filtering on the following list of options:
```text
backend_01
backend_02
backend_03
backend_04
```
##### Filter so that only the options that end with `01` or `02` are returned:
Regex:
```regex
/.*[01|02]/
```
Result:
```text
backend_01
backend_02
```
##### Filter and modify the options using a regex capture group to return part of the text:
Regex:
```regex
/.*(01|02)/
```
Result:
```text
01
02
```
#### Filter and modify - Prometheus Example
List of options:
```text
up{instance="demo.robustperception.io:9090",job="prometheus"} 1 1521630638000
up{instance="demo.robustperception.io:9093",job="alertmanager"} 1 1521630638000
up{instance="demo.robustperception.io:9100",job="node"} 1 1521630638000
```
Regex:
```regex
/.*instance="([^"]*).*/
```
Result:
```text
demo.robustperception.io:9090
demo.robustperception.io:9093
demo.robustperception.io:9100
```
### Query expressions
The query expressions are different for each data source.
- [Graphite templating queries]({{< relref "../features/datasources/graphite.md#templating" >}})
- [Elasticsearch templating queries]({{< relref "../features/datasources/elasticsearch.md#templating" >}})
- [InfluxDB templating queries]({{< relref "../features/datasources/influxdb.md#templating" >}})
- [Prometheus templating queries]({{< relref "../features/datasources/prometheus.md#templating" >}})
- [OpenTSDB templating queries]({{< relref "../features/datasources/opentsdb.md#templating" >}})
- [AzureMonitor templating queries]({{< relref "../features/datasources/azuremonitor.md#templating-with-variables-for-the-azure-monitor-service" >}})
One thing to note is that query expressions can contain references to other variables and in effect create linked variables.
Grafana will detect this and automatically refresh a variable when one of it's containing variables change.
## Selection options
Option | Description
------- | --------
*Multi-value* | If enabled, the variable will support the selection of multiple options at the same time.
*Include All option* | Add a special `All` option whose value includes all options.
*Custom all value* | By default the `All` value will include all options in combined expression. This can become very long and can have performance problems. Many times it can be better to specify a custom all value, like a wildcard regex. To make it possible to have custom regex, globs or lucene syntax in the **Custom all value** option it is never escaped so you will have to think about what is a valid value for your data source.
### Formatting multiple values
Interpolating a variable with multiple values selected is tricky as it is not straight forward how to format the multiple values into a string that
is valid in the given context where the variable is used. Grafana tries to solve this by allowing each data source plugin to
inform the templating interpolation engine what format to use for multiple values.
Note that the *Custom all value* option on the variable will have to be left blank for Grafana to format all values into a single string.
**Graphite**, for example, uses glob expressions. A variable with multiple values would, in this case, be interpolated as `{host1,host2,host3}` if
the current variable value was *host1*, *host2* and *host3*.
**InfluxDB and Prometheus** uses regex expressions, so the same variable
would be interpolated as `(host1|host2|host3)`. Every value would also be regex escaped if not, a value with a regex control character would
break the regex expression.
**Elasticsearch** uses lucene query syntax, so the same variable would, in this case, be formatted as `("host1" OR "host2" OR "host3")`. In this case every value
needs to be escaped so that the value can contain lucene control words and quotation marks.
#### Formatting troubles
Automatic escaping and formatting can cause problems and it can be tricky to grasp the logic is behind it.
Especially for InfluxDB and Prometheus where the use of regex syntax requires that the variable is used in regex operator context.
If you do not want Grafana to do this automatic regex escaping and formatting your only option is to disable the *Multi-value* or *Include All option*
options.
### Value groups/tags
If you have a lot of options in the dropdown for a multi-value variable. You can use this feature to group the values into selectable tags.
Option | Description
------- | --------
*Tags query* | Data source query that should return a list of tags
*Tag values query* | Data source query that should return a list of values for a specified tag key. Use `$tag` in the query to refer the currently selected tag.
{{< docs-imagebox img="/img/docs/v50/variable_dropdown_tags.png" max-width="300px" >}}
### Interval variables
Use the `Interval` type to create a variable that represents a time span (eg. `1m`,`1h`, `1d`). There is also a special `auto` option that will change depending on the current time range. You can specify how many times the current time range should be divided to calculate the current `auto` timespan.
This variable type is useful as a parameter to group by time (for InfluxDB), Date histogram interval (for Elasticsearch) or as a *summarize* function parameter (for Graphite).
Example using the template variable `myinterval` of type `Interval` in a graphite function:
```
summarize($myinterval, sum, false)
```
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment