Skip to content

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

Docs: Organize variables (#26738) 

* Moved files to folder and updated links

* fixed links

* Update _index.md

* Update templates-and-variables.md
parent 0e3b4e8c
Showing with 90 additions and 78 deletions
docs/sources/features/datasources/prometheus.md
......@@ -89,7 +89,7 @@ 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
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
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/variable-types/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.
......
docs/sources/linking/dashboard-links.md
......@@ -10,7 +10,7 @@ weight = 200
# Dashboard links
When you create a dashboard link, you can include the time range and current template variables to directly jump to the same context in another dashboard. This way, you don’t have to worry whether the person you send the link to is looking at the right data. For more information about specifying links, refer to [URL variables]({{< relref "../variables/url-variables.md" >}}).
When you create a dashboard link, you can include the time range and current template variables to directly jump to the same context in another dashboard. This way, you don’t have to worry whether the person you send the link to is looking at the right data. For more information about specifying links, refer to [URL variables]({{< relref "../variables/variable-types/url-variables.md" >}}).
Dashboard links can also be used as shortcuts to external systems, such as submitting [a GitHub issue with the current dashboard name](https://github.com/grafana/grafana/issues/new?title=Dashboard%3A%20HTTP%20Requests).
......
docs/sources/linking/data-links.md
......@@ -22,7 +22,7 @@ Stat, Gauge, or Bar Gauge you can click anywhere on the visualization to open th
1. Enter a **Title**. **Title** is a human-readable label for the link that will be displayed in the UI.
1. Enter the **URL** you want to link to.
You can even add one of the template variables defined in the dashboard. Press Ctrl+Space or Cmd+Space and click in the **URL** field to see the available variables. By adding template variables to your panel link, the link sends the user to the right context, with the relevant variables already set. For more information, refer to [URL variables]({{< relref "../variables/url-variables.md" >}}).
You can even add one of the template variables defined in the dashboard. Press Ctrl+Space or Cmd+Space and click in the **URL** field to see the available variables. By adding template variables to your panel link, the link sends the user to the right context, with the relevant variables already set. For more information, refer to [URL variables]({{< relref "../variables/variable-types/url-variables.md" >}}).
1. If you want the link to open in a new tab, then select **Open in a new tab**.
1. Click **Save** to save changes and close the window.
......
docs/sources/menu.yaml
......@@ -255,28 +255,33 @@
name: Overview
- link: /variables/variable-examples/
name: Variable examples
- link: /variables/add-query-variable/
name: Add query variable
- link: /variables/add-custom-variable/
name: Add custom variable
- link: /variables/add-text-box-variable/
name: Add text box variable
- link: /variables/add-constant-variable/
name: Add constant variable
- link: /variables/add-data-source-variable/
name: Add data source variable
- link: /variables/add-interval-variable/
name: Add interval variable
- link: /variables/add-ad-hoc-filters/
name: Add ad hoc filters
- name: Variable types
link: /variables/variable-types/
children:
- link: /variables/variable-types/add-query-variable/
name: Add query variable
- link: /variables/variable-types/add-custom-variable/
name: Add custom variable
- link: /variables/variable-types/add-text-box-variable/
name: Add text box variable
- link: /variables/variable-types/add-constant-variable/
name: Add constant variable
- link: /variables/variable-types/add-data-source-variable/
name: Add data source variable
- link: /variables/variable-types/add-interval-variable/
name: Add interval variable
- link: /variables/variable-types/add-ad-hoc-filters/
name: Add ad hoc filters
- link: /variables/variable-types/chained-variables/
name: Chained variables
- link: /variables/variable-types/global-variables/
name: Global variables
- link: /variables/variable-types/url-variables/
name: URL variables
- name: Selection options
link: /variables/variable-selection-options/
- name: Value groups/tags
link: /variables/variable-value-tags/
- link: /variables/global-variables/
name: Global variables
- link: /variables/url-variables/
name: URL variables
- link: /variables/advanced-variable-format-options/
name: Advanced variable formats
- link: /variables/formatting-multi-value-variables/
......@@ -285,8 +290,6 @@
name: Filter variables with regex
- link: /variables/repeat-panels-or-rows/
name: Repeat panels or rows
- link: /variables/chained-variables/
name: Chained variables
- name: What's new in Grafana
link: /whatsnew/
children:
......
docs/sources/panels/add-a-panel.md
......@@ -25,7 +25,7 @@ Grafana creates an empty graph panel with your default data source selected.
## 2. Edit panel settings
While not required, we recommend that you add a helpful title and description to your panel. You can use [variables you have defined]({{< relref "../variables/templates-and-variables.md" >}}) in either field, but not [global variables]({{< relref "../variables/global-variables.md" >}}).
While not required, we recommend that you add a helpful title and description to your panel. You can use [variables you have defined]({{< relref "../variables/templates-and-variables.md" >}}) in either field, but not [global variables]({{< relref "../variables/variable-types/global-variables.md" >}}).
![](/img/docs/panels/panel-settings-7-0.png)
......
docs/sources/panels/queries.md
......@@ -94,7 +94,7 @@ Panel data source query options:
This automatic interval is calculated based on the width of the graph. If the user zooms out a lot then the interval becomes greater, resulting in a more coarse grained aggregation whereas if the user zooms in then the interval decreases resulting in a more fine grained aggregation.
For more information, refer to [Global variables]({{< relref "../variables/global-variables.md" >}}).
For more information, refer to [Global variables]({{< relref "../variables/variable-types/global-variables.md" >}}).
- **Relative time -** You can override the relative time range for individual panels, causing them to be different than what is selected in the dashboard time picker in the top right corner of the dashboard. This allows you to show metrics from different time periods or days on the same dashboard.
......
docs/sources/variables/templates-and-variables.md
......@@ -38,13 +38,9 @@ Variable values are always synced to the URL using the syntax `var-<varname>=val
## Examples of templates and variables
To see variable and template examples, go to any of the dashboards listed below.
To see variable and template examples, go to any of the dashboards listed in [Variable examples]({{< relref "variable-examples.md" >}}).
- [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.
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.
......@@ -70,41 +66,20 @@ For advanced syntax to override data source default formatting, refer to [Advanc
## Variable types
Grafana 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.
### Query
Write a data source query that might return a list of metric names, tag values, keys, server names, sensor IDs, data centers, and so on.
For instructions, refer to [Add a query variable]({{< relref "add-query-variable.md" >}}).
Variable queries can contain other variables. For more information, refer to [Chained variables]({{< relref "chained-variables.md" >}}).
### Custom
Define the variable options manually using a comma-separated list. For instructions, refer to [Add a custom variable]({{< relref "add-custom-variable.md" >}}).
### Text box
Display a free text input field with an optional default value. For instructions, refer to [Add a text box variable]({{< relref "add-text-box-variable.md" >}}).
### Constant
Define a hidden constant. For instructions, refer to [Add a constant variable]({{< relref "add-constant-variable.md" >}}).
### Data source
Quickly change the data source for an entire dashboard. For instructions, refer to [Add a data source variable]({{< relref "add-data-source-variable.md" >}}).
### Interval
Interval variables represent time spans. Instead of hard-coding a group by time or date histogram interval, use an interval variable. For instructions, refer to [Add an interval variable]({{< relref "add-interval-variable.md" >}}).
### Ad hoc filters
Add key/value filters that are automatically added to all metric queries that use the specified data source. Ad hoc filter variables only work with InfluxDB, Prometheus, and Elasticsearch data sources. For instructions, refer to [Add ad hoc filters]({{< relref "add-ad-hoc-filters.md" >}}).
Grafana uses the following types of variables.
| Variable type | Description |
|:---|:---|
| Query | Query-generated list of values such as metric names, server names, sensor IDs, data centers, and so on. [Add a query variable]({{< relref "variable-types/add-query-variable.md" >}}). |
| Custom | Define the variable options manually using a comma-separated list. [Add a custom variable]({{< relref "variable-types/add-custom-variable.md" >}}). |
| Text box | Display a free text input field with an optional default value. [Add a text box variable]({{< relref "variable-types/add-text-box-variable.md" >}}). |
| Constant | Define a hidden constant. [Add a constant variable]({{< relref "variable-types/add-constant-variable.md" >}}). |
| Data source | Quickly change the data source for an entire dashboard. [Add a data source variable]({{< relref "variable-types/add-data-source-variable.md" >}}). |
| Interval | Interval variables represent time spans. [Add an interval variable]({{< relref "variable-types/add-interval-variable.md" >}}). |
| Ad hoc filters | Key/value filters that are automatically added to all metric queries for a data source (InfluxDB, Prometheus, and Elasticsearch only). [Add ad hoc filters]({{< relref "variable-types/add-ad-hoc-filters.md" >}}). |
| Global variables | Built-in variables that can be used in expressions in the query editor. Refer to [Global variables]({{< relref "variable-types/global-variables" >}}). |
| Chained variables | Variable queries can contain other variables. Refer to [Chained variables]({{< relref "variable-types/chained-variables.md" >}}). |
| URL variables | You can use variables in data links to link to specific portions of your visualizations. Refer to [Data links]({{< relref "../linking/data-links.md" >}}). |
## Variable best practices
......
docs/sources/variables/variable-types/_index.md 0 → 100644
+++
title = "Variables types"
type = "docs"
[menu.docs]
weight = 300
+++
# Variables types
Grafana uses several types of variables.
| Variable type | Description |
|:---|:---|
| Query | Query-generated list of values such as metric names, server names, sensor IDs, data centers, and so on. [Add a query variable]({{< relref "add-query-variable.md" >}}). |
| Custom | Define the variable options manually using a comma-separated list. [Add a custom variable]({{< relref "add-custom-variable.md" >}}). |
| Text box | Display a free text input field with an optional default value. [Add a text box variable]({{< relref "add-text-box-variable.md" >}}). |
| Constant | Define a hidden constant. [Add a constant variable]({{< relref "add-constant-variable.md" >}}). |
| Data source | Quickly change the data source for an entire dashboard. [Add a data source variable]({{< relref "add-data-source-variable.md" >}}). |
| Interval | Interval variables represent time spans. [Add an interval variable]({{< relref "add-interval-variable.md" >}}). |
| Ad hoc filters | Key/value filters that are automatically added to all metric queries for a data source (InfluxDB, Prometheus, and Elasticsearch only). [Add ad hoc filters]({{< relref "add-ad-hoc-filters.md" >}}). |
| Global variables | Built-in variables that can be used in expressions in the query editor. Refer to [Global variables]({{< relref "global-variables" >}}). |
| Chained variables | Variable queries can contain other variables. Refer to [Chained variables]({{< relref "chained-variables.md" >}}). |
| URL variables | You can use variables in data links to link to specific portions of your visualizations. Refer to [Data links]({{< relref "../../linking/data-links.md" >}}). |
\ No newline at end of file
docs/sources/variables/add-ad-hoc-filters.md → docs/sources/variables/variable-types/add-ad-hoc-filters.md
+++
title = "Add ad hoc filters"
type = "docs"
aliases = ["/docs/grafana/latest/variables/add-ad-hoc-filters.md"]
[menu.docs]
weight = 500
+++
......@@ -25,7 +26,7 @@ _Ad hoc filters_ allow you to add key/value filters that are automatically added
## Enter Options
1. In the **Data source** list, select the target data source. For more information about data sources, refer to [Add a data source]({{< relref "../features/datasources/add-a-data-source.md" >}}).
1. In the **Data source** list, select the target data source. For more information about data sources, refer to [Add a data source]({{< relref "../../features/datasources/add-a-data-source.md" >}}).
1. Click **Add** to add the variable to the dashboard.
## Create ad hoc filters
......
docs/sources/variables/add-constant-variable.md → docs/sources/variables/variable-types/add-constant-variable.md
+++
title = "Add a constant variable"
type = "docs"
aliases = ["/docs/grafana/latest/variables/add-constant-variable.md"]
[menu.docs]
weight = 500
+++
......@@ -27,6 +28,6 @@ Constant variables are useful when you have complex values that you need to incl
## Enter Constant options
1. In the **Value** field, enter the variable value. You can enter letters, numbers, and symbols. You can even use wildcards if you use [raw format]({{< relref "advanced-variable-format-options.md#raw" >}}).
1. In the **Value** field, enter the variable value. You can enter letters, numbers, and symbols. You can even use wildcards if you use [raw format]({{< relref "../advanced-variable-format-options.md#raw" >}}).
1. In **Preview of values**, Grafana displays the current variable value. Review it to ensure it matches what you expect.
1. Click **Add** to add the variable to the dashboard.
docs/sources/variables/add-custom-variable.md → docs/sources/variables/variable-types/add-custom-variable.md
+++
title = "Add a custom variable"
type = "docs"
aliases = ["/docs/grafana/latest/variables/add-custom-variable.md"]
[menu.docs]
weight = 500
+++
......@@ -9,7 +10,7 @@ weight = 500
Use a _custom_ variable for values that do not change. This might be numbers, strings, or even other variables.
For example, if you have server names or region names that never change, then you might want to create them as custom variables rather than query variables. Because they do not change, you might use them in [chained variables](chained-variables.md) rather than other query variables. That would reduce the number of queries Grafana must send when chained variables are updated.
For example, if you have server names or region names that never change, then you might want to create them as custom variables rather than query variables. Because they do not change, you might use them in [chained variables]({{< relref "chained-variables.md" >}}) rather than other query variables. That would reduce the number of queries Grafana must send when chained variables are updated.
## Enter General options
......@@ -26,6 +27,6 @@ For example, if you have server names or region names that never change, then yo
## Enter Custom Options
1. In the **Values separated by comma** list, enter the values for this variable in a comma-separated list. You can include numbers, strings, or other variables.
1. (optional) Enter [Selection Options]({{< relref "variable-selection-options.md" >}}).
1. (optional) Enter [Selection Options]({{< relref "../variable-selection-options.md" >}}).
1. In **Preview of values**, Grafana displays a list of the current variable values. Review them to ensure they match what you expect.
1. Click **Add** to add the variable to the dashboard.
docs/sources/variables/add-data-source-variable.md → docs/sources/variables/variable-types/add-data-source-variable.md
+++
title = "Add a data source variable"
type = "docs"
aliases = ["/docs/grafana/latest/variables/add-data-source-variable.md"]
[menu.docs]
weight = 500
+++
......@@ -23,8 +24,8 @@ _Data source_ variables allow you to quickly change the data source for an entir
## Enter Data source options
1. In the **Type** list, select the target data source for the variable. For more information about data sources, refer to [Add a data source]({{< relref "../features/datasources/add-a-data-source.md" >}}).
1. In the **Type** list, select the target data source for the variable. For more information about data sources, refer to [Add a data source]({{< relref "../../features/datasources/add-a-data-source.md" >}}).
1. (optional) In **Instance name filter**, enter a regex filter for which data source instances to choose from in the variable value drop-down list. Leave this field empty to display all instances.
1. (optional) Enter [Selection Options]({{< relref "variable-selection-options.md" >}}).
1. (optional) Enter [Selection Options]({{< relref "../variable-selection-options.md" >}}).
1. In **Preview of values**, Grafana displays a list of the current variable values. Review them to ensure they match what you expect.
1. Click **Add** to add the variable to the dashboard.
docs/sources/variables/add-interval-variable.md → docs/sources/variables/variable-types/add-interval-variable.md
+++
title = "Add an interval variable"
type = "docs"
aliases = ["/docs/grafana/latest/variables/add-interval-variable.md"]
[menu.docs]
weight = 500
+++
......
docs/sources/variables/add-query-variable.md → docs/sources/variables/variable-types/add-query-variable.md
+++
title = "Add a query variable"
type = "docs"
aliases = ["/docs/grafana/latest/variables/add-query-variable.md"]
[menu.docs]
weight = 500
+++
......@@ -13,7 +14,7 @@ Query expressions can contain references to other variables and in effect create
## Query expressions
Query expressions are different for each data source. For more information, refer to the documentation for your [data source]({{< relref "../features/datasources/_index.md" >}}).
Query expressions are different for each data source. For more information, refer to the documentation for your [data source]({{< relref "../../features/datasources/_index.md" >}}).
## Enter General options
......@@ -29,7 +30,7 @@ Query expressions are different for each data source. For more information, refe
## Enter Query Options
1. In the **Data source** list, select the target data source for the query. For more information about data sources, refer to [Add a data source]({{< relref "../features/datasources/add-a-data-source.md" >}}).
1. In the **Data source** list, select the target data source for the query. For more information about data sources, refer to [Add a data source]({{< relref "../../features/datasources/add-a-data-source.md" >}}).
1. In the **Refresh** list, select when the variable should update options.
- **Never -** Variables queries are cached and values are not updated. This is fine if the values never change, but problematic if they are dynamic and change a lot.
- **On Dashboard Load -** Queries the data source every time the dashboard loads. This slows down dashboard loading, because the variable query needs to be completed before dashboard can be initialized.
......@@ -37,9 +38,9 @@ Query expressions are different for each data source. For more information, refe
1. In the **Query** field, enter a query.
- The query field varies according to your data source. Some data sources have custom query editors.
- If you need more room in a single input field query editor, then hover your cursor over the lines in the lower right corner of the field and drag downward to expand.
1. (optional) In the **Regex** field, type a regex expression to filter or capture specific parts of the names returned by your data source query. To see examples, refer to [Filter variables with regex]({{< relref "filter-variables-with-regex.md" >}}).
1. (optional) In the **Regex** field, type a regex expression to filter or capture specific parts of the names returned by your data source query. To see examples, refer to [Filter variables with regex]({{< relref "../filter-variables-with-regex.md" >}}).
1. In the **Sort** list, select the sort order for values to be displayed in the dropdown list. The default option, **Disabled**, means that the order of options returned by your data source query will be used.
1. (optional) Enter [Selection Options]({{< relref "variable-selection-options.md" >}}).
1. (optional) Enter [Value groups/tags]({{< relref "variable-value-tags.md" >}}).
1. (optional) Enter [Selection Options]({{< relref "../variable-selection-options.md" >}}).
1. (optional) Enter [Value groups/tags]({{< relref "../variable-value-tags.md" >}}).
1. In **Preview of values**, Grafana displays a list of the current variable values. Review them to ensure they match what you expect.
1. Click **Add** to add the variable to the dashboard.
docs/sources/variables/add-text-box-variable.md → docs/sources/variables/variable-types/add-text-box-variable.md
+++
title = "Add a text box variable"
type = "docs"
aliases = ["/docs/grafana/latest/variables/add-text-box-variable.md"]
[menu.docs]
weight = 500
+++
......
docs/sources/variables/chained-variables.md → docs/sources/variables/variable-types/chained-variables.md
......@@ -2,6 +2,7 @@
title = "Chained variables"
keywords = ["grafana", "templating", "variable", "nested", "chained", "linked"]
type = "docs"
aliases = ["/docs/grafana/latest/variables/chained-variables.md"]
[menu.docs]
weight = 600
+++
......
docs/sources/variables/global-variables.md → docs/sources/variables/variable-types/global-variables.md
......@@ -2,6 +2,7 @@
title = "Global variables"
keywords = ["grafana", "templating", "documentation", "guide", "template", "variable", "global", "standard"]
type = "docs"
aliases = ["/docs/grafana/latest/variables/global-variables.md"]
[menu.docs]
name = "global-variables"
parent = "variables"
......
docs/sources/variables/url-variables.md → docs/sources/variables/variable-types/url-variables.md
+++
title = "URL variables"
keywords = ["grafana", "url variables", "documentation", "variables"]
aliases = ["/docs/grafana/latest/variables/url-variables.md"]
type = "docs"
+++
# URL variables
You can use variables in data links to link to specific portions of your visualizations. For more information about data links, refer to [Data links]({{< relref "../linking/data-links.md" >}}).
You can use variables in data links to link to specific portions of your visualizations. For more information about data links, refer to [Data links]({{< relref "../../linking/data-links.md" >}}).
> **Note:** These variables changed in 6.4 so if you have an older version of Grafana please use the version picker to select
docs for an older version of Grafana.
......
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