mirror of
https://github.com/grafana/grafana.git
synced 2025-02-25 18:55:37 -06:00
Docs/refactors variables topics (#54470)
* refactor and partial relref fix * finishes variables refactor * Update docs/sources/variables/add-template-variables/index.md Co-authored-by: Torkel Ödegaard <torkel@grafana.com> * removes duplicate general options, adds links to general options within tasks * adds configure variable selection options topic * starts phase II of refactoring * incorporates feedback, updates relrefs * corrects final relrefs * updates alias Co-authored-by: Torkel Ödegaard <torkel@grafana.com>
This commit is contained in:
Christopher Moyer
GitHub
parent
b382c7ac1d
commit
7147d17567
@ -52,5 +52,5 @@ Once you have a strategy or design guidelines, write them down to help maintain
|
||||
- Add documentation to dashboards and panels.
|
||||
- To add documentation to a dashboard, add a [Text panel visualization]({{< relref "../visualizations/text-panel/" >}}) to the dashboard. Record things like the purpose of the dashboard, useful resource links, and any instructions users might need to interact with the dashboard. Check out this [Wikimedia example](https://grafana.wikimedia.org/d/000000066/resourceloader?orgId=1).
|
||||
- To add documentation to a panel, edit the panel settings and add a description. Any text you add will appear if you hover your cursor over the small `i` in the top left corner of the panel.
|
||||
- Reuse your dashboards and enforce consistency by using [templates and variables]({{< relref "../variables/" >}}).
|
||||
- Reuse your dashboards and enforce consistency by using [templates and variables]({{< relref "../dashboards/variables" >}}).
|
||||
- Be careful with stacking graph data. The visualizations can be misleading, and hide important data. We recommend turning it off in most cases.
|
||||
|
||||
@ -35,7 +35,7 @@ How can you tell you are here?
|
||||
|
||||
- Prevent sprawl by using template variables. For example, you don't need a separate dashboard for each node, you can use query variables. Even better, you can make the data source a template variable too, so you can reuse the same dashboard across different clusters and monitoring backends.
|
||||
|
||||
Refer to the list of [Variable examples]({{< relref "../variables/variable-examples/" >}}) if you want some ideas.
|
||||
Refer to the list of [Variable examples]({{< relref "../dashboards/variables/#examples-of-templates-and-variables" >}}) if you want some ideas.
|
||||
|
||||
- Methodical dashboards according to an [observability strategy]({{< relref "common-observability-strategies/" >}}).
|
||||
- Hierarchical dashboards with drill-downs to the next level.
|
||||
|
||||
@ -76,7 +76,7 @@ Only organization administrators can create reports by default. You can customiz
|
||||
|
||||
> **Note:** Available in [Grafana Enterprise]({{< relref "../../enterprise/" >}}) version 7.5 and later behind the `reportVariables` feature flag, Grafana Enterprise version 8.0 and later without a feature flag, and [Grafana Cloud Pro and Advanced]({{< ref "/grafana-cloud" >}}).
|
||||
|
||||
You can configure report-specific template variables for the dashboard on the report page. The variables that you select will override the variables from the dashboard, and they are used when rendering a PDF file of the report. For detailed information about using template variables, refer to the [Templates and variables]({{< relref "../../variables/" >}}) section.
|
||||
You can configure report-specific template variables for the dashboard on the report page. The variables that you select will override the variables from the dashboard, and they are used when rendering a PDF file of the report. For detailed information about using template variables, refer to the [Templates and variables]({{< relref "../variables/" >}}) section.
|
||||
|
||||
> **Note:** The query variables saved with a report might become of date if the results of that query change. For example, if your template variable queries for a list of hostnames and a new hostname is added, then it will not be included in the report. If that occurs, the selected variables must be manually updated in the report. If you select the `All` value for the template variable or if you keep the dashboard's original variable selection, then the report stays up-to-date as new values are added.
|
||||
|
||||
|
||||
@ -13,6 +13,8 @@ aliases:
|
||||
- /docs/grafana/latest/administration/reports/
|
||||
- /docs/grafana/latest/dashboards/reporting/
|
||||
- /docs/grafana/latest/enterprise/export-pdf/
|
||||
- docs/grafana/latest/dashboards/share-dashboards-panels/
|
||||
- /docs/grafana/latest/share-dashboards-panels/
|
||||
title: Share dashboards and panels
|
||||
menuTitle: Share dashboards and panels
|
||||
weight: 85
|
||||
@ -87,9 +89,7 @@ If you created a snapshot by mistake, click **Delete snapshot** to remove the sn
|
||||
|
||||
### Dashboard export
|
||||
|
||||
Grafana dashboards can easily be exported and imported. For more information, refer to [Export and import dashboards]({{< relref "../dashboards/manage-dashboards/#export-and-import-dashboards" >}}).
|
||||
|
||||
Export and import dashboards
|
||||
Grafana dashboards can easily be exported and imported. For more information, refer to [Export and import dashboards]({{< relref "./manage-dashboards/#export-and-import-dashboards" >}}).
|
||||
|
||||
|
||||
|
||||
@ -97,7 +97,7 @@ Export and import dashboards
|
||||
|
||||
You can generate and save PDF files of any dashboard.
|
||||
|
||||
> **Note:** Available in [Grafana Enterprise]({{< relref "../introduction/grafana-enterprise/" >}}).
|
||||
> **Note:** Available in [Grafana Enterprise]({{< relref "../../introduction/grafana-enterprise/" >}}).
|
||||
|
||||
1. In the upper-right corner of the dashboard that you want to export as PDF, click the **Share dashboard** icon.
|
||||
1. On the PDF tab, select a layout option for the exported dashboard: **Portrait** or **Landscape**.
|
||||
@ -127,7 +127,7 @@ The **Link** tab shows the current time range, template variables, and the defau
|
||||
1. Send the copied URL to a Grafana user with authorization to view the link.
|
||||
1. You also optionally click **Direct link rendered image** to share an image of the panel.
|
||||
|
||||
For more information, refer to [Image rendering]({{< relref "../setup-grafana/image-rendering/" >}}).
|
||||
For more information, refer to [Image rendering]({{< relref "../../setup-grafana/image-rendering/" >}}).
|
||||
|
||||
The following example shows a link to a server-side rendered PNG:
|
||||
|
||||
@ -1,11 +1,12 @@
|
||||
---
|
||||
aliases:
|
||||
- /docs/grafana/latest/variables/
|
||||
title: Templates and variables
|
||||
- /docs/grafana/latest/variables/variable-examples/
|
||||
title: Template variables
|
||||
weight: 130
|
||||
---
|
||||
|
||||
# Templates and variables
|
||||
# Template 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.
|
||||
@ -33,14 +34,25 @@ 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 in [Variable examples]({{< relref "variable-examples/" >}}).
|
||||
|
||||
Variables are listed in drop-down lists across the top of the screen. Select different variables to see how the visualizations change.
|
||||
|
||||
To see variable settings, navigate to **Dashboard Settings > Variables**. Click a variable in the list to see its settings.
|
||||
|
||||
Variables can be used in titles, descriptions, text panels, and queries. Queries with text that starts with `$` are templates. Not all panels will have template queries.
|
||||
|
||||
The following dashboards in Grafana Play provide examples of template variables.
|
||||
|
||||
- [Elasticsearch Metrics](https://play.grafana.org/d/000000014/elasticsearch-metrics?orgId=1) - Uses ad hoc filters, global variables, and a custom variable.
|
||||
- [Graphite Templated Nested](https://play.grafana.org/d/000000056/graphite-templated-nested?orgId=1) - Uses query variables, chained query variables, an interval variable, and a repeated panel.
|
||||
- [Influx DB Group By Variable](https://play.grafana.org/d/000000137/influxdb-group-by-variable?orgId=1) - Query variable, panel uses the variable results to group the metric data.
|
||||
- [InfluxDB Raw Query Template Var](https://play.grafana.org/d/000000083/influxdb-raw-query-template-var?orgId=1) - Uses query variables, chained query variables, and an interval variable.
|
||||
- [InfluxDB Server Monitoring](https://play.grafana.org/d/AAy9r_bmk/influxdb-server-monitoring?orgId=1) - Uses query variables, chained query variables, an interval variable, and an ad hoc filter.
|
||||
- [Prometheus templating](https://play.grafana.org/d/000000063/prometheus-templating?orgId=1) - Uses chained query variables.
|
||||
- [Template Redux](https://play.grafana.org/d/p-k6QtkGz/template-redux?orgId=1) - Uses query variables, chained query variables, ad hoc filters, an interval variable, a text box variable, a custom variable, and a data source variable.
|
||||
- [Templating, repeated panels](https://play.grafana.org/d/000000025/templating-repeated-panels?orgId=1) - Two sets of repeated panels use query variables.
|
||||
- [Templating showcase](https://play.grafana.org/d/000000091/templating-showcase?orgId=1) - Uses custom, query, chained query, and data source variables.
|
||||
- [Templating value groups](https://play.grafana.org/d/000000024/templating-value-groups?orgId=1) - Uses query variable with value groups.
|
||||
|
||||
## Variable best practices
|
||||
|
||||
- Variable drop-down lists are displayed in the order they are listed in the variable list in Dashboard settings.
|
||||
@ -0,0 +1,596 @@
|
||||
---
|
||||
aliases:
|
||||
- /docs/grafana/latest/variables/variable-types/
|
||||
- /docs/grafana/latest/variables/add-query-variable/
|
||||
- /docs/grafana/latest/variables/variable-types/add-query-variable/
|
||||
- /docs/grafana/latest/variables/add-custom-variable/
|
||||
- /docs/grafana/latest/variables/variable-types/add-custom-variable/
|
||||
- /docs/grafana/latest/variables/add-text-box-variable/
|
||||
- /docs/grafana/latest/variables/variable-types/add-text-box-variable/
|
||||
- /docs/grafana/latest/variables/add-constant-variable/
|
||||
- /docs/grafana/latest/variables/variable-types/add-constant-variable/
|
||||
- /docs/grafana/latest/variables/add-data-source-variable/
|
||||
- /docs/grafana/latest/variables/variable-types/add-data-source-variable/
|
||||
- /docs/grafana/latest/variables/add-interval-variable/
|
||||
- /docs/grafana/latest/variables/variable-types/add-interval-variable/
|
||||
- /docs/grafana/latest/variables/add-ad-hoc-filters/
|
||||
- /docs/grafana/latest/variables/variable-types/add-ad-hoc-filters/
|
||||
- /docs/grafana/latest/variables/global-variables/
|
||||
- /docs/grafana/latest/variables/variable-types/global-variables/
|
||||
- /docs/grafana/latest/variables/chained-variables/
|
||||
- /docs/grafana/latest/variables/variable-types/chained-variables/
|
||||
- /docs/grafana/latest/variables/add-template-variables/
|
||||
- /docs/grafana/latest/variables/variable-selection-options/
|
||||
- /docs/grafana/latest/variables/filter-variables-with-regex/
|
||||
- /docs/grafana/latest/variables/formatting-multi-value-variables/
|
||||
- /docs/grafana/latest/reference/templating/
|
||||
- /docs/grafana/latest/variables/manage-variable/
|
||||
title: Add and manage template variables
|
||||
menuTitle: Add and manage template variables
|
||||
weight: 100
|
||||
keywords:
|
||||
- grafana
|
||||
- templating
|
||||
- documentation
|
||||
- guide
|
||||
- template
|
||||
- variable
|
||||
- global
|
||||
- standard
|
||||
- nested
|
||||
- chained
|
||||
- linked
|
||||
---
|
||||
|
||||
# Add and manage template variables
|
||||
|
||||
The following table lists the types of variables shipped with Grafana.
|
||||
|
||||
| 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-a-query-variable" >}}). |
|
||||
| Custom | Define the variable options manually using a comma-separated list. [Add a custom variable]({{< relref "#add-a-custom-variable" >}}). |
|
||||
| Text box | Display a free text input field with an optional default value. [Add a text box variable]({{< relref "#add-a-text-box-variable" >}}). |
|
||||
| Constant | Define a hidden constant. [Add a constant variable]({{< relref "#add-a-constant-variable" >}}). |
|
||||
| Data source | Quickly change the data source for an entire dashboard. [Add a data source variable]({{< relref "#add-a-data-source-variable" >}}). |
|
||||
| Interval | Interval variables represent time spans. [Add an interval variable]({{< relref "#add-an-interval-variable" >}}). |
|
||||
| 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" >}}). |
|
||||
| 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" >}}). |
|
||||
|
||||
### Enter General options
|
||||
|
||||
You must enter general options for any type of variable that you create.
|
||||
|
||||
1. Navigate to the dashboard you want to make a variable for and click the **Dashboard settings** (gear) icon at the top of the page.
|
||||
1. On the **Variables** tab, click **New**.
|
||||
1. Enter a **Name** for the variable.
|
||||
1. In the **Type** list, select **Query**.
|
||||
1. (Optional) In **Label**, enter the display name of the variable dropdown.
|
||||
|
||||
If you don't enter a display name, then the dropdown label is 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.
|
||||
|
||||
## Add a query variable
|
||||
|
||||
Query variables enable you to write a data source query that can return a list of metric names, tag values, or keys. For example, a query variable might return a list of server names, sensor IDs, or data centers. The variable values change as they dynamically fetch options with a data source query.
|
||||
|
||||
Query variables are generally only supported for strings. If your query returns numbers or any other data type, you might need to convert them to strings in order to use them as variables. For the Azure data source, for example, you can use the [tostring](https://docs.microsoft.com/en-us/azure/data-explorer/kusto/query/tostringfunction) function for this purpose.
|
||||
|
||||
Query expressions can contain references to other variables and in effect create linked variables. Grafana detects this and automatically refreshes a variable when one of its linked variables change.
|
||||
|
||||
> **Note:** Query expressions are different for each data source. For more information, refer to the documentation for your [data source]({{< relref "../../../datasources/" >}}).
|
||||
|
||||
1. [Enter general options](#enter-general-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 "../../../datasources/add-a-data-source/" >}}).
|
||||
1. In the **Refresh** list, select when the variable should update options.
|
||||
- **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.
|
||||
- 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" >}}).
|
||||
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 "#configure-variable-selection-options" >}}).
|
||||
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.
|
||||
|
||||
## Add a custom variable
|
||||
|
||||
Use a _custom_ variable for a value that does not change, such as a number or a string.
|
||||
|
||||
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" >}}) rather than other query variables. That would reduce the number of queries Grafana must send when chained variables are updated.
|
||||
|
||||
1. [Enter general options](#enter-general-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 key/value pairs separated by a space and a colon. For example, `key1 : value1,key2 : value2`.
|
||||
1. (Optional) Enter [Selection Options]({{< relref "#configure-variable-selection-options" >}}).
|
||||
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.
|
||||
|
||||
## 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.
|
||||
|
||||
1. [Enter general options](#enter-general-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.
|
||||
|
||||
## Add a constant variable
|
||||
|
||||
_Constant_ variables enable 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 query. For example, if you had a server path called `i-0b6a61efe2ab843gg`, then you could replace it with a variable called `$path_gg`.
|
||||
|
||||
1. [Enter general options](#enter-general-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 "../variable-syntax/#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.
|
||||
|
||||
## Add a data source variable
|
||||
|
||||
_Data source_ variables enable you to quickly change the data source for an entire dashboard. They are useful if you have multiple instances of a data source, perhaps in different environments.
|
||||
|
||||
1. [Enter general options](#enter-general-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 "../../../datasources/add-a-data-source/" >}}).
|
||||
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 "#configure-variable-selection-options" >}}).
|
||||
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.
|
||||
|
||||
## Add an interval variable
|
||||
|
||||
Use an _interval_ variable to represents time spans such as `1m`,`1h`, `1d`. You can think of them as a dashboard-wide "group by time" command. Interval variables change how the data is grouped in the visualization. You can also use the Auto Option to return a set number of data points per time span.
|
||||
|
||||
You can use an interval variable as a parameter to group by time (for InfluxDB), date histogram interval (for Elasticsearch), or as a summarize function parameter (for Graphite).
|
||||
|
||||
1. [Enter general options](#enter-general-options).
|
||||
1. In the **Values** field, enter the time range intervals that you want to appear in the variable drop-down list. The following time units are supported: `s (seconds)`, `m (minutes)`, `h (hours)`, `d (days)`, `w (weeks)`, `M (months)`, and `y (years)`. You can also accept or edit the default values: `1m,10m,30m,1h,6h,12h,1d,7d,14d,30d`.
|
||||
1. (Optional) Turn on the **Auto Option** if you want to add the `auto` option to the list. This option allows you to specify how many times the current time range should be divided to calculate the current `auto` time span. If you turn it on, then two more options appear:
|
||||
- **Step count -** Select the number of times the current time range will be divided to calculate the value, similar to the **Max data points** query option. For example, if the current visible time range is 30 minutes, then the `auto` interval groups the data into 30 one-minute increments. The default value is 30 steps.
|
||||
- **Min Interval -** The minimum threshold below which the step count intervals will not divide the time. To continue the 30 minute example, if the minimum interval is set to 2m, then Grafana would group the data into 15 two-minute increments.
|
||||
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.
|
||||
|
||||
### Interval variable examples
|
||||
|
||||
The following example shows a template variable `myinterval` in a Graphite function:
|
||||
|
||||
```
|
||||
summarize($myinterval, sum, false)
|
||||
```
|
||||
|
||||
The following example shows a more complex Graphite example, from the [Graphite Template Nested Requests panel](https://play.grafana.org/d/000000056/graphite-templated-nested?editPanel=2&orgId=1):
|
||||
|
||||
```
|
||||
groupByNode(summarize(movingAverage(apps.$app.$server.counters.requests.count, 5), '$interval', 'sum', false), 2, 'sum')
|
||||
```
|
||||
|
||||
## Add ad hoc filters
|
||||
|
||||
_Ad hoc filters_ enable you to add key/value filters that are automatically added to all metric queries that use the specified data source. Unlike other variables, you do not use ad hoc filters in queries. Instead, you use ad hoc filters to write filters for existing queries.
|
||||
|
||||
> **Note:** Ad hoc filter variables only work with Prometheus, Loki, InfluxDB, and Elasticsearch data sources.
|
||||
|
||||
1. [Enter general options](#enter-general-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 "../../../datasources/add-a-data-source/" >}}).
|
||||
1. Click **Add** to add the variable to the dashboard.
|
||||
|
||||
### Create ad hoc filters
|
||||
|
||||
Ad hoc filters are one of the most complex and flexible variable options available. Instead of a regular list of variable options, this variable allows you to build a dashboard-wide ad hoc query. Filters you apply in this manner are applied to all panels on the dashboard.
|
||||
|
||||
## Configure 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 variables
|
||||
|
||||
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:** The **Custom all value** option on the variable must be blank for Grafana to format all values into a single string. If leave it blank, then the Grafana concatenates (adds together) all the values in the query. Something like `value1,value2,value3`. If a custom `all` value is used, then instead the value will be something like `*` or `all`.
|
||||
|
||||
#### Multi-value variables with a Graphite data source
|
||||
|
||||
Graphite 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_.
|
||||
|
||||
#### Multi-value variables with a Prometheus or InfluxDB data source
|
||||
|
||||
InfluxDB and Prometheus use 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.
|
||||
|
||||
#### Multi-value variables with an Elastic data source
|
||||
|
||||
Elasticsearch uses lucene query syntax, so the same variable would be formatted as `("host1" OR "host2" OR "host3")`. In this case, every value must be escaped so that the value only contains lucene control words and quotation marks.
|
||||
|
||||
#### Troubleshoot multi-value variables
|
||||
|
||||
Automatic escaping and formatting can cause problems and it can be tricky to grasp the logic 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, then you must do one of the following:
|
||||
|
||||
- Turn off the **Multi-value** or **Include All option** options.
|
||||
- Use the [raw variable format]({{< relref "../variable-syntax/#raw" >}}).
|
||||
|
||||
### 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.
|
||||
|
||||
## 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. These variables are useful in queries, dashboard links, panel links, and data links.
|
||||
|
||||
### $\_\_dashboard
|
||||
|
||||
> Only available in Grafana v6.7+. In Grafana 7.1, the variable changed from showing the UID of the current dashboard to the name of the current dashboard.
|
||||
|
||||
This variable is the name of the current dashboard.
|
||||
|
||||
### $\_\_from and $\_\_to
|
||||
|
||||
Grafana has two built-in time range variables: `$__from` and `$__to`. They are currently always interpolated as epoch milliseconds by default, but you can control date formatting.
|
||||
|
||||
> **Note:** This special formatting syntax is only available in Grafana 7.1.2+
|
||||
|
||||
| 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: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/) that does not include the `:` character |
|
||||
|
||||
The syntax above also works with `${__to}`.
|
||||
|
||||
You can use this variable in URLs, as well. For example, you can send a user to a dashboard that shows a time range from six hours ago until now: https://play.grafana.org/d/000000012/grafana-play-home?viewPanel=2&orgId=1?from=now-6h&to=now
|
||||
|
||||
### $\_\_interval
|
||||
|
||||
You can use the `$__interval` variable 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: `(to - from) / 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
|
||||
|
||||
This variable is the ID of the current organization.
|
||||
`${__org.name}` is the name of the current organization.
|
||||
|
||||
### $\_\_user
|
||||
|
||||
> Only available in Grafana v7.1+
|
||||
|
||||
`${__user.id}` is the ID of the current user.
|
||||
`${__user.login}` is the login handle of the current user.
|
||||
`${__user.email}` is the email for the current user.
|
||||
|
||||
### $\_\_range
|
||||
|
||||
Currently only supported for Prometheus and Loki 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`.
|
||||
|
||||
### $\_\_rate_interval
|
||||
|
||||
Currently only supported for Prometheus data sources. The `$__rate_interval` variable is meant to be used in the rate function. Refer to [Prometheus query variables]({{< relref "../../../datasources/prometheus.md#using-__rate_interval">}}) for details.
|
||||
|
||||
### $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. You can add it 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.
|
||||
|
||||
## Chained variables
|
||||
|
||||
_Chained variables_, also called _linked variables_ or _nested variables_, are query variables with one or more other variables in their variable query. This section explains how chained variables work and provides links to example dashboards that use chained variables.
|
||||
|
||||
Chained variable queries are different for every data source, but the premise is the same for all. You can use chained variable queries in any data source that allows them.
|
||||
|
||||
Extremely complex linked templated dashboards are possible, 5 or 10 levels deep. Technically, there is no limit to how deep or complex you can go, but the more links you have, the greater the query load.
|
||||
|
||||
### Grafana Play dashboard examples
|
||||
|
||||
The following Grafana Play dashboards contain fairly simple chained variables, only two layers deep. To view the variables and their settings, click **Dashboard settings** (gear icon) and then click **Variables**. Both examples are expanded in the following section.
|
||||
|
||||
- [Graphite Templated Nested](https://play.grafana.org/d/000000056/graphite-templated-nested?orgId=1&var-app=country&var-server=All&var-interval=1h)
|
||||
- [InfluxDB Templated](https://play.grafana.org/d/000000002/influxdb-templated?orgId=1)
|
||||
|
||||
### Examples explained
|
||||
|
||||
Variables are useful to reuse dashboards and dynamically change what is shown in dashboards. Chained variables are especially useful to filter what you see.
|
||||
|
||||
Create parent/child relationship in a variable, sort of a tree structure where you can select different levels of filters.
|
||||
|
||||
The following sections explain the linked examples in the dashboards above in depth and builds on them. While the examples are data source-specific, the concepts can be applied broadly.
|
||||
|
||||
#### Graphite example
|
||||
|
||||
In this example, there are several applications. Each application has a different subset of servers. It is based on the [Graphite Templated Nested](https://play.grafana.org/d/000000056/graphite-templated-nested?orgId=1&var-app=country&var-server=All&var-interval=1h).
|
||||
|
||||
Now, you could make separate variables for each metric source, but then you have to know which server goes with which app. A better solution is to use one variable to filter another. In this example, when the user changes the value of the `app` variable, it changes the dropdown options returned by the `server` variable. Both variables use the **Multi-value** option and **Include all option**, enabling users to select some or all options presented at any time.
|
||||
|
||||
##### app variable
|
||||
|
||||
The query for this variable basically says, "Give me all the applications that exist."
|
||||
|
||||
```
|
||||
apps.*
|
||||
```
|
||||
|
||||
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."
|
||||
|
||||
```
|
||||
apps.$app.*
|
||||
```
|
||||
|
||||
If the user selects `backend`, then the query changes to:
|
||||
|
||||
```
|
||||
apps.backend.*
|
||||
```
|
||||
|
||||
The query returns all servers associated with `backend`, including `backend_01`, `backend_02`, and so on.
|
||||
|
||||
If the user selects `fakesite`, then the query changes to:
|
||||
|
||||
```
|
||||
apps.fakesite.*
|
||||
```
|
||||
|
||||
The query returns all servers associated with `fakesite`, including `web_server_01`, `web_server_02`, and so on.
|
||||
|
||||
##### More variables
|
||||
|
||||
> **Note:** This example is theoretical. The Graphite server used in the example does not contain CPU metrics.
|
||||
|
||||
The dashboard stops at two levels, but you could keep going. For example, if you wanted to get CPU metrics for selected servers, you could copy the `server` variable and extend the query so that it reads:
|
||||
|
||||
```
|
||||
apps.$app.$server.cpu.*
|
||||
```
|
||||
|
||||
This query basically says, "Show me the CPU metrics for the selected server."
|
||||
|
||||
Depending on what variable options the user selects, you could get queries like:
|
||||
|
||||
```
|
||||
apps.backend.backend_01.cpu.*
|
||||
apps.{backend.backend_02,backend_03}.cpu.*
|
||||
apps.fakesite.web_server_01.cpu.*
|
||||
```
|
||||
|
||||
#### InfluxDB example
|
||||
|
||||
In this example, you have several data centers. Each data center has a different subset of hosts. It is based on the [InfluxDB Templated](https://play.grafana.org/d/000000002/influxdb-templated?orgId=1).
|
||||
|
||||
In this example, when the user changes the value of the `datacenter` variable, it changes the dropdown options returned by the `host` variable. The `host` variable uses the **Multi-value** option and **Include all option**, allowing users to select some or all options presented at any time. The `datacenter` does not use either option, so you can only select one data center at a time.
|
||||
|
||||
##### datacenter variable
|
||||
|
||||
The query for this variable basically says, "Give me all the data centers that exist."
|
||||
|
||||
```
|
||||
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."
|
||||
|
||||
```
|
||||
SHOW TAG VALUES WITH KEY = "hostname" WHERE "datacenter" =~ /^$datacenter$/
|
||||
```
|
||||
|
||||
If the user selects `America`, then the query changes to:
|
||||
|
||||
```
|
||||
SHOW TAG VALUES WITH KEY = "hostname" WHERE "datacenter" =~ /^America/
|
||||
```
|
||||
|
||||
The query returns all servers associated with `America`, including `server1`, `server2`, and so on.
|
||||
|
||||
If the user selects `Europe`, then the query changes to:
|
||||
|
||||
```
|
||||
SHOW TAG VALUES WITH KEY = "hostname" WHERE "datacenter" =~ /^Europe/
|
||||
```
|
||||
|
||||
The query returns all servers associated with `Europe`, including `server3`, `server4`, and so on.
|
||||
|
||||
##### More variables
|
||||
|
||||
> **Note:** This example is theoretical. The InfluxDB server used in the example does not contain CPU metrics.
|
||||
|
||||
The dashboard stops at two levels, but you could keep going. For example, if you wanted to get CPU metrics for selected hosts, you could copy the `host` variable and extend the query so that it reads:
|
||||
|
||||
```
|
||||
SHOW TAG VALUES WITH KEY = "cpu" WHERE "datacenter" =~ /^$datacenter$/ AND "host" =~ /^$host$/
|
||||
```
|
||||
|
||||
This query basically says, "Show me the CPU metrics for the selected host."
|
||||
|
||||
Depending on what variable options the user selects, you could get queries like:
|
||||
|
||||
```bash
|
||||
SHOW TAG VALUES WITH KEY = "cpu" WHERE "datacenter" =~ /^America/ AND "host" =~ /^server2/
|
||||
SHOW TAG VALUES WITH KEY = "cpu" WHERE "datacenter" =~ /^Africa/ AND "host" =~ /^server/7/
|
||||
SHOW TAG VALUES WITH KEY = "cpu" WHERE "datacenter" =~ /^Europe/ AND "host" =~ /^server3+server4/
|
||||
```
|
||||
|
||||
### Best practices and tips
|
||||
|
||||
The following practices will make your dashboards and variables easier to use.
|
||||
|
||||
#### Creating new linked variables
|
||||
|
||||
- Chaining variables create parent/child dependencies. You can envision them as a ladder or a tree.
|
||||
- The easiest way to create a new chained variable is to copy the variable that you want to base the new one on. In the variable list, click the **Duplicate variable** icon to the right of the variable entry to create a copy. You can then add on to the query for the parent variable.
|
||||
- New variables created this way appear at the bottom of the list. You might need to drag it to a different position in the list to get it into a logical order.
|
||||
|
||||
#### Variable order
|
||||
|
||||
You can change the orders of variables in the dashboard variable list by clicking the up and down arrows on the right side of each entry. Grafana lists variable dropdowns left to right according to this list, with the variable at the top on the far left.
|
||||
|
||||
- List variables that do not have dependencies at the top, before their child variables.
|
||||
- Each variable should follow the one it is dependent on.
|
||||
- Remember there is no indication in the UI of which variables have dependency relationships. List the variables in a logical order to make it easy on other users (and yourself).
|
||||
|
||||
#### Complexity consideration
|
||||
|
||||
The more layers of dependency you have in variables, the longer it will take to update dashboards after you change variables.
|
||||
|
||||
For example, if you have a series of four linked variables (country, region, server, metric) and you change a root variable value (country), then Grafana must run queries for all the dependent variables before it updates the visualizations in the dashboard.
|
||||
|
||||
## Manage variables
|
||||
|
||||
The variables page lets you [add]({{< relref "./add-template-variables/" >}}) variables and manage existing variables. It also allows you to [inspect]({{< relref "inspect-variable/" >}}) variables and identify whether a variable is being referenced (or used) in other variables or dashboard.
|
||||
|
||||
**Move:** You can move a variable up or down the list using drag and drop.
|
||||
|
||||
**Clone:** To clone a variable, click the clone icon from the set of icons on the right. This creates a copy of the variable with the name of the original variable prefixed with `copy_of_`.
|
||||
|
||||
**Delete:** To delete a variable, click the trash icon from the set of icons on the right.
|
||||
|
||||
## Filter variables with regex
|
||||
|
||||
Using the Regex Query option, you filter the list of options returned by the variable query or modify the options returned.
|
||||
|
||||
This page shows how to use 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. For more information, refer to the Mozilla guide on [Regular expressions](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions).
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
### Filter and modify using named text and value capture groups
|
||||
|
||||
> **Note:** This feature is available in Grafana 7.4+.
|
||||
|
||||
Using named capture groups, you can capture separate 'text' and 'value' parts from the options returned by the variable query. This allows the variable drop-down list to contain a friendly name for each value that can be selected.
|
||||
|
||||
For example, when querying the `node_hwmon_chip_names` Prometheus metric, the `chip_name` is a lot friendlier that the `chip` value. So the following variable query result:
|
||||
|
||||
```text
|
||||
node_hwmon_chip_names{chip="0000:d7:00_0_0000:d8:00_0",chip_name="enp216s0f0np0"} 1
|
||||
node_hwmon_chip_names{chip="0000:d7:00_0_0000:d8:00_1",chip_name="enp216s0f0np1"} 1
|
||||
node_hwmon_chip_names{chip="0000:d7:00_0_0000:d8:00_2",chip_name="enp216s0f0np2"} 1
|
||||
node_hwmon_chip_names{chip="0000:d7:00_0_0000:d8:00_3",chip_name="enp216s0f0np3"} 1
|
||||
```
|
||||
|
||||
Passed through the following Regex:
|
||||
|
||||
```regex
|
||||
/chip_name="(?<text>[^"]+)|chip="(?<value>[^"]+)/g
|
||||
```
|
||||
|
||||
Would produce the following drop-down list:
|
||||
|
||||
```text
|
||||
Display Name Value
|
||||
------------ -------------------------
|
||||
enp216s0f0np0 0000:d7:00_0_0000:d8:00_0
|
||||
enp216s0f0np1 0000:d7:00_0_0000:d8:00_1
|
||||
enp216s0f0np2 0000:d7:00_0_0000:d8:00_2
|
||||
enp216s0f0np3 0000:d7:00_0_0000:d8:00_3
|
||||
```
|
||||
|
||||
**Note:** Only `text` and `value` capture group names are supported.
|
||||
@ -10,12 +10,12 @@ keywords:
|
||||
- template
|
||||
- variable
|
||||
title: Inspect variables
|
||||
weight: 125
|
||||
weight: 200
|
||||
---
|
||||
|
||||
# Inspect variables and their dependencies
|
||||
# Inspect variables
|
||||
|
||||
The variables page lets you easily identify whether a variable is being referenced (or used) in other variables or dashboard. In addition, you can also [add]({{< relref "variable-types/" >}}) variables and [manage]({{< relref "manage-variable/" >}}) existing variables from this page.
|
||||
The variables page lets you easily identify whether a variable is being referenced (or used) in other variables or dashboard. In addition, you can also [add]({{< relref "./add-template-variables/" >}}) and [manage](../manage-variable/) variables from this page.
|
||||
|
||||
> **Note:** This feature is available in Grafana 7.4 and later versions.
|
||||
|
||||
@ -1,6 +1,8 @@
|
||||
---
|
||||
aliases:
|
||||
- /docs/grafana/latest/variables/advanced-variable-format-options/
|
||||
- /docs/grafana/latest/reference/templating/
|
||||
- /docs/grafana/latest/variables/syntax/
|
||||
keywords:
|
||||
- grafana
|
||||
- templating
|
||||
@ -8,17 +10,35 @@ keywords:
|
||||
- guide
|
||||
- template
|
||||
- variable
|
||||
title: Advanced variable format options
|
||||
weight: 600
|
||||
title: Variable syntax
|
||||
weight: 300
|
||||
---
|
||||
|
||||
# Advanced variable format options
|
||||
# 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
|
||||
- `${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/" >}}) for more detail on all the formatting types.
|
||||
- `[[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.
|
||||
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/" >}}).
|
||||
|
||||
## 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
|
||||
### General syntax
|
||||
|
||||
Syntax: `${var_name:option}`
|
||||
|
||||
@ -28,7 +48,7 @@ If any invalid formatting option is specified, then `glob` is the default/fallba
|
||||
|
||||
An alternative syntax (that might be deprecated in the future) is `[[var_name:option]]`.
|
||||
|
||||
## CSV
|
||||
### CSV
|
||||
|
||||
Formats variables with multiple values as a comma-separated string.
|
||||
|
||||
@ -38,7 +58,7 @@ String to interpolate: '${servers:csv}'
|
||||
Interpolation result: 'test1,test2'
|
||||
```
|
||||
|
||||
## Distributed - OpenTSDB
|
||||
### Distributed - OpenTSDB
|
||||
|
||||
Formats variables with multiple values in custom format for OpenTSDB.
|
||||
|
||||
@ -48,7 +68,7 @@ String to interpolate: '${servers:distributed}'
|
||||
Interpolation result: 'test1,servers=test2'
|
||||
```
|
||||
|
||||
## Doublequote
|
||||
### Doublequote
|
||||
|
||||
Formats single- and multi-valued variables into a comma-separated string, escapes `"` in each value by `\"` and quotes each value with `"`.
|
||||
|
||||
@ -58,7 +78,7 @@ String to interpolate: '${servers:doublequote}'
|
||||
Interpolation result: '"test1","test2"'
|
||||
```
|
||||
|
||||
## Glob - Graphite
|
||||
### Glob - Graphite
|
||||
|
||||
Formats variables with multiple values into a glob (for Graphite queries).
|
||||
|
||||
@ -68,7 +88,7 @@ String to interpolate: '${servers:glob}'
|
||||
Interpolation result: '{test1,test2}'
|
||||
```
|
||||
|
||||
## JSON
|
||||
### JSON
|
||||
|
||||
Formats variables with multiple values as a comma-separated string.
|
||||
|
||||
@ -78,7 +98,7 @@ String to interpolate: '${servers:json}'
|
||||
Interpolation result: '["test1", "test2"]'
|
||||
```
|
||||
|
||||
## Lucene - Elasticsearch
|
||||
### Lucene - Elasticsearch
|
||||
|
||||
Formats variables with multiple values in Lucene format for Elasticsearch.
|
||||
|
||||
@ -88,7 +108,7 @@ String to interpolate: '${servers:lucene}'
|
||||
Interpolation result: '("test1" OR "test2")'
|
||||
```
|
||||
|
||||
## Percentencode
|
||||
### Percentencode
|
||||
|
||||
Formats single and multi valued variables for use in URL parameters.
|
||||
|
||||
@ -98,7 +118,7 @@ String to interpolate: '${servers:percentencode}'
|
||||
Interpolation result: 'foo%28%29bar%20BAZ%2Ctest2'
|
||||
```
|
||||
|
||||
## Pipe
|
||||
### Pipe
|
||||
|
||||
Formats variables with multiple values into a pipe-separated string.
|
||||
|
||||
@ -108,7 +128,7 @@ String to interpolate: '${servers:pipe}'
|
||||
Interpolation result: 'test1.|test2'
|
||||
```
|
||||
|
||||
## Raw
|
||||
### Raw
|
||||
|
||||
Turns off data source-specific formatting, such as single quotes in an SQL query.
|
||||
|
||||
@ -118,7 +138,7 @@ String to interpolate: '${var_name:raw}'
|
||||
Interpolation result: 'test.1,test2'
|
||||
```
|
||||
|
||||
## Regex
|
||||
### Regex
|
||||
|
||||
Formats variables with multiple values into a regex string.
|
||||
|
||||
@ -128,7 +148,7 @@ String to interpolate: '${servers:regex}'
|
||||
Interpolation result: '(test1\.|test2)'
|
||||
```
|
||||
|
||||
## Singlequote
|
||||
### Singlequote
|
||||
|
||||
Formats single- and multi-valued variables into a comma-separated string, escapes `'` in each value by `\'` and quotes each value with `'`.
|
||||
|
||||
@ -138,7 +158,7 @@ String to interpolate: '${servers:singlequote}'
|
||||
Interpolation result: "'test1','test2'"
|
||||
```
|
||||
|
||||
## Sqlstring
|
||||
### Sqlstring
|
||||
|
||||
Formats single- and multi-valued variables into a comma-separated string, escapes `'` in each value by `''` and quotes each value with `'`.
|
||||
|
||||
@ -148,7 +168,7 @@ String to interpolate: '${servers:sqlstring}'
|
||||
Interpolation result: "'test''1','test2'"
|
||||
```
|
||||
|
||||
## Text
|
||||
### Text
|
||||
|
||||
Formats single- and multi-valued variables into their text representation. For a single variable it will just return the text representation. For multi-valued variables it will return the text representation combined with `+`.
|
||||
|
||||
@ -158,7 +178,7 @@ String to interpolate: '${servers:text}'
|
||||
Interpolation result: "test1 + test2"
|
||||
```
|
||||
|
||||
## Query parameters
|
||||
### Query parameters
|
||||
|
||||
Formats single- and multi-valued variables into their query parameter representation. Example: `var-foo=value1&var-foo=value2`
|
||||
|
||||
@ -11,7 +11,7 @@ weight: 10
|
||||
|
||||
Instead of hard-coding server, application, and sensor names in your metric queries, you can use variables. The variables are listed as dropdown select boxes at the top of the dashboard. These dropdowns make it easy to change the display of data in your dashboard.
|
||||
|
||||
For an introduction to templating and template variables, refer to the [Templating]({{< relref "../../variables/" >}}) documentation.
|
||||
For an introduction to templating and template variables, refer to the [Templating]({{< relref "../../dashboards/variables" >}}) documentation.
|
||||
|
||||
## Query variable
|
||||
|
||||
@ -36,7 +36,7 @@ For details about the metrics CloudWatch provides, please refer to the [CloudWat
|
||||
|
||||
### Using variables in queries
|
||||
|
||||
Variables can be used in the variable form. Refer to the [variable syntax documentation]({{< relref "../../variables/syntax/" >}}).
|
||||
Variables can be used in the variable form. Refer to the [variable syntax documentation]({{< relref "../../dashboards/variables/variable-syntax" >}}).
|
||||
|
||||
## ec2_instance_attribute examples
|
||||
|
||||
|
||||
@ -20,7 +20,7 @@ weight: 2
|
||||
|
||||
Instead of hard-coding values for fields like resource group or resource name in your queries, you can use variables in their place to create more interactive, dynamic, and reusable dashboards.
|
||||
|
||||
Check out the [Templating]({{< relref "../../variables/" >}}) documentation for an introduction to the templating feature and the different
|
||||
Check out the [Templating]({{< relref "../../dashboards/variables" >}}) documentation for an introduction to the templating feature and the different
|
||||
types of template variables.
|
||||
|
||||
The Azure Monitor data source provides the following queries you can specify in the Query field in the Variable edit view
|
||||
|
||||
@ -128,7 +128,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
|
||||
being displayed in your dashboard.
|
||||
|
||||
Check out the [Templating]({{< relref "../variables/" >}}) documentation for an introduction to the templating feature and the different
|
||||
Check out the [Templating]({{< relref "../dashboards/variables/" >}}) documentation for an introduction to the templating feature and the different
|
||||
types of template variables.
|
||||
|
||||
### Query variable
|
||||
|
||||
@ -129,7 +129,7 @@ The option is called `cloud monitoring auto` and the defaults are:
|
||||
- 5m for time ranges >= 23 hours and < 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 time series panel. For more information about grafana auto, refer to the [interval variable]({{< relref "../../variables/variable-types/add-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 time series panel. For more information about grafana auto, refer to the [interval variable]({{< relref "../../dashboards/variables/add-template-variables/#add-an-interval-variable" >}}).
|
||||
|
||||
You can also choose fixed time intervals to group by, like `1h` or `1d`.
|
||||
|
||||
@ -252,7 +252,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
|
||||
being displayed in your dashboard.
|
||||
|
||||
Check out the [Templating]({{< relref "../../variables/" >}}) documentation for an introduction to the templating feature and the different
|
||||
Check out the [Templating]({{< relref "../../dashboards/variables/" >}}) documentation for an introduction to the templating feature and the different
|
||||
types of template variables.
|
||||
|
||||
### Query Variable
|
||||
@ -274,7 +274,7 @@ Variable of the type _Query_ allows you to query Google Cloud Monitoring for var
|
||||
|
||||
### Using variables in queries
|
||||
|
||||
Refer to the [variable syntax documentation]({{< relref "../../variables/syntax/" >}}).
|
||||
Refer to the [variable syntax documentation]({{< relref "../../dashboards/variables/variable-syntax" >}}).
|
||||
|
||||
## Annotations
|
||||
|
||||
|
||||
@ -117,7 +117,7 @@ Instead of hard-coding things like server, application, and sensor name in your
|
||||
Variables are shown as drop-down select boxes at the top of the dashboard. These dropdowns make it easy to change the data
|
||||
being displayed in your dashboard.
|
||||
|
||||
For more information, refer to [Variables and templates]({{< relref "../variables/" >}}).
|
||||
For more information, refer to [Variables and templates]({{< relref "../dashboards/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, use the Grafana functions `tags` and `tag_values`.
|
||||
|
||||
@ -212,7 +212,7 @@ Example of a tag expression with regex formatting and using the Equal Tilde oper
|
||||
server=~${servers:regex}
|
||||
```
|
||||
|
||||
For more information, refer to [Advanced variable format options]({{< relref "../variables/advanced-variable-format-options/" >}}).
|
||||
For more information, refer to [Advanced variable format options]({{< relref "../dashboards/variables/variable-syntax/#advanced-variable-format-options" >}}).
|
||||
|
||||
## Annotations
|
||||
|
||||
|
||||
@ -10,7 +10,7 @@ weight: 300
|
||||
|
||||
Instead of hard-coding things like server, application and sensor name in your metric queries you can use variables in their place.
|
||||
|
||||
For more information, refer to [Templates and variables]({{< relref "../../variables/" >}}).
|
||||
For more information, refer to [Templates and variables]({{< relref "../../dashboards/variables/" >}}).
|
||||
|
||||
## Using variables in InfluxDB queries
|
||||
|
||||
@ -35,7 +35,7 @@ Example dashboard:
|
||||
|
||||
## Query variables
|
||||
|
||||
If you add a query template variable, then you can write an InfluxDB exploration (metadata) query. These queries can return things like measurement names, key names or key values. For more information, refer to [Add query variable]({{< relref "../../variables/variable-types/add-query-variable/" >}}).
|
||||
If you add a query template variable, then you can write an InfluxDB exploration (metadata) query. These queries can return things like measurement names, key names or key values. For more information, refer to [Add query variable]({{< relref "../../dashboards/variables/add-template-variables/#add-a-query-variable" >}}).
|
||||
|
||||
For example, you can have a variable that contains all values for tag `hostname` if you specify a query like this in the query variable **Query**.
|
||||
|
||||
@ -45,7 +45,7 @@ SHOW TAG VALUES WITH KEY = "hostname"
|
||||
|
||||
## Chained or nested variables
|
||||
|
||||
You can also create nested variables, sometimes called [chained variables]({{< relref "../../variables/variable-types/chained-variables/" >}}).
|
||||
You can also create nested variables, sometimes called [chained variables]({{< relref "../../dashboards/variables/add-template-variables/#chained-variables" >}}).
|
||||
|
||||
For example, if you had another variable, for example `region`. Then you could have the hosts variable only show hosts from the current selected region with a query like this:
|
||||
|
||||
@ -65,4 +65,4 @@ If you have a variable with key names you can use this variable in a group by cl
|
||||
|
||||
InfluxDB supports the special `Ad hoc filters` variable type. This variable allows you to specify any number of key/value filters on the fly. These filters are automatically applied to all your InfluxDB queries.
|
||||
|
||||
For more information, refer to [Add ad hoc filters]({{< relref "../../variables/variable-types/add-ad-hoc-filters/" >}}).
|
||||
For more information, refer to [Add ad hoc filters]({{< relref "../../dashboards/variables/add-template-variables/#add-ad-hoc-filters" >}}).
|
||||
|
||||
@ -208,7 +208,7 @@ LogQL supports wrapping a log query with functions that allow for creating metri
|
||||
|
||||
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 "../variables/" >}}) documentation for an introduction to the templating feature and the different types of template variables.
|
||||
Check out the [Templating]({{< relref "../dashboards/variables" >}}) documentation for an introduction to the templating feature and the different types of template variables.
|
||||
|
||||
## Query variable
|
||||
|
||||
@ -227,7 +227,7 @@ Loki supports the special ad hoc filters variable type. It allows you to specify
|
||||
|
||||
### Using interval and range variables
|
||||
|
||||
You can use some global built-in variables in query variables; `$__interval`, `$__interval_ms`, `$__range`, `$__range_s` and `$__range_ms`. For more information, refer to [Global built-in variables]({{< relref "../variables/variable-types/global-variables/" >}}).
|
||||
You can use some global built-in variables in query variables; `$__interval`, `$__interval_ms`, `$__range`, `$__range_s` and `$__range_ms`. For more information, refer to [Global built-in variables]({{< relref "../dashboards/variables/add-template-variables/#global-variables/" >}}).
|
||||
|
||||
## Annotations
|
||||
|
||||
|
||||
@ -38,7 +38,7 @@ To access data source settings, hover your mouse over the **Configuration** (gea
|
||||
|
||||
### Min time interval
|
||||
|
||||
A lower limit for the [$__interval]({{< relref "../variables/variable-types/global-variables/#__interval" >}}) and [$__interval_ms]({{< relref "../variables/variable-types/global-variables/#__interval_ms" >}}) variables.
|
||||
A lower limit for the [$__interval]({{< relref "../dashboards/variables/add-template-variables/#__interval" >}}) and [$__interval_ms]({{< relref "../dashboards/variables/add-template-variables/#__interval_ms" >}}) variables.
|
||||
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
|
||||
number followed by a valid time identifier, e.g. `1m` (1 minute) or `30s` (30 seconds). The following time identifiers are supported:
|
||||
@ -271,7 +271,7 @@ Data frame result:
|
||||
|
||||
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 "../variables/" >}}) documentation for an introduction to the templating feature and the different types of template variables.
|
||||
Check out the [Templating]({{< relref "../dashboards/variables" >}}) documentation for an introduction to the templating feature and the different types of template variables.
|
||||
|
||||
### Query variable
|
||||
|
||||
@ -341,7 +341,7 @@ Grafana automatically creates a quoted, comma-separated string for multi-value v
|
||||
|
||||
`${servers:csv}`
|
||||
|
||||
Read more about variable formatting options in the [Variables]({{< relref "../variables/variable-types/#advanced-formatting-options" >}}) documentation.
|
||||
Read more about variable formatting options in the [Variables]({{< relref "../dashboards/variables/variable-syntax/#advanced-variable-format-options" >}}) documentation.
|
||||
|
||||
## Annotations
|
||||
|
||||
|
||||
@ -41,7 +41,7 @@ Grafana ships with a built-in MySQL data source plugin that allows you to query
|
||||
|
||||
### Min time interval
|
||||
|
||||
A lower limit for the [$__interval]({{< relref "../variables/variable-types/global-variables/#__interval" >}}) and [$__interval_ms]({{< relref "../variables/variable-types/global-variables/#__interval_ms" >}}) variables.
|
||||
A lower limit for the [$__interval]({{< relref "../dashboards/variables/add-template-variables/#__interval" >}}) and [$__interval_ms]({{< relref "../dashboards/variables/add-template-variables/#__interval_ms" >}}) variables.
|
||||
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
|
||||
number followed by a valid time identifier, e.g. `1m` (1 minute) or `30s` (30 seconds). The following time identifiers are supported:
|
||||
@ -283,7 +283,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.
|
||||
|
||||
Check out the [Templating]({{< relref "../variables/" >}}) documentation for an introduction to the templating feature and the different types of template variables.
|
||||
Check out the [Templating]({{< relref "../dashboards/variables/" >}}) documentation for an introduction to the templating feature and the different types of template variables.
|
||||
|
||||
### Query Variable
|
||||
|
||||
@ -378,7 +378,7 @@ Grafana automatically creates a quoted, comma-separated string for multi-value v
|
||||
|
||||
`${servers:csv}`
|
||||
|
||||
Read more about variable formatting options in the [Variables]({{< relref "../variables/#advanced-formatting-options" >}}) documentation.
|
||||
Read more about variable formatting options in the [Variables]({{< relref "../dashboards/variables/variable-syntax/#advanced-variable-format-options" >}}) documentation.
|
||||
|
||||
## Annotations
|
||||
|
||||
|
||||
@ -51,7 +51,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
|
||||
being displayed in your dashboard.
|
||||
|
||||
Check out the [Templating]({{< relref "../variables/" >}}) documentation for an introduction to the templating feature and the different
|
||||
Check out the [Templating]({{< relref "../dashboards/variables/" >}}) documentation for an introduction to the templating feature and the different
|
||||
types of template variables.
|
||||
|
||||
### Query variable
|
||||
|
||||
@ -38,7 +38,7 @@ To access PostgreSQL settings, hover your mouse over the **Configuration** (gear
|
||||
|
||||
### Min time interval
|
||||
|
||||
A lower limit for the [$__interval]({{< relref "../variables/variable-types/global-variables/#__interval" >}}) and [$__interval_ms]({{< relref "../variables/variable-types/global-variables/#__interval_ms" >}}) variables.
|
||||
A lower limit for the [$__interval]({{< relref "../dashboards/variables/add-template-variables/#__interval" >}}) and [$__interval_ms]({{< relref "../dashboards/variables/add-template-variables/#__interval_ms" >}}) variables.
|
||||
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
|
||||
number followed by a valid time identifier, e.g. `1m` (1 minute) or `30s` (30 seconds). The following time identifiers are supported:
|
||||
@ -283,7 +283,7 @@ Data frame result:
|
||||
|
||||
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.
|
||||
|
||||
Refer to [Templates and variables]({{< relref "../variables/" >}}) for an introduction to the templating feature and the different types of template variables.
|
||||
Refer to [Templates and variables]({{< relref "../dashboards/variables" >}}) for an introduction to the templating feature and the different types of template variables.
|
||||
|
||||
### Query variable
|
||||
|
||||
@ -376,7 +376,7 @@ Grafana automatically creates a quoted, comma-separated string for multi-value v
|
||||
|
||||
`${servers:csv}`
|
||||
|
||||
Read more about variable formatting options in the [Variables]({{< relref "../variables/#advanced-formatting-options" >}}) documentation.
|
||||
Read more about variable formatting options in the [Variables]({{< relref "../dashboards/variables/variable-syntax/#advanced-variable-format-options" >}}) documentation.
|
||||
|
||||
## Annotations
|
||||
|
||||
|
||||
@ -168,7 +168,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
|
||||
being displayed in your dashboard.
|
||||
|
||||
Check out the [Templating]({{< relref "../variables/" >}}) documentation for an introduction to the templating feature and the different
|
||||
Check out the [Templating]({{< relref "../dashboards/variables" >}}) documentation for an introduction to the templating feature and the different
|
||||
types of template variables.
|
||||
|
||||
### Query variable
|
||||
@ -190,7 +190,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, for example, `$__interval`, `$__interval_ms`, `$__range`, `$__range_s` and `$__range_ms`. See [Global built-in variables]({{< relref "../variables/variable-types/global-variables/" >}}) for more information. They are convenient to use in conjunction with the `query_result` function when you need to filter variable queries since the `label_values` function doesn't support queries.
|
||||
You can use some global built-in variables in query variables, for example, `$__interval`, `$__interval_ms`, `$__range`, `$__range_s` and `$__range_ms`. See [Global built-in variables]({{< relref "../dashboards/variables/add-template-variables/#global-variables" >}}) for more information. They are convenient to use in conjunction with the `query_result` function when you need to filter variable queries since the `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.
|
||||
|
||||
@ -235,7 +235,7 @@ options are enabled, Grafana converts the labels from plain text to a regex comp
|
||||
|
||||
### Ad hoc filters variable
|
||||
|
||||
Prometheus supports the special [ad hoc filters]({{< relref "../variables/variable-types/add-ad-hoc-filters/" >}}) variable type. It allows you to specify any number of label/value filters on the fly. These filters are automatically
|
||||
Prometheus supports the special [ad hoc filters]({{< relref "../dashboards/variables/add-template-variables/#add-ad-hoc-filters" >}}) variable type. It allows you to specify any number of label/value filters on the fly. These filters are automatically
|
||||
applied to all your Prometheus queries.
|
||||
|
||||
## Annotations
|
||||
|
||||
@ -6,7 +6,7 @@ title: Add support for variables in plugins
|
||||
|
||||
# Add support for variables in plugins
|
||||
|
||||
Variables are placeholders for values, and can be used to create things like templated queries and dashboard or panel links. For more information on variables, refer to [Templates and variables]({{< relref "../../variables/" >}}).
|
||||
Variables are placeholders for values, and can be used to create things like templated queries and dashboard or panel links. For more information on variables, refer to [Templates and variables]({{< relref "../../dashboards/variables/" >}}).
|
||||
|
||||
This guide explains how to leverage template variables in your panel plugins and data source plugins.
|
||||
|
||||
@ -62,7 +62,7 @@ For data sources, you need to use the getTemplateSrv, which returns an instance
|
||||
|
||||
## Format multi-value variables
|
||||
|
||||
When a user selects multiple values for variable, the value of the interpolated variable depends on the [variable format](https://grafana.com/docs/grafana/next/variables/advanced-variable-format-options/).
|
||||
When a user selects multiple values for variable, the value of the interpolated variable depends on the [variable format]({{< relref "../../dashboards/variables/variable-syntax/#advanced-variable-format-options" >}}).
|
||||
|
||||
A data source can define the default format option when no format is specified by adding a third argument to the interpolation function.
|
||||
|
||||
@ -78,7 +78,7 @@ Now, when users write `$service`, the query looks like this:
|
||||
SELECT * FROM services WHERE id IN (admin,auth,billing)
|
||||
```
|
||||
|
||||
For more information on the available variable formats, refer to [Advanced variable format options]({{< relref "../../variables/advanced-variable-format-options/" >}}).
|
||||
For more information on the available variable formats, refer to [Advanced variable format options]({{< relref "../../dashboards/variables/variable-syntax/#advanced-variable-format-options" >}}).
|
||||
|
||||
## Set a variable from your plugin
|
||||
|
||||
@ -101,7 +101,7 @@ locationService.partial({ 'var-service': 'billing' }, true);
|
||||
|
||||
## Add support for query variables to your data source
|
||||
|
||||
[Query variables]({{< relref "../../variables/variable-types/add-query-variable/" >}}) is a type of variable that allows you to query a data source for the values. By adding support for query variables to your data source plugin, users can create dynamic dashboards based on data from your data source.
|
||||
[Query variables]({{< relref "../../dashboards/variables/add-template-variables/#add-a-query-variable" >}}) is a type of variable that allows you to query a data source for the values. By adding support for query variables to your data source plugin, users can create dynamic dashboards based on data from your data source.
|
||||
|
||||
Let's start by defining a query model for the variable query.
|
||||
|
||||
@ -199,4 +199,4 @@ Let's create a custom query editor to allow the user to edit the query model.
|
||||
.setVariableQueryEditor(VariableQueryEditor);
|
||||
```
|
||||
|
||||
That's it! You can now try out the plugin by adding a [query variable]({{< relref "../../variables/variable-types/add-query-variable/" >}}) to your dashboard.
|
||||
That's it! You can now try out the plugin by adding a [query variable]({{< relref "../../dashboards/variables/add-template-variables/#add-a-query-variable" >}}) to your dashboard.
|
||||
|
||||
@ -62,7 +62,7 @@ Grafana Enterprise adds the following features:
|
||||
- [Data source permissions]({{< relref "../administration/data-source-management/" >}}) to restrict query access to specific teams and users.
|
||||
- [Data source query caching]({{< relref "query-caching/" >}}) to temporarily store query results in Grafana to reduce data source load and rate limiting.
|
||||
- [Reporting]({{< relref "../dashboards/create-reports/" >}}) to generate a PDF report from any dashboard and set up a schedule to have it emailed to whoever you choose.
|
||||
- [Export dashboard as PDF]({{< relref "../dashboards/create-reports/#export-dashboard-as-pdf" >}})
|
||||
- [Export dashboard as PDF]({{< relref "../dashboards/share-dashboards-panels/#export-dashboard-as-pdf" >}})
|
||||
- [Custom branding]({{< relref "../setup-grafana/configure-grafana/configure-custom-branding/" >}}) to customize Grafana from the brand and logo to the footer links.
|
||||
- [Usage insights]({{< relref "../dashboards/assess-dashboard-usage/" >}}) to understand how your Grafana instance is used.
|
||||
- [Vault integration]({{< relref "../setup-grafana/configure-security/configure-database-encryption/integrate-with-hashicorp-vault/" >}}) to manage your configuration or provisioning secrets with Vault.
|
||||
|
||||
@ -33,7 +33,7 @@ This feature, which shows up as a graph marker in Grafana, is useful for correla
|
||||
|
||||
## Dashboard variables
|
||||
|
||||
[Template variables]({{< relref "../variables/" >}}) 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 "../dashboards/variables" >}}) 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.
|
||||
|
||||
|
||||
@ -53,7 +53,7 @@ Grafana Enterprise adds the following features:
|
||||
- [Data source permissions]({{< relref "../administration/data-source-management#data-source-permissions" >}}) to restrict query access to specific teams and users.
|
||||
- [Data source query caching]({{< relref "../enterprise/query-caching.md" >}}) to temporarily store query results in Grafana to reduce data source load and rate limiting.
|
||||
- [Reporting]({{< relref "../dashboards/create-reports/" >}}) to generate a PDF report from any dashboard and set up a schedule to have it emailed to whomever you choose.
|
||||
- [Export dashboard as PDF]({{< relref "../share-dashboards-panels/#export-dashboard-as-pdf" >}})
|
||||
- [Export dashboard as PDF]({{< relref "../dashboards/share-dashboards-panels/#export-dashboard-as-pdf" >}})
|
||||
- [Custom branding]({{< relref "../setup-grafana/configure-grafana/configure-custom-branding/" >}}) to customize Grafana from the brand and logo to the footer links.
|
||||
- [Usage insights]({{< relref "../dashboards/assess-dashboard-usage/" >}}) to understand how your Grafana instance is used.
|
||||
- [Vault integration]({{< relref "../setup-grafana/configure-security/configure-database-encryption/encrypt-secrets-using-hashicorp-key-vault/" >}}) to manage your configuration or provisioning secrets with Vault.
|
||||
|
||||
@ -30,14 +30,14 @@ To see a list of available variables, type `$` in the data link **URL** field to
|
||||
|
||||
> **Note:** These variables changed in 6.4 so if you have an older version of Grafana, then use the version picker to select docs for an older version of Grafana.
|
||||
|
||||
You can also use template variables in your data links URLs, refer to [Templates and variables]({{< relref "../../variables/" >}}) for more information on template variables.
|
||||
You can also use template variables in your data links URLs, refer to [Templates and variables]({{< relref "../../dashboards/variables/" >}}) for more information on template variables.
|
||||
|
||||
## Time range panel variables
|
||||
|
||||
These variables allow you to include the current time range in the data link URL.
|
||||
|
||||
- `__url_time_range` - current dashboard's time range (i.e. `?from=now-6h&to=now`)
|
||||
- `$__from and $__to` - For more information, refer to [Global variables]({{< relref "../../variables/variable-types/global-variables/#__from-and-__to" >}}).
|
||||
- `$__from and $__to` - For more information, refer to [Global variables]({{< relref "../../dashboards/variables/add-template-variables/#__from-and-__to" >}}).
|
||||
|
||||
## Series variables
|
||||
|
||||
|
||||
@ -56,7 +56,7 @@ Add a title and description to a panel to share with users any important informa
|
||||
|
||||
Text entered in this field appears in a tooltip in the upper-left corner of the panel.
|
||||
|
||||
You can use [variables you have defined]({{< relref "../../variables/" >}}) in the **Title** and **Description** field, but not [global variables]({{< relref "../../variables/variable-types/global-variables/" >}}).
|
||||
You can use [variables you have defined]({{< relref "../../dashboards/variables" >}}) in the **Title** and **Description** field, but not [global variables]({{< relref "../../dashboards/variables/add-template-variables/#global-variables" >}}).
|
||||
|
||||
|
||||
|
||||
|
||||
@ -7,8 +7,10 @@ title: Configure standard options
|
||||
menuTitle: Configure standard options
|
||||
weight: 40
|
||||
keywords:
|
||||
- xxx
|
||||
- xxx
|
||||
- panel
|
||||
- dasboard
|
||||
- standard
|
||||
- option
|
||||
---
|
||||
|
||||
# Configure standard options
|
||||
@ -83,7 +85,7 @@ To change this setting, type a number in the field and then click outside the fi
|
||||
|
||||
### Display name
|
||||
|
||||
Lets you set the display title of all fields. You can use [variables]({{< relref "../../variables/" >}}) in the field title.
|
||||
Lets you set the display title of all fields. You can use [variables]({{< relref "../../dashboards/variables/" >}}) in the field title.
|
||||
|
||||
When multiple stats, fields, or series are shown, this field controls the title in each stat. You can use expressions like `${__field.name}` to use only the series name or the field name in title.
|
||||
|
||||
|
||||
@ -31,7 +31,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/variable-types/global-variables/" >}}).
|
||||
For more information, refer to [Global variables]({{< relref "../dashboards/variables/add-template-variables/#global-variables" >}}).
|
||||
|
||||
- **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.
|
||||
|
||||
|
||||
@ -1,118 +0,0 @@
|
||||
---
|
||||
aliases:
|
||||
- /docs/grafana/latest/variables/filter-variables-with-regex/
|
||||
keywords:
|
||||
- grafana
|
||||
- templating
|
||||
- documentation
|
||||
- guide
|
||||
- template
|
||||
- variable
|
||||
title: Filter variables with regex
|
||||
weight: 700
|
||||
---
|
||||
|
||||
# Filter variables with regex
|
||||
|
||||
Using the Regex Query option, you filter the list of options returned by the variable query or modify the options returned.
|
||||
|
||||
This page shows how to use 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. For more information, refer to the Mozilla guide on [Regular expressions](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions).
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
## Filter and modify using named text and value capture groups
|
||||
|
||||
> **Note:** This feature is available in Grafana 7.4+.
|
||||
|
||||
Using named capture groups, you can capture separate 'text' and 'value' parts from the options returned by the variable query. This allows the variable drop-down list to contain a friendly name for each value that can be selected.
|
||||
|
||||
For example, when querying the `node_hwmon_chip_names` Prometheus metric, the `chip_name` is a lot friendlier that the `chip` value. So the following variable query result:
|
||||
|
||||
```text
|
||||
node_hwmon_chip_names{chip="0000:d7:00_0_0000:d8:00_0",chip_name="enp216s0f0np0"} 1
|
||||
node_hwmon_chip_names{chip="0000:d7:00_0_0000:d8:00_1",chip_name="enp216s0f0np1"} 1
|
||||
node_hwmon_chip_names{chip="0000:d7:00_0_0000:d8:00_2",chip_name="enp216s0f0np2"} 1
|
||||
node_hwmon_chip_names{chip="0000:d7:00_0_0000:d8:00_3",chip_name="enp216s0f0np3"} 1
|
||||
```
|
||||
|
||||
Passed through the following Regex:
|
||||
|
||||
```regex
|
||||
/chip_name="(?<text>[^"]+)|chip="(?<value>[^"]+)/g
|
||||
```
|
||||
|
||||
Would produce the following drop-down list:
|
||||
|
||||
```text
|
||||
Display Name Value
|
||||
------------ -------------------------
|
||||
enp216s0f0np0 0000:d7:00_0_0000:d8:00_0
|
||||
enp216s0f0np1 0000:d7:00_0_0000:d8:00_1
|
||||
enp216s0f0np2 0000:d7:00_0_0000:d8:00_2
|
||||
enp216s0f0np3 0000:d7:00_0_0000:d8:00_3
|
||||
```
|
||||
|
||||
**Note:** Only `text` and `value` capture group names are supported.
|
||||
@ -1,33 +0,0 @@
|
||||
---
|
||||
aliases:
|
||||
- /docs/grafana/latest/variables/formatting-multi-value-variables/
|
||||
title: Multi-value variables
|
||||
weight: 600
|
||||
---
|
||||
|
||||
# Multi-value variables
|
||||
|
||||
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:** The **Custom all value** option on the variable must be blank for Grafana to format all values into a single string. If leave it blank, then the Grafana concatenates (adds together) all the values in the query. Something like `value1,value2,value3`. If a custom `all` value is used, then instead the value will be something like `*` or `all`.
|
||||
|
||||
## Multi-value variables with a Graphite data source
|
||||
|
||||
Graphite 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_.
|
||||
|
||||
## Multi-value variables with a Prometheus or InfluxDB data source
|
||||
|
||||
InfluxDB and Prometheus use 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.
|
||||
|
||||
## Multi-value variables with an Elastic data source
|
||||
|
||||
Elasticsearch uses lucene query syntax, so the same variable would be formatted as `("host1" OR "host2" OR "host3")`. In this case, every value must be escaped so that the value only contains lucene control words and quotation marks.
|
||||
|
||||
## Troubleshoot multi-value variables
|
||||
|
||||
Automatic escaping and formatting can cause problems and it can be tricky to grasp the logic 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, then you must do one of the following:
|
||||
|
||||
- Turn off the **Multi-value** or **Include All option** options.
|
||||
- Use the [raw variable format]({{< relref "advanced-variable-format-options/#raw" >}}).
|
||||
@ -1,30 +0,0 @@
|
||||
---
|
||||
aliases:
|
||||
- /docs/grafana/latest/reference/templating/
|
||||
- /docs/grafana/latest/variables/manage-variable/
|
||||
keywords:
|
||||
- grafana
|
||||
- templating
|
||||
- documentation
|
||||
- guide
|
||||
- template
|
||||
- variable
|
||||
title: Manage variables
|
||||
weight: 120
|
||||
---
|
||||
|
||||
# Manage variables
|
||||
|
||||
The variables page lets you [add]({{< relref "variable-types/" >}}) variables and manage existing variables. It also allows you to [inspect]({{< relref "inspect-variable/" >}}) variables and identify whether a variable is being referenced (or used) in other variables or dashboard.
|
||||
|
||||
## Move
|
||||
|
||||
You can move a variable up or down the list using drag and drop.
|
||||
|
||||
## Clone
|
||||
|
||||
To clone a variable, click the clone icon from the set of icons on the right. This creates a copy of the variable with the name of the original variable prefixed with `copy_of_`.
|
||||
|
||||
## Delete
|
||||
|
||||
To delete a variable, click the trash icon from the set of icons on the right.
|
||||
@ -1,32 +0,0 @@
|
||||
---
|
||||
aliases:
|
||||
- /docs/grafana/latest/reference/templating/
|
||||
- /docs/grafana/latest/variables/syntax/
|
||||
keywords:
|
||||
- grafana
|
||||
- templating
|
||||
- documentation
|
||||
- guide
|
||||
- template
|
||||
- variable
|
||||
title: Variable syntax
|
||||
weight: 100
|
||||
---
|
||||
|
||||
# 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
|
||||
- `${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/" >}}) for more detail on all the formatting types.
|
||||
- `[[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.
|
||||
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/" >}}).
|
||||
@ -1,28 +0,0 @@
|
||||
---
|
||||
aliases:
|
||||
- /docs/grafana/latest/variables/variable-examples/
|
||||
keywords:
|
||||
- grafana
|
||||
- templating
|
||||
- documentation
|
||||
- guide
|
||||
- template
|
||||
- variable
|
||||
title: Variable examples
|
||||
weight: 200
|
||||
---
|
||||
|
||||
# Variable examples
|
||||
|
||||
This page contains links to dashboards in Grafana Play with examples of template variables.
|
||||
|
||||
- [Elasticsearch Metrics](https://play.grafana.org/d/000000014/elasticsearch-metrics?orgId=1) - Uses ad hoc filters, global variables, and a custom variable.
|
||||
- [Graphite Templated Nested](https://play.grafana.org/d/000000056/graphite-templated-nested?orgId=1) - Uses query variables, chained query variables, an interval variable, and a repeated panel.
|
||||
- [Influx DB Group By Variable](https://play.grafana.org/d/000000137/influxdb-group-by-variable?orgId=1) - Query variable, panel uses the variable results to group the metric data.
|
||||
- [InfluxDB Raw Query Template Var](https://play.grafana.org/d/000000083/influxdb-raw-query-template-var?orgId=1) - Uses query variables, chained query variables, and an interval variable.
|
||||
- [InfluxDB Server Monitoring](https://play.grafana.org/d/AAy9r_bmk/influxdb-server-monitoring?orgId=1) - Uses query variables, chained query variables, an interval variable, and an ad hoc filter.
|
||||
- [Prometheus templating](https://play.grafana.org/d/000000063/prometheus-templating?orgId=1) - Uses chained query variables.
|
||||
- [Template Redux](https://play.grafana.org/d/p-k6QtkGz/template-redux?orgId=1) - Uses query variables, chained query variables, ad hoc filters, an interval variable, a text box variable, a custom variable, and a data source variable.
|
||||
- [Templating, repeated panels](https://play.grafana.org/d/000000025/templating-repeated-panels?orgId=1) - Two sets of repeated panels use query variables.
|
||||
- [Templating showcase](https://play.grafana.org/d/000000091/templating-showcase?orgId=1) - Uses custom, query, chained query, and data source variables.
|
||||
- [Templating value groups](https://play.grafana.org/d/000000024/templating-value-groups?orgId=1) - Uses query variable with value groups.
|
||||
@ -1,28 +0,0 @@
|
||||
---
|
||||
aliases:
|
||||
- /docs/grafana/latest/variables/variable-selection-options/
|
||||
title: Variable selection options
|
||||
weight: 400
|
||||
---
|
||||
|
||||
# Configure 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/" >}}).
|
||||
|
||||
## 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.
|
||||
@ -1,22 +0,0 @@
|
||||
---
|
||||
aliases:
|
||||
- /docs/grafana/latest/variables/variable-types/
|
||||
title: Add variables
|
||||
weight: 140
|
||||
---
|
||||
|
||||
# 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/" >}}). |
|
||||
| Custom | Define the variable options manually using a comma-separated list. [Add a custom variable]({{< relref "add-custom-variable/" >}}). |
|
||||
| Text box | Display a free text input field with an optional default value. [Add a text box variable]({{< relref "add-text-box-variable/" >}}). |
|
||||
| Constant | Define a hidden constant. [Add a constant variable]({{< relref "add-constant-variable/" >}}). |
|
||||
| Data source | Quickly change the data source for an entire dashboard. [Add a data source variable]({{< relref "add-data-source-variable/" >}}). |
|
||||
| Interval | Interval variables represent time spans. [Add an interval variable]({{< relref "add-interval-variable/" >}}). |
|
||||
| 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/" >}}). |
|
||||
| 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/" >}}). |
|
||||
@ -1,34 +0,0 @@
|
||||
---
|
||||
aliases:
|
||||
- /docs/grafana/latest/variables/add-ad-hoc-filters/
|
||||
- /docs/grafana/latest/variables/variable-types/add-ad-hoc-filters/
|
||||
title: Add ad hoc filters
|
||||
weight: 700
|
||||
---
|
||||
|
||||
# Add ad hoc filters
|
||||
|
||||
_Ad hoc filters_ allow you to add key/value filters that are automatically added to all metric queries that use the specified data source. Unlike other variables, you do not use ad hoc filters in queries. Instead, you use ad hoc filters to write filters for existing queries.
|
||||
|
||||
> **Note:** Ad hoc filter variables only work with Prometheus, Loki, InfluxDB, and Elasticsearch data sources.
|
||||
|
||||
## 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 **Ad hoc filters**.
|
||||
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 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 "../../datasources/add-a-data-source/" >}}).
|
||||
1. Click **Add** to add the variable to the dashboard.
|
||||
|
||||
## Create ad hoc filters
|
||||
|
||||
Ad hoc filters are one of the most complex and flexible variable options available. Instead of a regular list of variable options, this variable allows you to build a dashboard-wide ad hoc query. Filters you apply in this manner are applied to all panels on the dashboard.
|
||||
@ -1,33 +0,0 @@
|
||||
---
|
||||
aliases:
|
||||
- /docs/grafana/latest/variables/add-constant-variable/
|
||||
- /docs/grafana/latest/variables/variable-types/add-constant-variable/
|
||||
title: Add a constant variable
|
||||
weight: 400
|
||||
---
|
||||
|
||||
# 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/#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.
|
||||
@ -1,32 +0,0 @@
|
||||
---
|
||||
aliases:
|
||||
- /docs/grafana/latest/variables/add-custom-variable/
|
||||
- /docs/grafana/latest/variables/variable-types/add-custom-variable/
|
||||
title: Add a custom variable
|
||||
weight: 200
|
||||
---
|
||||
|
||||
# Add a custom variable
|
||||
|
||||
Use a _custom_ variable for a value that does not change, such as a number or a string.
|
||||
|
||||
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/" >}}) 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 key/value pairs separated by a space and a colon. For example, `key1 : value1,key2 : value2`.
|
||||
1. (optional) Enter [Selection Options]({{< relref "../variable-selection-options/" >}}).
|
||||
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,31 +0,0 @@
|
||||
---
|
||||
aliases:
|
||||
- /docs/grafana/latest/variables/add-data-source-variable/
|
||||
- /docs/grafana/latest/variables/variable-types/add-data-source-variable/
|
||||
title: Add a data source variable
|
||||
weight: 500
|
||||
---
|
||||
|
||||
# Add a data source variable
|
||||
|
||||
_Data source_ variables allow you to quickly change the data source for an entire dashboard. They are useful if you have multiple instances of a data source, perhaps in different environments.
|
||||
|
||||
## 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 **Datasource**.
|
||||
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 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 "../../datasources/add-a-data-source/" >}}).
|
||||
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/" >}}).
|
||||
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,48 +0,0 @@
|
||||
---
|
||||
aliases:
|
||||
- /docs/grafana/latest/variables/add-interval-variable/
|
||||
- /docs/grafana/latest/variables/variable-types/add-interval-variable/
|
||||
title: Add an interval variable
|
||||
weight: 600
|
||||
---
|
||||
|
||||
# Add an interval variable
|
||||
|
||||
Use an _interval_ variable to represents time spans such as `1m`,`1h`, `1d`. You can think of them as a dashboard-wide "group by time" command. Interval variables change how the data is grouped in the visualization. You can also use the Auto Option to return a set number of data points per time span.
|
||||
|
||||
You can use an interval variable as a parameter to group by time (for InfluxDB), date histogram interval (for Elasticsearch), or as a summarize function parameter (for Graphite).
|
||||
|
||||
## 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 **Interval**.
|
||||
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 Interval Options
|
||||
|
||||
1. In the **Values** field, enter the time range intervals that you want to appear in the variable drop-down list. The following time units are supported: `s (seconds)`, `m (minutes)`, `h (hours)`, `d (days)`, `w (weeks)`, `M (months)`, and `y (years)`. You can also accept or edit the default values: `1m,10m,30m,1h,6h,12h,1d,7d,14d,30d`.
|
||||
1. (optional) Turn on the **Auto Option** if you want to add the `auto` option to the list. This option allows you to specify how many times the current time range should be divided to calculate the current `auto` time span. If you turn it on, then two more options appear:
|
||||
- **Step count -** Select the number of times the current time range will be divided to calculate the value, similar to the **Max data points** query option. For example, if the current visible time range is 30 minutes, then the `auto` interval groups the data into 30 one-minute increments. The default value is 30 steps.
|
||||
- **Min Interval -** The minimum threshold below which the step count intervals will not divide the time. To continue the 30 minute example, if the minimum interval is set to 2m, then Grafana would group the data into 15 two-minute increments.
|
||||
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.
|
||||
|
||||
## Interval variable examples
|
||||
|
||||
Example using the template variable `myinterval` in a Graphite function:
|
||||
|
||||
```
|
||||
summarize($myinterval, sum, false)
|
||||
```
|
||||
|
||||
A more complex Graphite example, from the [Graphite Template Nested Requests panel](https://play.grafana.org/d/000000056/graphite-templated-nested?editPanel=2&orgId=1):
|
||||
|
||||
```
|
||||
groupByNode(summarize(movingAverage(apps.$app.$server.counters.requests.count, 5), '$interval', 'sum', false), 2, 'sum')
|
||||
```
|
||||
@ -1,46 +0,0 @@
|
||||
---
|
||||
aliases:
|
||||
- /docs/grafana/latest/variables/add-query-variable/
|
||||
- /docs/grafana/latest/variables/variable-types/add-query-variable/
|
||||
title: Add a query variable
|
||||
weight: 100
|
||||
---
|
||||
|
||||
# Add a query variable
|
||||
|
||||
Query variables allow you to write a data source query that can return a list of metric names, tag values, or keys. For example, a query variable might return a list of server names, sensor IDs, or data centers. The variable values change as they dynamically fetch options with a data source query.
|
||||
|
||||
Query variables are generally only supported for strings. If your query return numbers or any other data type, you may need to convert them to strings in order to use them as variables. For the Azure data source, for example, you can use the [tostring](https://docs.microsoft.com/en-us/azure/data-explorer/kusto/query/tostringfunction) function for this purpose.
|
||||
|
||||
Query expressions can contain references to other variables and in effect create linked variables. Grafana detects this and automatically refreshes a variable when one of its linked variables change.
|
||||
|
||||
## Query expressions
|
||||
|
||||
Query expressions are different for each data source. For more information, refer to the documentation for your [data source]({{< relref "../../datasources/" >}}).
|
||||
|
||||
## 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 **Query**.
|
||||
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 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 "../../datasources/add-a-data-source/" >}}).
|
||||
1. In the **Refresh** list, select when the variable should update options.
|
||||
- **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.
|
||||
- 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/" >}}).
|
||||
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/" >}}).
|
||||
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,29 +0,0 @@
|
||||
---
|
||||
aliases:
|
||||
- /docs/grafana/latest/variables/add-text-box-variable/
|
||||
- /docs/grafana/latest/variables/variable-types/add-text-box-variable/
|
||||
title: Add a text box variable
|
||||
weight: 300
|
||||
---
|
||||
|
||||
# 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.
|
||||
@ -1,181 +0,0 @@
|
||||
---
|
||||
aliases:
|
||||
- /docs/grafana/latest/variables/chained-variables/
|
||||
- /docs/grafana/latest/variables/variable-types/chained-variables/
|
||||
keywords:
|
||||
- grafana
|
||||
- templating
|
||||
- variable
|
||||
- nested
|
||||
- chained
|
||||
- linked
|
||||
title: Chained variables
|
||||
weight: 800
|
||||
---
|
||||
|
||||
# Chained variables
|
||||
|
||||
_Chained variables_, also called _linked variables_ or _nested variables_, are query variables with one or more other variables in their variable query. This page explains how chained variables work and provides links to example dashboards that use chained variables.
|
||||
|
||||
Chained variable queries are different for every data source, but the premise is the same for all. You can use chained variable queries in any data source that allows them.
|
||||
|
||||
Extremely complex linked templated dashboards are possible, 5 or 10 levels deep. Technically, there is no limit to how deep or complex you can go, but the more links you have, the greater the query load.
|
||||
|
||||
## Grafana Play dashboard examples
|
||||
|
||||
The following Grafana Play dashboards contain fairly simple chained variables, only two layers deep. To view the variables and their settings, click **Dashboard settings** (gear icon) and then click **Variables**. Both examples are expanded in the following section.
|
||||
|
||||
- [Graphite Templated Nested](https://play.grafana.org/d/000000056/graphite-templated-nested?orgId=1&var-app=country&var-server=All&var-interval=1h)
|
||||
- [InfluxDB Templated](https://play.grafana.org/d/000000002/influxdb-templated?orgId=1)
|
||||
|
||||
## Examples explained
|
||||
|
||||
Variables are useful to reuse dashboards, dynamically change what is shown in dashboards. Chained variables are especially useful to filter what you see.
|
||||
|
||||
Create parent/child relationship in variable, sort of a tree structure where you can select different levels of filters.
|
||||
|
||||
The following sections explain the linked examples in the dashboards above in depth and builds on them. While the examples are data source-specific, the concepts can be applied broadly.
|
||||
|
||||
### Graphite example
|
||||
|
||||
In this example, you have several applications. Each application has a different subset of servers. It is based on the [Graphite Templated Nested](https://play.grafana.org/d/000000056/graphite-templated-nested?orgId=1&var-app=country&var-server=All&var-interval=1h).
|
||||
|
||||
Now, you could make separate variables for each metric source, but then you have to know which server goes with which app. A better solution is to use one variable to filter another. In this example, when the user changes the value of the `app` variable, it changes the dropdown options returned by the `server` variable. Both variables use the **Multi-value** option and **Include all option**, allowing users to select some or all options presented at any time.
|
||||
|
||||
#### app variable
|
||||
|
||||
The query for this variable basically says, "Give me all the applications that exist."
|
||||
|
||||
```
|
||||
apps.*
|
||||
```
|
||||
|
||||
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."
|
||||
|
||||
```
|
||||
apps.$app.*
|
||||
```
|
||||
|
||||
If the user selects `backend`, then the query changes to:
|
||||
|
||||
```
|
||||
apps.backend.*
|
||||
```
|
||||
|
||||
The query returns all servers associated with `backend`, including `backend_01`, `backend_02`, and so on.
|
||||
|
||||
If the user selects `fakesite`, then the query changes to:
|
||||
|
||||
```
|
||||
apps.fakesite.*
|
||||
```
|
||||
|
||||
The query returns all servers associated with `fakesite`, including `web_server_01`, `web_server_02`, and so on.
|
||||
|
||||
#### More variables
|
||||
|
||||
> **Note:** This example is theoretical. The Graphite server used in the example does not contain CPU metrics.
|
||||
|
||||
The dashboard stops at two levels, but you could keep going. For example, if you wanted to get CPU metrics for selected servers, you could copy the `server` variable and extend the query so that it reads:
|
||||
|
||||
```
|
||||
apps.$app.$server.cpu.*
|
||||
```
|
||||
|
||||
This query basically says, "Show me the CPU metrics for the selected server."
|
||||
|
||||
Depending on what variable options the user selects, you could get queries like:
|
||||
|
||||
```
|
||||
apps.backend.backend_01.cpu.*
|
||||
apps.{backend.backend_02,backend_03}.cpu.*
|
||||
apps.fakesite.web_server_01.cpu.*
|
||||
```
|
||||
|
||||
### InfluxDB example
|
||||
|
||||
In this example, you have several data centers. Each data center has a different subset of hosts. It is based on the [InfluxDB Templated](https://play.grafana.org/d/000000002/influxdb-templated?orgId=1).
|
||||
|
||||
In this example, when the user changes the value of the `datacenter` variable, it changes the dropdown options returned by the `host` variable. The `host` variable uses the **Multi-value** option and **Include all option**, allowing users to select some or all options presented at any time. The `datacenter` does not use either option, so you can only select one data center at a time.
|
||||
|
||||
#### datacenter variable
|
||||
|
||||
The query for this variable basically says, "Give me all the data centers that exist."
|
||||
|
||||
```
|
||||
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."
|
||||
|
||||
```
|
||||
SHOW TAG VALUES WITH KEY = "hostname" WHERE "datacenter" =~ /^$datacenter$/
|
||||
```
|
||||
|
||||
If the user selects `America`, then the query changes to:
|
||||
|
||||
```
|
||||
SHOW TAG VALUES WITH KEY = "hostname" WHERE "datacenter" =~ /^America/
|
||||
```
|
||||
|
||||
The query returns all servers associated with `America`, including `server1`, `server2`, and so on.
|
||||
|
||||
If the user selects `Europe`, then the query changes to:
|
||||
|
||||
```
|
||||
SHOW TAG VALUES WITH KEY = "hostname" WHERE "datacenter" =~ /^Europe/
|
||||
```
|
||||
|
||||
The query returns all servers associated with `Europe`, including `server3`, `server4`, and so on.
|
||||
|
||||
#### More variables
|
||||
|
||||
> **Note:** This example is theoretical. The InfluxDB server used in the example does not contain CPU metrics.
|
||||
|
||||
The dashboard stops at two levels, but you could keep going. For example, if you wanted to get CPU metrics for selected hosts, you could copy the `host` variable and extend the query so that it reads:
|
||||
|
||||
```
|
||||
SHOW TAG VALUES WITH KEY = "cpu" WHERE "datacenter" =~ /^$datacenter$/ AND "host" =~ /^$host$/
|
||||
```
|
||||
|
||||
This query basically says, "Show me the CPU metrics for the selected host."
|
||||
|
||||
Depending on what variable options the user selects, you could get queries like:
|
||||
|
||||
```bash
|
||||
SHOW TAG VALUES WITH KEY = "cpu" WHERE "datacenter" =~ /^America/ AND "host" =~ /^server2/
|
||||
SHOW TAG VALUES WITH KEY = "cpu" WHERE "datacenter" =~ /^Africa/ AND "host" =~ /^server/7/
|
||||
SHOW TAG VALUES WITH KEY = "cpu" WHERE "datacenter" =~ /^Europe/ AND "host" =~ /^server3+server4/
|
||||
```
|
||||
|
||||
## Best practices and tips
|
||||
|
||||
The following practices will make your dashboards and variables easier to use.
|
||||
|
||||
### Creating new linked variables
|
||||
|
||||
- Chaining variables create parent/child dependencies. You can envision them as a ladder or a tree.
|
||||
- The easiest way to create a new chained variable is to copy the variable that you want to base the new one on. In the variable list, click the **Duplicate variable** icon to the right of the variable entry to create a copy. You can then add on to the query for the parent variable.
|
||||
- New variables created this way appear at the bottom of the list. You might need to drag it to a different position in the list to get it into a logical order.
|
||||
|
||||
### Variable order
|
||||
|
||||
You can change the orders of variables in the dashboard variable list by clicking the up and down arrows on the right side of each entry. Grafana lists variable dropdowns left to right according to this list, with the variable at the top on the far left.
|
||||
|
||||
- List variables that do not have dependencies at the top, before their child variables.
|
||||
- Each variable should follow the one it is dependent on.
|
||||
- Remember there is no indication in the UI of which variables have dependency relationships. List the variables in a logical order to make it easy on other users (and yourself).
|
||||
|
||||
### Complexity consideration
|
||||
|
||||
The more layers of dependency you have in variables, the longer it will take to update dashboards after you change variables.
|
||||
|
||||
For example, if you have a series of four linked variables (country, region, server, metric) and you change a root variable value (country), then Grafana must run queries for all the dependent variables before it updates the visualizations in the dashboard.
|
||||
@ -1,98 +0,0 @@
|
||||
---
|
||||
aliases:
|
||||
- /docs/grafana/latest/variables/global-variables/
|
||||
- /docs/grafana/latest/variables/variable-types/global-variables/
|
||||
keywords:
|
||||
- grafana
|
||||
- templating
|
||||
- documentation
|
||||
- guide
|
||||
- template
|
||||
- variable
|
||||
- global
|
||||
- standard
|
||||
title: Global variables
|
||||
weight: 900
|
||||
---
|
||||
|
||||
# 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. These variables are useful in queries, dashboard links, panel links, and data links.
|
||||
|
||||
## $\_\_dashboard
|
||||
|
||||
> Only available in Grafana v6.7+. In Grafana 7.1, the variable changed from showing the UID of the current dashboard to the name of the current dashboard.
|
||||
|
||||
This variable is the name of the current dashboard.
|
||||
|
||||
## $\_\_from and $\_\_to
|
||||
|
||||
Grafana has two built in time range variables: `$__from` and `$__to`. They are currently always interpolated as epoch milliseconds by default but you can control date formatting.
|
||||
|
||||
> This special formatting syntax is only available in Grafana 7.1.2+
|
||||
|
||||
| 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: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/) that does not include the `:` character |
|
||||
|
||||
The above syntax works with `${__to}` as well.
|
||||
|
||||
You can use this variable in URLs as well. For example, send a user to a dashboard that shows a time range from six hours ago until now: https://play.grafana.org/d/000000012/grafana-play-home?viewPanel=2&orgId=1?from=now-6h&to=now
|
||||
|
||||
## $\_\_interval
|
||||
|
||||
You can use the `$__interval` variable 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: `(to - from) / 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
|
||||
|
||||
This variable is the ID of the current organization.
|
||||
`${__org.name}` is the name of the current organization.
|
||||
|
||||
## $\_\_user
|
||||
|
||||
> Only available in Grafana v7.1+
|
||||
|
||||
`${__user.id}` is the ID of the current user.
|
||||
`${__user.login}` is the login handle of the current user.
|
||||
`${__user.email}` is the email for the current user.
|
||||
|
||||
## $\_\_range
|
||||
|
||||
Currently only supported for Prometheus and Loki 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`.
|
||||
|
||||
## $\_\_rate_interval
|
||||
|
||||
Currently only supported for Prometheus data sources. The `$__rate_interval` variable is meant to be used in the rate function. Refer to [Prometheus query variables]({{< relref "../../datasources/prometheus.md#using-__rate_interval">}}) for details.
|
||||
|
||||
## $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. You can add it 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.
|
||||
@ -37,4 +37,4 @@ to the embedded text.
|
||||
|
||||
## Variables
|
||||
|
||||
[Variables]({{< relref "../variables/syntax/" >}}) in the content will be expanded for display.
|
||||
[Variables]({{< relref "../dashboards/variables/variable-syntax" >}}) in the content will be expanded for display.
|
||||
|
||||
@ -63,7 +63,7 @@ The new table panel introduced in 7.0 was missing a few features that the old ta
|
||||
|
||||
## Ad hoc filtering in the new table panel
|
||||
|
||||
[Ad hoc filtering]({{< relref "../variables/variable-types/#ad-hoc-filters" >}}), a way to automatically add filters to queries without having to define template variables is now supported in the new Table panel.
|
||||
[Ad hoc filtering]({{< relref "../dashboards/variables/add-template-variables/#add-ad-hoc-filters" >}}), a way to automatically add filters to queries without having to define template variables is now supported in the new Table panel.
|
||||
|
||||
## Stat panel text mode
|
||||
|
||||
@ -108,7 +108,7 @@ You can now use HashiCorp Vault to get secrets for configuration and provisionin
|
||||
|
||||
### Support for monthly schedules in reports
|
||||
|
||||
With Grafana Enterprise 7.1, you can generate reports on a [monthly schedule]({{< relref "../share-dashboards-panels/#scheduling" >}}).
|
||||
With Grafana Enterprise 7.1, you can generate reports on a [monthly schedule]({{< relref "../dashboards/share-dashboards-panels/#scheduling" >}}).
|
||||
|
||||
## Upgrading
|
||||
|
||||
|
||||
@ -126,9 +126,9 @@ These features are included in the Grafana Enterprise edition software.
|
||||
|
||||
### Report and export dashboards in grid layout
|
||||
|
||||
A new layout option is available when rendering reports: the grid layout. With this option, your report uses the panel layout from your dashboard, so that what you see is what you get. Learn more about the [grid layout]({{< relref "../share-dashboards-panels/#layout-and-orientation" >}}) in the documentation.
|
||||
A new layout option is available when rendering reports: the grid layout. With this option, your report uses the panel layout from your dashboard, so that what you see is what you get. Learn more about the [grid layout]({{< relref "../dashboards/share-dashboards-panels/#layout-and-orientation" >}}) in the documentation.
|
||||
|
||||
The grid layout is also available for the [Export dashboard as PDF]({{< relref "../share-dashboards-panels/#export-dashboard-as-pdf" >}}) feature.
|
||||
The grid layout is also available for the [Export dashboard as PDF]({{< relref "../dashboards/share-dashboards-panels/#export-dashboard-as-pdf" >}}) feature.
|
||||
|
||||
{{< figure src="/static/img/docs/enterprise/reports_grid_landscape_preview.png" max-width="500px" class="docs-image--no-shadow" >}}
|
||||
|
||||
@ -136,7 +136,7 @@ The grid layout is also available for the [Export dashboard as PDF]({{< relref "
|
||||
|
||||
You can now generate a report with a different time range from the dashboard it is based on. This means that you no longer have to apply workarounds, such as copying dashboards or carefully aligning report generation with the end of the month, to generate reports that cover the period you want.
|
||||
|
||||
For more information, refer to [Reports time range]({{< relref "../share-dashboards-panels/#report-time-range" >}}).
|
||||
For more information, refer to [Reports time range]({{< relref "../dashboards/share-dashboards-panels/#report-time-range" >}}).
|
||||
|
||||
### Organization-wide report settings
|
||||
|
||||
@ -144,7 +144,7 @@ You can now configure organization-wide report settings, such as report branding
|
||||
|
||||
{{< figure src="/static/img/docs/enterprise/reports_settings.png" max-width="500px" class="docs-image--no-shadow" caption="Reports settings" >}}
|
||||
|
||||
For more information, refer to [Report settings]({{< relref "../share-dashboards-panels/#report-settings" >}}).
|
||||
For more information, refer to [Report settings]({{< relref "../dashboards/share-dashboards-panels/#report-settings" >}}).
|
||||
|
||||
## Upgrading
|
||||
|
||||
|
||||
@ -183,7 +183,7 @@ For more information on adding a query editor help component to your plugin, ref
|
||||
|
||||
The variables list has an additional column indicating whether variables are referenced in queries and panel names or not. The dependencies graph provides an easy way to check variable dependencies. You can click on a variable name within the graph to make updates to the variable as needed.
|
||||
|
||||
For more information, refer to [Inspect variables and their dependencies]({{< relref "../variables/inspect-variable/" >}}).
|
||||
For more information, refer to [Inspect variables and their dependencies]({{< relref "../dashboards/variables/inspect-variable/" >}}).
|
||||
|
||||
## Grafana Enterprise features
|
||||
|
||||
@ -217,7 +217,7 @@ Also, a counter for audit log writing actions with status (success / failure) an
|
||||
|
||||
You can now select a font, other than the default, for Unicode-based scripts. As a result, an automatically generated PDF of a dashboard, which contains for example Chinese or Cyrillic text, can display them. Because the size of a report increases as additional fonts are added, this feature is not on by default.
|
||||
|
||||
[Reporting]({{< relref "../share-dashboards-panels/#rendering-configuration" >}}) was updated as a result of this change.
|
||||
[Reporting]({{< relref "../dashboards/share-dashboards-panels/#rendering-configuration" >}}) was updated as a result of this change.
|
||||
|
||||
### Request security
|
||||
|
||||
|
||||
@ -131,7 +131,7 @@ If you have created dashboards with template variables, then you can choose whic
|
||||
|
||||
Enable this feature in configuration settings using the `templateVariables` flag.
|
||||
|
||||
For more information, refer to [Reporting]({{< relref "../share-dashboards-panels/#choose-template-variables" >}}).
|
||||
For more information, refer to [Reporting]({{< relref "../dashboards/share-dashboards-panels/#choose-template-variables" >}}).
|
||||
|
||||
### Active user limits
|
||||
|
||||
|
||||
@ -312,7 +312,7 @@ When creating a report, you can now choose to export Table panels as .csv files
|
||||
|
||||
You can also link back to the dashboard directly from the email, for users who want to see the data live in Grafana. This release also includes some improvements to the Reports list view.
|
||||
|
||||
For more information, refer to [Reporting docs]({{< relref "../share-dashboards-panels/#reporting" >}}).
|
||||
For more information, refer to [Reporting docs]({{< relref "../dashboards/share-dashboards-panels/#reporting" >}}).
|
||||
|
||||
### License restrictions clarification in the docs
|
||||
|
||||
|
||||
@ -150,7 +150,7 @@ Fine grained access control allows you to customize roles and permissions in Gra
|
||||
|
||||
### New and improved reporting scheduler
|
||||
|
||||
We’ve enhanced the scheduler for Reports to be more flexible, so you can send reports at just the right time. When scheduling a report, you can now choose to send a report at custom intervals such as every 4 hours or every 2 weeks. You can also send a report for a limited time period by providing a start and end date, or send a report only on weekdays or on the last day of each month. This change accompanies some other recent improvements to Reporting, like the ability to choose template variables for reports and an improved UX for authoring reports. To learn more, refer to the [reporting]({{< relref "../share-dashboards-panels/#reporting" >}}) documentation.
|
||||
We’ve enhanced the scheduler for Reports to be more flexible, so you can send reports at just the right time. When scheduling a report, you can now choose to send a report at custom intervals such as every 4 hours or every 2 weeks. You can also send a report for a limited time period by providing a start and end date, or send a report only on weekdays or on the last day of each month. This change accompanies some other recent improvements to Reporting, like the ability to choose template variables for reports and an improved UX for authoring reports. To learn more, refer to the [reporting]({{< relref "../dashboards/share-dashboards-panels/#reporting" >}}) documentation.
|
||||
|
||||
### Encrypt data in the query cache
|
||||
|
||||
|
||||
@ -183,7 +183,7 @@ Reporting is better in a few specific ways in Grafana version 9.1:
|
||||
For example, you can share last month's numbers as compared to the numbers for this month.
|
||||
The dashboard uses the same template variables if you attach the dashboard to a report twice.
|
||||
|
||||
To learn more about reporting, see the [documentation]({{< relref "../share-dashboards-panels/#reporting" >}}).
|
||||
To learn more about reporting, see the [documentation]({{< relref "../dashboards/share-dashboards-panels/#reporting" >}}).
|
||||
|
||||
{{< figure src="/static/img/docs/enterprise/reporting-draft-9-1.png" max-width="750px" caption="Saving a report as a draft" >}}
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user