IntenseWebs/grafana
3
0
Fork 0
mirror of https://github.com/grafana/grafana.git synced 2025-02-25 18:55:37 -06:00
Code Issues Packages Projects Releases Wiki Activity

Docs: Add variable topics - custom, constant, text box (#26471)

Browse Source 
* moved some content into other topics

* Update variable-value-tags.md

* Update variable-selection-options.md

* Update add-query-variable.md

* Update templates-and-variables.md

* Create add-custom-variable.md

* Update menu.yaml

* Update templates-and-variables.md

* Update templates-and-variables.md

* editing content

* Create add-text-box-variable.md

* added links

* content updates

* update-content

* Update templates-and-variables.md

* Update menu.yaml

* Update add-constant-variable.md

* Update add-constant-variable.md

* Update docs/sources/variables/add-query-variable.md

Co-authored-by: Arve Knudsen <arve.knudsen@gmail.com>

* Update docs/sources/variables/variable-value-tags.md

Co-authored-by: Arve Knudsen <arve.knudsen@gmail.com>

* Update docs/sources/variables/variable-value-tags.md

Co-authored-by: Arve Knudsen <arve.knudsen@gmail.com>

* Update docs/sources/variables/variable-value-tags.md

Co-authored-by: Arve Knudsen <arve.knudsen@gmail.com>

Co-authored-by: Arve Knudsen <arve.knudsen@gmail.com>
This commit is contained in:
Diana Payton 2020-07-21 08:33:10 -07:00 committed by GitHub
parent fb5ff6a70f
commit bd7c26257d
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
8 changed files with 174 additions and 61 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

12
docs/sources/menu.yaml
View File

@ -254,7 +254,17 @@
- link: /variables/templates-and-variables/
name: Overview
- link: /variables/add-query-variable/
name: Add a 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
- 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/

32
docs/sources/variables/add-constant-variable.md Normal file
View File

@ -0,0 +1,32 @@
+++
title = "Add a constant variable"
type = "docs"
[menu.docs]
weight = 500
+++
# Add a constant variable
_Constant_ variables allow you to define a hidden constant. This is useful for metric path prefixes for dashboards you want to share. When you export a dashboard, constant variables are converted to import options.
Constant variables are _not_ flexible. Each constant variable only holds one value, and it cannot be updated unless you update the variable settings.
Constant variables are useful when you have complex values that you need to include in queries but don't want to retype in every single query. For example, if you had a server path called `i-0b6a61efe2ab843gg`, then you could replace it with a variable called `$path_gg`.
## Enter General options
1. Navigate to the dashboard you want to make a variable for and then click the **Dashboard settings** (gear) icon at the top of the page.
1. On the Variables tab, click **New**.
1. Enter a **Name** for your variable.
1. In the **Type** list, select **Constant**.
1. (optional) In **Label**, enter the display name of the variable dropdown. If you don't enter a display name, then the dropdown label will be the variable name.
1. Choose a **Hide** option:
- **Variable -** No variable dropdown is displayed on the dashboard. This is the default.
- **No selection (blank) -** The variable dropdown displays the variable **Name** or **Label** value.
- **Label -** The variable dropdown only displays the selected variable value and a down arrow.
## 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 **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.

31
docs/sources/variables/add-custom-variable.md Normal file
View File

@ -0,0 +1,31 @@
+++
title = "Add a custom variable"
type = "docs"
[menu.docs]
weight = 500
+++
# Add a custom variable
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.
## Enter General options
1. Navigate to the dashboard you want to make a variable for and then click the **Dashboard settings** (gear) icon at the top of the page.
1. On the Variables tab, click **New**.
1. Enter a **Name** for your variable.
1. In the **Type** list, select **Custom**.
1. (optional) In **Label**, enter the display name of the variable dropdown. If you don't enter a display name, then the dropdown label will be the variable name.
1. Choose a **Hide** option:
- **No selection (blank) -** The variable dropdown displays the variable **Name** or **Label** value. This is the default.
- **Label -** The variable dropdown only displays the selected variable value and a down arrow.
- **Variable -** No variable dropdown is displayed on the dashboard.
## 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. 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.

59
docs/sources/variables/add-query-variable.md
View File

@ -37,58 +37,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.
2. (optional) In the **Regex** field, type a regex expression to filter or capture specific parts of the names return by your data source query. To see examples, refer to [Filter variables with regex]({{< relref "filter-variables-with-regex.md" >}}).
3. 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.
## Enter Selection Options
All selection options are optional, and they are off by default.
### Multi-value
If you turn this on, then the variable dropdown list allows users to select multiple options at the same time. For more information, refer to [Formatting multi-value variables]({{< relref "formatting-multi-value-variables.md" >}}).
### Include All option
Grafana adds an `All` option to the variable dropdown list. If a user selects this option, then all variable options are selected.
### Custom all value
This option is only visible if the **Include All option** is selected.
Enter regex, globs, or lucene syntax in the **Custom all value** field to define the value of the `All` option.
By default the `All` value includes all options in combined expression. This can become very long and can have performance problems. Sometimes it can be better to specify a custom all value, like a wildcard regex.
In order 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.
## Enter Value groups/tags (experimental feature)
If you have many options in the dropdown for a multi-value variable, then you can use this feature to group the values into selectable tags.
{{< docs-imagebox img="/img/docs/v50/variable_dropdown_tags.png" max-width="300px" >}}
This feature is off by default. Click **Enabled** to turn on the feature.
### Tags query
Enter a data source query that should return a list of tags. The tags query returns a list of tags that each represent a group, and the tag values query returns a list of group members.
For example, the tags query could be a list of regions (Europe, Asia, Americas), and then if the user selects the Europe tag, then the tag values query would return a list of countries -- Sweden, Germany, France, and so on.
If you have a variable with a lot of values (say all the countries in the world), then this allows you to easily select a group of them. If the user selects the tag Europe, all the countries in Europe would be selected.
In this [example dashboard](https://play.grafana.org/d/ZUPhFVGGk/graphite-with-experimental-tags?orgId=1), the server variable has tags enabled.
### Tag values query
Enter a 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.
The `$tag` variable will have the value of the tag that the user chooses.
For example, if you have a Graphite query for tags, `regions.*`, that returns a list of regions. The the values query could be `regions.$tag.*`, which if the user chooses Europe would be interpolated to `regions.Europe.*`.
## Final steps
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. 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.
1. Click **Add** to add the variable to the dashboard.

28
docs/sources/variables/add-text-box-variable.md Normal file
View File

@ -0,0 +1,28 @@
+++
title = "Add a text box variable"
type = "docs"
[menu.docs]
weight = 500
+++
# Add a text box variable
_Text box_ variables display a free text input field with an optional default value. This is the most flexible variable, because you can enter any value. Use this type of variable if you have metrics with high cardinality or if you want to update multiple panels in a dashboard at the same time.
## Enter General options
1. Navigate to the dashboard you want to make a variable for and then click the **Dashboard settings** (gear) icon at the top of the page.
1. On the Variables tab, click **New**.
1. Enter a **Name** for your variable.
1. In the **Type** list, select **Text box**.
1. (optional) In **Label**, enter the display name of the variable dropdown. If you don't enter a display name, then the dropdown label will be the variable name.
1. Choose a **Hide** option:
- **No selection (blank) -** The variable dropdown displays the variable **Name** or **Label** value. This is the default.
- **Label -** The variable dropdown only displays the selected variable value and a down arrow.
- **Variable -** No variable dropdown is displayed on the dashboard.
## Enter Text options
1. (optional) In the **Default value** field, select the default value for the variable. If you do not enter anything in this field, then Grafana displays an empty text box for users to type text into.
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.

13
docs/sources/variables/templates-and-variables.md
View File

@ -76,23 +76,23 @@ You can also define the following types of variables in Grafana.
### Query
Query variables allow you to write a data source query that might return a list of metric names, tag values, keys, server names, sensor IDs, data centers, etc.
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" >}}).
Queries can contain other variables. For more information, refer to [Chained variables]({{< relref "chained-variables.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.
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
Text box variables display as a free text input field with an optional default value.
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. Useful for metric path prefixes for dashboards you want to share. During dashboard export, constant variables are made into an import option.
Define a hidden constant. For instructions, refer to [Add a constant variable]({{< relref "add-constant-variable.md" >}}).
### Data source
@ -118,4 +118,5 @@ Ad hoc filter variables only work with InfluxDB, Prometheus, and Elasticsearch
## Variable best practices
- Variable drop-down lists are displayed in the order they are listed in the variable list in Dashboard settings. Consider putting the variables that you will change often at the top, so they will be shown first (far left on the dashboard).
- Variable drop-down lists are displayed in the order they are listed in the variable list in Dashboard settings.
- Put the variables that you will change often at the top, so they will be shown first (far left on the dashboard).

28
docs/sources/variables/variable-selection-options.md Normal file
View File

@ -0,0 +1,28 @@
+++
title = "Enter variable Selection Options"
type = "docs"
[menu.docs]
weight = 800
+++
# Enter variable selection options
**Selection Options** are a feature you can use to manage variable option selections. All selection options are optional, and they are off by default.
## Multi-value
If you turn this on, then the variable dropdown list allows users to select multiple options at the same time. For more information, refer to [Formatting multi-value variables]({{< relref "formatting-multi-value-variables.md" >}}).
## Include All option
Grafana adds an `All` option to the variable dropdown list. If a user selects this option, then all variable options are selected.
## Custom all value
This option is only visible if the **Include All option** is selected.
Enter regex, globs, or lucene syntax in the **Custom all value** field to define the value of the `All` option.
By default the `All` value includes all options in combined expression. This can become very long and can have performance problems. Sometimes it can be better to specify a custom all value, like a wildcard regex.
In order 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.

32
docs/sources/variables/variable-value-tags.md Normal file
View File

@ -0,0 +1,32 @@
+++
title = "Enter Value tags"
type = "docs"
[menu.docs]
weight = 800
+++
# Enter variable value groups/tags (experimental feature)
Value groups/tags are a feature you can use to organize variable options. If you have many options in the dropdown for a multi-value variable, then you can use this feature to group the values into selectable tags.
{{< docs-imagebox img="/img/docs/v50/variable_dropdown_tags.png" max-width="300px" >}}
This feature is off by default. Click **Enabled** to turn the feature on.
## Tags query
Enter a data source query that should return a list of tags. The tags query returns a list of tags that each represents a group, and the tag values query returns a list of group members.
For example, the tags query could be a list of regions (Europe, Asia, Americas), and then if the user selects the Europe tag, then the tag values query would return a list of countries -- Sweden, Germany, France, and so on.
If you have a variable with a lot of values (say all the countries in the world), then this allows you to easily select a group of them. If the user selects the tag Europe, all the countries in Europe would be selected.
In this [example dashboard](https://play.grafana.org/d/ZUPhFVGGk/graphite-with-experimental-tags?orgId=1), the server variable has tags enabled.
## Tag values query
Enter a data source query that should return a list of values for a specified tag key. Use `$tag` in the query to refer to the currently selected tag.
The `$tag` variable will have the value of the tag that the user chooses.
For example, if you have a Graphite query for tags, `regions.*`, that returns a list of regions. The the values query could be `regions.$tag.*`, which if the user chooses Europe would be interpolated to `regions.Europe.*`.