Docs: updates for file-based menu (#28500)
* initial * cleanup * remove bad aliases * cleanup, fix links * add docs-file-based-command * update docs * update readme * fix broken links * fix spelling Co-authored-by: Diana Payton <52059945+oddlittlebird@users.noreply.github.com>
This commit is contained in:
Robby Milo
co-authored by
Diana Payton
Diana Payton
parent
a7e092f243
commit
abee02dbcd
@@ -1,8 +1,5 @@
|
||||
+++
|
||||
title = "Templates and variables"
|
||||
type = "docs"
|
||||
[menu.docs]
|
||||
identifier = "variables"
|
||||
weight = 130
|
||||
+++
|
||||
|
||||
@@ -36,7 +33,7 @@ Variable values are always synced to the URL using the syntax `var-<varname>=val
|
||||
|
||||
To see variable and template examples, go to any of the dashboards listed in [Variable examples]({{< relref "variable-examples.md" >}}).
|
||||
|
||||
Variables are listed in drop-down 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.
|
||||
|
||||
|
||||
@@ -1,16 +1,12 @@
|
||||
+++
|
||||
title = "Advanced variable format options"
|
||||
keywords = ["grafana", "templating", "documentation", "guide", "template", "variable"]
|
||||
type = "docs"
|
||||
[menu.docs]
|
||||
identifier = "advanced-variables-formats"
|
||||
parent = "variables"
|
||||
weight = 600
|
||||
+++
|
||||
|
||||
# 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.
|
||||
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.
|
||||
|
||||
|
||||
@@ -1,10 +1,6 @@
|
||||
+++
|
||||
title = "Filter variables with regex"
|
||||
keywords = ["grafana", "templating", "documentation", "guide", "template", "variable"]
|
||||
type = "docs"
|
||||
[menu.docs]
|
||||
identifier = "filter-variables-regex"
|
||||
parent = "variables"
|
||||
weight = 700
|
||||
+++
|
||||
|
||||
|
||||
@@ -1,9 +1,5 @@
|
||||
+++
|
||||
title = "Formatting multi-value variables"
|
||||
type = "docs"
|
||||
[menu.docs]
|
||||
identifier = "format-multi-value-variables"
|
||||
parent = "variables"
|
||||
weight = 600
|
||||
+++
|
||||
|
||||
|
||||
@@ -1,10 +1,6 @@
|
||||
+++
|
||||
title = "Variables"
|
||||
keywords = ["grafana", "templating", "documentation", "guide", "template", "variable", "repeat"]
|
||||
type = "docs"
|
||||
[menu.docs]
|
||||
identifier = "repeat-panel-rows"
|
||||
parent = "variables"
|
||||
weight = 800
|
||||
+++
|
||||
|
||||
|
||||
@@ -1,11 +1,7 @@
|
||||
+++
|
||||
title = "Variables syntax and types"
|
||||
keywords = ["grafana", "templating", "documentation", "guide", "template", "variable"]
|
||||
type = "docs"
|
||||
aliases = ["/docs/grafana/latest/reference/templating"]
|
||||
[menu.docs]
|
||||
identifier = "variables-syntax-types"
|
||||
parent = "variables"
|
||||
weight = 100
|
||||
+++
|
||||
|
||||
@@ -16,9 +12,9 @@ Panel titles and metric queries can refer to variables using two different synta
|
||||
- `$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
|
||||
- `${var_name}` Use this syntax when you want to interpolate a variable in the middle of an expression.
|
||||
- `${var_name}` Use this syntax when you want to interpolate a variable in the middle of an expression.
|
||||
- `${var_name:<format>}` This format gives you more control over how Grafana interpolates values. Refer to [Advanced variable format options]({{< relref "advanced-variable-format-options.md" >}}) for more detail on all the formatting types.
|
||||
- `[[varname]]` Do not use. Deprecated old syntax, will be removed in a future release.
|
||||
- `[[varname]]` Do not use. Deprecated old syntax, will be removed in a future release.
|
||||
|
||||
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.
|
||||
|
||||
@@ -1,10 +1,6 @@
|
||||
+++
|
||||
title = "Variable examples"
|
||||
keywords = ["grafana", "templating", "documentation", "guide", "template", "variable"]
|
||||
type = "docs"
|
||||
[menu.docs]
|
||||
identifier = "variables-examples"
|
||||
parent = "variables"
|
||||
weight = 200
|
||||
+++
|
||||
|
||||
|
||||
@@ -1,9 +1,5 @@
|
||||
+++
|
||||
title = "Enter variable Selection Options"
|
||||
type = "docs"
|
||||
[menu.docs]
|
||||
identifier = "variables-selection-options"
|
||||
parent = "variables"
|
||||
weight = 400
|
||||
+++
|
||||
|
||||
@@ -25,6 +21,6 @@ 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.
|
||||
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.
|
||||
|
||||
@@ -1,8 +1,5 @@
|
||||
+++
|
||||
title = "Variables types"
|
||||
type = "docs"
|
||||
[menu.docs]
|
||||
identifier = "variable-types"
|
||||
weight = 140
|
||||
+++
|
||||
|
||||
|
||||
@@ -1,10 +1,6 @@
|
||||
+++
|
||||
title = "Add ad hoc filters"
|
||||
type = "docs"
|
||||
aliases = ["/docs/grafana/latest/variables/add-ad-hoc-filters.md"]
|
||||
[menu.docs]
|
||||
identifier = "add-adhoc-filters"
|
||||
parent = "variable-types"
|
||||
weight = 700
|
||||
+++
|
||||
|
||||
|
||||
@@ -1,10 +1,6 @@
|
||||
+++
|
||||
title = "Add a constant variable"
|
||||
type = "docs"
|
||||
aliases = ["/docs/grafana/latest/variables/add-constant-variable.md"]
|
||||
[menu.docs]
|
||||
identifier = "add-constant-variable"
|
||||
parent = "variable-types"
|
||||
weight = 400
|
||||
+++
|
||||
|
||||
@@ -12,7 +8,7 @@ weight = 400
|
||||
|
||||
_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 _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`.
|
||||
|
||||
@@ -24,10 +20,10 @@ Constant variables are useful when you have complex values that you need to incl
|
||||
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.
|
||||
- **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,10 +1,6 @@
|
||||
+++
|
||||
title = "Add a custom variable"
|
||||
type = "docs"
|
||||
aliases = ["/docs/grafana/latest/variables/add-custom-variable.md"]
|
||||
[menu.docs]
|
||||
identifier = "add-custom-variable"
|
||||
parent = "variable-types"
|
||||
weight = 200
|
||||
+++
|
||||
|
||||
@@ -12,7 +8,7 @@ weight = 200
|
||||
|
||||
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]({{< relref "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
|
||||
|
||||
|
||||
@@ -1,10 +1,6 @@
|
||||
+++
|
||||
title = "Add a data source variable"
|
||||
type = "docs"
|
||||
aliases = ["/docs/grafana/latest/variables/add-data-source-variable.md"]
|
||||
[menu.docs]
|
||||
identifier = "add-datasource-variable"
|
||||
parent = "variable-types"
|
||||
weight = 500
|
||||
+++
|
||||
|
||||
|
||||
@@ -1,10 +1,6 @@
|
||||
+++
|
||||
title = "Add an interval variable"
|
||||
type = "docs"
|
||||
aliases = ["/docs/grafana/latest/variables/add-interval-variable.md"]
|
||||
[menu.docs]
|
||||
identifier = "add-interval-variable"
|
||||
parent = "variable-types"
|
||||
weight = 600
|
||||
+++
|
||||
|
||||
|
||||
@@ -1,10 +1,6 @@
|
||||
+++
|
||||
title = "Add a query variable"
|
||||
type = "docs"
|
||||
aliases = ["/docs/grafana/latest/variables/add-query-variable.md"]
|
||||
[menu.docs]
|
||||
identifier = "add-query-variable"
|
||||
parent = "variable-types"
|
||||
weight = 100
|
||||
+++
|
||||
|
||||
@@ -35,9 +31,9 @@ Query expressions are different for each data source. For more information, refe
|
||||
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 "../../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.
|
||||
- **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.
|
||||
- **On Time Range Change -** Queries the data source when the dashboard time range changes. Only use this option if your variable options query contains a time range filter or is dependent on the dashboard time range.
|
||||
1. In the **Query** field, enter a query.
|
||||
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,10 +1,6 @@
|
||||
+++
|
||||
title = "Add a text box variable"
|
||||
type = "docs"
|
||||
aliases = ["/docs/grafana/latest/variables/add-text-box-variable.md"]
|
||||
[menu.docs]
|
||||
identifier = "add-text-box-variable"
|
||||
parent = "variable-types"
|
||||
weight = 300
|
||||
+++
|
||||
|
||||
@@ -26,6 +22,6 @@ _Text box_ variables display a free text input field with an optional default va
|
||||
|
||||
## 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. (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.
|
||||
|
||||
@@ -1,11 +1,7 @@
|
||||
+++
|
||||
title = "Chained variables"
|
||||
keywords = ["grafana", "templating", "variable", "nested", "chained", "linked"]
|
||||
type = "docs"
|
||||
aliases = ["/docs/grafana/latest/variables/chained-variables.md"]
|
||||
[menu.docs]
|
||||
identifier = "chained-variable"
|
||||
parent = "variable-types"
|
||||
weight = 800
|
||||
+++
|
||||
|
||||
@@ -50,7 +46,7 @@ The values returned are `backend`, `country`, `fakesite`, and `All`.
|
||||
|
||||
#### server variable
|
||||
|
||||
The query for this variable basically says, "Give me all servers for the currently chosen application."
|
||||
The query for this variable basically says, "Give me all servers for the currently chosen application."
|
||||
|
||||
```
|
||||
apps.$app.*
|
||||
@@ -103,14 +99,14 @@ In this example, when the user changes the value of the `datacenter` variable, i
|
||||
The query for this variable basically says, "Give me all the data centers that exist."
|
||||
|
||||
```
|
||||
SHOW TAG VALUES WITH KEY = "datacenter"
|
||||
SHOW TAG VALUES WITH KEY = "datacenter"
|
||||
```
|
||||
|
||||
The values returned are `America`, `Africa`, `Asia`, and `Europe`.
|
||||
|
||||
#### host variable
|
||||
|
||||
The query for this variable basically says, "Give me all hosts for the currently chosen data center."
|
||||
The query for this variable basically says, "Give me all hosts for the currently chosen data center."
|
||||
|
||||
```
|
||||
SHOW TAG VALUES WITH KEY = "hostname" WHERE "datacenter" =~ /^$datacenter$/
|
||||
|
||||
@@ -1,11 +1,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]
|
||||
identifier = "global-variable"
|
||||
parent = "variable-types"
|
||||
weight = 900
|
||||
+++
|
||||
|
||||
@@ -28,7 +24,7 @@ Grafana has two built in time range variables: `$__from` and `$__to`. They are c
|
||||
| Syntax | Example result | Description |
|
||||
| ------------------------ | ------------------------ | ----------- |
|
||||
| `${__from}` | 1594671549254 | Unix millisecond epoch |
|
||||
| `${__from:date}` | 2020-07-13T20:19:09.254Z | No args, defaults to ISO 8601/RFC 3339 |
|
||||
| `${__from:date}` | 2020-07-13T20:19:09.254Z | No args, defaults to ISO 8601/RFC 3339 |
|
||||
| `${__from:date:iso}` | 2020-07-13T20:19:09.254Z | ISO 8601/RFC 3339 |
|
||||
| `${__from:date:seconds}` | 1594671549 | Unix seconds epoch |
|
||||
| `${__from:date:YYYY-MM}` | 2020-07 | Any custom [date format](https://momentjs.com/docs/#/displaying/) |
|
||||
|
||||
@@ -1,9 +1,5 @@
|
||||
+++
|
||||
title = "Enter Value tags"
|
||||
type = "docs"
|
||||
[menu.docs]
|
||||
identifier = "variables-value-groups"
|
||||
parent = "variables"
|
||||
weight = 500
|
||||
+++
|
||||
|
||||
@@ -19,18 +15,18 @@ To see an example, check out [Templating value groups](https://play.grafana.org/
|
||||
|
||||
## 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.
|
||||
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.
|
||||
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.
|
||||
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 values query could be `regions.$tag.*`, which if the user chooses Europe would be interpolated to `regions.Europe.*`.
|
||||
|
||||
Reference in New Issue
Block a user