From c1de972eb5fa337b98a8886431f85e74e98a64ab Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Torkel=20=C3=96degaard?= Date: Tue, 2 May 2017 16:22:31 +0200 Subject: [PATCH 1/8] docs: wip templating docs --- docs/sources/reference/templating.md | 36 ++++++++++++++++++++++++---- 1 file changed, 31 insertions(+), 5 deletions(-) diff --git a/docs/sources/reference/templating.md b/docs/sources/reference/templating.md index 636cc62a0c8..422a655d5f2 100644 --- a/docs/sources/reference/templating.md +++ b/docs/sources/reference/templating.md @@ -10,19 +10,36 @@ weight = 1 # Templating - + -Dashboard Templating allows you to make your Dashboards more interactive and dynamic. +Templating allows you to make your dashboards more interactive and dynamic. They’re one of the more powerful and complex features in Grafana. The templating +feature allows you to create variables that are shown as dropdown select boxes at the top of the dashboard. +These dropdowns makes it easy to change the variable value and in turn quickly change the data being displayed. -They’re one of the most powerful and most used features of Grafana, and they’ve recently gotten even more attention in Grafana 2.0 and Grafana 2.1. +## What is a variable? -You can create Dashboard Template variables that can be used practically anywhere in a Dashboard: data queries on individual Panels (within the Query Editor), the names in your legends, or titles in Panels and Rows. +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. -You can configure Dashboard Templating by clicking the dropdown cog on the top of the Dashboard while viewing it. +### Interpolation +Panel titles and metric queries can refer to variables using two different syntaxes: + +- `$` Example: apps.frontend.$server.requests.count +- `[[varname]]` Example: apps.frontend.[[server]].requests.count + +Why two ways? The first syntax is easier to read and write but does not allow you to use a variable in the middle of word. Use +the second syntax for scenarios like this: `my.server[[serverNumber]].count`. + +Before queries are sent to your data source the query is **interpolated**, meaning the variable is replaced with its current value. During +interpolation the variable value might be **escaped** in order to conform to the syntax of the query langauge of where it is used. For example +a variable used in a regex expression in an InfluxDB or Prometheus query will be regex escaped. Read the data source specific documentation +article for details on value escaping during interpolation. ## Variable types + + There are three different types of Template variables: query, custom, and interval. They can all be used to create dynamic variables that you can use throughout the Dashboard, but they differ in how they get the data for their values. @@ -40,6 +57,15 @@ You can even create nested variables that use other variables in their definitio You can utilize the special ** All ** value to allow the Dashboard user to query for every single Query variable returned. Grafana will automatically translate ** All ** into the appropriate format for your Data Source. +### Annotation query details + +The annotation query options are different for each data source. + +- [Graphite annotation queries]({{< relref "features/datasources/graphite.md#annotations" >}}) +- [Elasticsearch annotation queries]({{< relref "features/datasources/elasticsearch.md#annotations" >}}) +- [InfluxDB annotation queries]({{< relref "features/datasources/influxdb.md#annotations" >}}) +- [Prometheus annotation queries]({{< relref "features/datasources/prometheus.md#annotations" >}}) + #### Multi-select As of Grafana 2.1, it is now possible to select a subset of Query Template variables (previously it was possible to select an individual value or 'All', not multiple values that were less than All). This is accomplished via the Multi-Select option. If enabled, the Dashboard user will be able to enable and disable individual variables. From 2304a710bf3b68036676172ea280bc57391ce729 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Torkel=20=C3=96degaard?= Date: Wed, 3 May 2017 14:09:04 +0200 Subject: [PATCH 2/8] docs: templating doc wip --- docs/sources/reference/templating.md | 142 +++++++++++++++++++-------- 1 file changed, 99 insertions(+), 43 deletions(-) diff --git a/docs/sources/reference/templating.md b/docs/sources/reference/templating.md index 422a655d5f2..5322b8150b3 100644 --- a/docs/sources/reference/templating.md +++ b/docs/sources/reference/templating.md @@ -12,9 +12,9 @@ weight = 1 -Templating allows you to make your dashboards more interactive and dynamic. They’re one of the more powerful and complex features in Grafana. The templating -feature allows you to create variables that are shown as dropdown select boxes at the top of the dashboard. -These dropdowns makes it easy to change the variable value and in turn quickly change the data being displayed. +Templating allows you to make your dashboards more interactive and dynamic. Instead of hard-coding things like server, application +or sensor id in you metric queries you can use variables in their place. Variables are shown as dropdown select boxes at the top of +the dashboard. These dropdowns makes it easy to change the data being displayed in your dashboard. ## What is a variable? @@ -32,80 +32,136 @@ Why two ways? The first syntax is easier to read and write but does not allow yo the second syntax for scenarios like this: `my.server[[serverNumber]].count`. Before queries are sent to your data source the query is **interpolated**, meaning the variable is replaced with its current value. During -interpolation the variable value might be **escaped** in order to conform to the syntax of the query langauge of where it is used. For example -a variable used in a regex expression in an InfluxDB or Prometheus query will be regex escaped. Read the data source specific documentation -article for details on value escaping during interpolation. +interpolation the variable value might be **escaped** in order to conform to the syntax of the query language and where it is used. +For example a variable used in a regex expression in an InfluxDB or Prometheus query will be regex escaped. Read the data source specific +documentation article for details on value escaping during interpolation. -## Variable types +### Variable options + +A variable is presented as a dropdown select box at the top of the dashboards. It has a current value and a set of **options**. The **options** +is the the set of values you can choose from. + +## Adding a variable -There are three different types of Template variables: query, custom, and interval. +You add variables via Dashboard cogs menu > Templating. This opens up a list of variables and a `New` button to create a new variable. -They can all be used to create dynamic variables that you can use throughout the Dashboard, but they differ in how they get the data for their values. +### Basic variable options + +Option | Description +------- | -------- +*Name* | The name of the variable, this is the name you use when you refer to your variable in your metric queries. Must be unique and contain no white-spaces. +*Label* | The name of the dropdown for this variable. +*Hide* | Options to hide the dropdown select box. +*Type* | Defines the variable type. -### Query +### Variable types - > Note: The Query type is Data Source specific. Please consult the appropriate documentation for your particular Data Source. +Type | Description +------- | -------- +*Query* | This variable type allows you to write a data source query that usually returns a list of metric names, tag values or keys. For example a query that returns a list of server names, sensor ids or data centers. +*Interval* | This variable can represent timespans. Instead of hard-coding a group by time or date histogram interval use a variable of this type. +*Datasource* | This type allows you to quickly change data source for an entire Dashboard. Useful if you have multiple instances of a data source in for example different environments. +*Custom* | Define the variable options manually using a comma seperated list. +*Constant* | Define a hidden constant. Useful for metric path prefixes for dashboards you want to share. During dashboard export constant variables will be made into an import option. +*Ad hoc filters* | Very special kind of variable that only works with some data sources, InfluxDB & Elasticsearch currently. It allows you to add key/value filters that will automatically be added to all metric queries that use the specified data source. -Query is the most common type of Template variable. Use the `Query` template type to generate a dynamic list of variables, simply by allowing Grafana to explore your Data Source metric namespace when the Dashboard loads. +### Query options -For example a query like `prod.servers.*` will fill the variable with all possible values that exists in that wildcard position (in the case of the Graphite Data Source). +This variable type is the most powerful and complex as it can dynamically fetch its options using a data source query. -You can even create nested variables that use other variables in their definition. For example `apps.$app.servers.*` uses the variable $app in its own query definition. +Option | Description +------- | -------- +*Data source* | The data source target for the query. +*Refresh* | Controls when to update the variable option list (values in the dropdown). **On Dashboard Load** will slow down dashboard load as the variable query needs to be completed before dashboard can be initialized. Set this only to **On Time Range Change** if your variable options query contains a time range filter or is dependant on dashboard time range. +*Query* | The data source specific query expression. +*Regex* | Regex to filter or capture specific parts of the names return by your data source query. Optional. +*Sort* | Define sort order for options in dropdown. **Disabled** means that the order of options returned by your data source query will be used. -You can utilize the special ** All ** value to allow the Dashboard user to query for every single Query variable returned. Grafana will automatically translate ** All ** into the appropriate format for your Data Source. +### Query expressions -### Annotation query details +The query expressions are different for each data source. -The annotation query options are different for each data source. +- [Graphite templating queries]({{< relref "features/datasources/graphite.md#templating" >}}) +- [Elasticsearch templating queries]({{< relref "features/datasources/elasticsearch.md#templating" >}}) +- [InfluxDB templating queries]({{< relref "features/datasources/influxdb.md#templating" >}}) +- [Prometheus templating queries]({{< relref "features/datasources/prometheus.md#templating" >}}) +- [OpenTSDB templating queries]({{< relref "features/datasources/prometheus.md#templating" >}}) -- [Graphite annotation queries]({{< relref "features/datasources/graphite.md#annotations" >}}) -- [Elasticsearch annotation queries]({{< relref "features/datasources/elasticsearch.md#annotations" >}}) -- [InfluxDB annotation queries]({{< relref "features/datasources/influxdb.md#annotations" >}}) -- [Prometheus annotation queries]({{< relref "features/datasources/prometheus.md#annotations" >}}) +One thing to note is that query expressions can contain references to other variables and in effect create depend & nested +variables. Grafana will detect this and automatically refresh a variable when one of it's containing variables change. -#### Multi-select -As of Grafana 2.1, it is now possible to select a subset of Query Template variables (previously it was possible to select an individual value or 'All', not multiple values that were less than All). This is accomplished via the Multi-Select option. If enabled, the Dashboard user will be able to enable and disable individual variables. +## Selection Options -The Multi-Select functionality is taken a step further with the introduction of Multi-Select Tagging. This functionality allows you to group individual Template variables together under a Tag or Group name. +Option | Description +------- | -------- +*Mulit-value* | If enabled, the variable will support the selection of multiple options at the same time. +*Include All option* | Add a special `All` option whose value includes all options. +*Custom all value* | By default the `All` value will include all options in combined expression. This can become very long and can have performance problems. Many times it can be better to specify a custom all value, like a wildcard regex. To make it possible to have custom regex, globs or lucene syntax in the **Custom all value** option it is never escaped so you will have to think avbout what is a valid value for your data source. -For example, if you were using Templating to list all 20 of your applications, you could use Multi-Select Tagging to group your applications by function or region or criticality, etc. +### Formating multiple values - > Note: Multi-Select Tagging functionality is currently experimental but is part of Grafana 2.1. To enable this feature click the enable icon when editing Template options for a particular variable. +Interpolating a variable with multiple values selected is tricky as it is not straight forward how to format the multiple values to into a string that +is valid in the given context where the variable is used. Grafana tries to solve this by allowing each data source plugin to +inform the templating interpolation engine what format to use for multiple values. - +**Graphite** for example uses glob expressions. A variable with multiple values would in this case be interpolated as `{host1,host2,host3}` if +the current variable value was *host1*, *host2* and *host3*. -Grafana gets the list of tags and the list of values in each tag by performing two queries on your metric namespace. +**InfluxDB and Prometheus** uses regex expressions, so the same variable +would be interpolated as `(host1|host2|host3)`. Every value would also be regex escaped, if not, a value with a regex control character would +break the regex expression. -The Tags query returns a list of Tags. +**Elasticsearch** uses lucene query syntax, so the same variable would in this case be formated as `("host1" OR "host2" OR "host3")`. In this case every value +needs to be escaped so that the value can contain lucene control words and quotation marks. -The Tag values query returns the values for a given Tag. +#### Formating troubles -Note: a proof of concept shim that translates the metric query into a SQL call is provided. This allows you to maintain your tag:value mapping independently of your Data Source. +Automatic escaping & formating can cause problems and it can be tricky to grasp the logic is behind it. +Especially for InfluxDB and Prometheus where the use of regex syntax requires that the variable is used in regex operator context. +If you do not want Grafana to do this automatic regex escaping and formating your only option is to disable the *Multi-value* or *Include All option* +options. -Once configured, Multi-Select Tagging provides a convenient way to group and your template variables, and slice your data in the exact way you want. The Tags can be seen on the right side of the template pull-down. +### Value groups/tags -![](/img/docs/v2/multi-select.gif) +If you have a lot of options in the dropdown for a multi-value variable. You can use this feature to group the values into selectable tags. -### Interval +Option | Description +------- | -------- +*Tags query* | Data source query that should return a list of tags +*Tag values query* | Data source query that should return a list of values for a specified tag key. Use `$tag` in the query to refer the currently selected tag. -Use the `Interval` type to create Template variables around time ranges (eg. `1m`,`1h`, `1d`). There is also a special `auto` option that will change depending on the current time range, you can specify how many times the current time range should be divided to calculate the current `auto` range. +![](/img/docs/v4/variable_dropdown_tags.png) -![](/img/docs/v2/templated_variable_parameter.png) +### Interval variables -### Custom +Use the `Interval` type to create a variable that represent a timespan (eg. `1m`,`1h`, `1d`). There is also a special `auto` option that will change depending on the current time range. You can specify how many times the current time range +should be divided to calculate the current `auto` timespan. -Use the `Custom` type to manually create Template variables around explicit values that are hard-coded into the Dashboard, and not dependent on any Data Source. You can specify multiple Custom Template values by separating them with a comma. +This variable type is useful as parameter to group by time (for InfluxDB), Date histogram interval (for Elasticsearch) or as a *summarize* function parameter (for Graphite). -## Repeating Panels and Repeating Rows +## Repeating Panels -Template Variables can be very useful to dynamically change what you're visualizing on a given panel. Sometimes, you might want to create entire new Panels (or Rows) based on what Template Variables have been selected. This is now possible in Grafana 2.1. +Template variables can be very useful to dynamically change your queries across a whole dashboard. If you want +Grafana to dynamically create new panels or rows based on what values you have selected you can use the *Repeat* feature. -Once you've got your Template variables (of any type) configured the way you'd like, check out the Repeating Panels and Repeating Row documentation +If you have a variable with `Multi-value` or `Include all value` options enabled you can choose one panel or one row and have Grafana repeat that row +for every selected value. You find this option under the General tab in panel edit mode. You select the variable to repeat by, and a `min span`. +The `min span` controls how small Grafana will make the panels (if you have many values selected). Grafana will automatically adjust the width of +each repeated panel so that the whole row is filled. Currently you cannot mix other panels on a row with a repeated panel. -## Screencast - Templated Graphite Queries +Only make changes to the first panel (the original template). To have the changes take effect on all panels you need to trigger a dynamic dashboard re-build. +You can do this by either changing the variable value (that is the basis for the repeat) or reload the dashboard. + +## Repeating Rows + +This option requires you to open the row options view. Hover over the row left side to trigger the row menu, in this menu click `Row Options`. This +opens the row options view. Here you find a *Repeat* dropdown where you can select the variable to repeat by. + +### URL state + +Variable values are always synced to the URL using the syntax `var-=value`. - From e6c29391c641fd8ffad2c72da0c3b05083b49c4c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Torkel=20=C3=96degaard?= Date: Wed, 3 May 2017 14:20:59 +0200 Subject: [PATCH 3/8] docs: improved Graphite templating docs --- docs/sources/features/datasources/graphite.md | 26 ++++++++++++++++--- docs/sources/reference/templating.md | 6 ++--- 2 files changed, 25 insertions(+), 7 deletions(-) diff --git a/docs/sources/features/datasources/graphite.md b/docs/sources/features/datasources/graphite.md index 58965f8bf6f..34fb48618f7 100644 --- a/docs/sources/features/datasources/graphite.md +++ b/docs/sources/features/datasources/graphite.md @@ -76,17 +76,35 @@ this consolidation is done using `avg` function. You can how Graphite consolidat > client side by Grafana. And depending on your consolidation function only one or two can be correct at the same time. ## Templating -You can create a template variable in Grafana and have that variable filled with values from any Graphite metric exploration query. -You can then use this variable in your Graphite queries, either as part of a metric path or as arguments to functions. -For example a query like `prod.servers.*` will fill the variable with all possible -values that exists in the wildcard position. +Instead of hard-coding things like server, application and sensor name in you metric queries you can use variables in their place. +Variables are shown as dropdown select boxes at the top of the dashboard. These dropdowns makes it easy to change the data +being displayed in your dashboard. + +Checkout the [Templating]({{< relref "reference/templating.md" >}}) documentation for an introduction to the templating feature and the different +types of template variables. + +### Query variables + +The query you specify in the query field should be a metric find type of query. For example a query like `prod.servers.*` will fill the +variable with all possible values that exists in the wildcard position. You can also create nested variables that use other variables in their definition. For example `apps.$app.servers.*` uses the variable `$app` in its query definition. +### Variable usage + +You can use a variable in a metric node path or as a parameter to a function. ![](/img/docs/v2/templated_variable_parameter.png) +There are two syntaxes: + +- `$` Example: apps.frontend.$server.requests.count +- `[[varname]]` Example: apps.frontend.[[server]].requests.count + +Why two ways? The first syntax is easier to read and write but does not allow you to use a variable in the middle of word. Use +the second syntax in expressions like `my.server[[serverNumber]].count`. + ## Annotations [Annotations]({{< relref "reference/annotations.md" >}}) allows you to overlay rich event information on top of graphs. You add annotation diff --git a/docs/sources/reference/templating.md b/docs/sources/reference/templating.md index 5322b8150b3..f16e03c898b 100644 --- a/docs/sources/reference/templating.md +++ b/docs/sources/reference/templating.md @@ -12,8 +12,8 @@ weight = 1 -Templating allows you to make your dashboards more interactive and dynamic. Instead of hard-coding things like server, application -or sensor id in you metric queries you can use variables in their place. Variables are shown as dropdown select boxes at the top of +Templating allows for more interactive and dynamic dashboards. Instead of hard-coding things like server, application +and sensor name in you metric queries you can use variables in their place. Variables are shown as dropdown select boxes at the top of the dashboard. These dropdowns makes it easy to change the data being displayed in your dashboard. ## What is a variable? @@ -29,7 +29,7 @@ Panel titles and metric queries can refer to variables using two different synta - `[[varname]]` Example: apps.frontend.[[server]].requests.count Why two ways? The first syntax is easier to read and write but does not allow you to use a variable in the middle of word. Use -the second syntax for scenarios like this: `my.server[[serverNumber]].count`. +the second syntax in expressions like `my.server[[serverNumber]].count`. Before queries are sent to your data source the query is **interpolated**, meaning the variable is replaced with its current value. During interpolation the variable value might be **escaped** in order to conform to the syntax of the query language and where it is used. From ed8d284715c47069d0533a3d3ede52441be87f34 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Torkel=20=C3=96degaard?= Date: Wed, 3 May 2017 15:50:38 +0200 Subject: [PATCH 4/8] docs: updated prometheus docs --- docs/sources/features/datasources/graphite.md | 10 +-- .../features/datasources/prometheus.md | 82 +++++++++---------- docs/sources/reference/templating.md | 7 ++ .../prometheus/partials/query.editor.html | 20 +++-- 4 files changed, 66 insertions(+), 53 deletions(-) diff --git a/docs/sources/features/datasources/graphite.md b/docs/sources/features/datasources/graphite.md index 34fb48618f7..3e4276ba486 100644 --- a/docs/sources/features/datasources/graphite.md +++ b/docs/sources/features/datasources/graphite.md @@ -18,15 +18,13 @@ change function parameters and much more. The editor can handle all types of gra queries through the use of query references. ## Adding the data source -![](/img/docs/v2/add_Graphite.jpg) 1. Open the side menu by clicking the the Grafana icon in the top header. 2. In the side menu under the `Dashboards` link you should find a link named `Data Sources`. +3. Click the `+ Add data source` button in the top header. +4. Select `Graphite` from the *Type* dropdown. - > NOTE: If this link is missing in the side menu it means that your current user does not have the `Admin` role for the current organization. - -3. Click the `Add new` link in the top header. -4. Select `Graphite` from the dropdown. +> NOTE: If your not seeing the `Data Sources` link in your side menu it means that your current user does not have the `Admin` role for the current organization. Name | Description ------------ | ------------- @@ -84,7 +82,7 @@ being displayed in your dashboard. Checkout the [Templating]({{< relref "reference/templating.md" >}}) documentation for an introduction to the templating feature and the different types of template variables. -### Query variables +### Query variable The query you specify in the query field should be a metric find type of query. For example a query like `prod.servers.*` will fill the variable with all possible values that exists in the wildcard position. diff --git a/docs/sources/features/datasources/prometheus.md b/docs/sources/features/datasources/prometheus.md index e6f2749bb4b..b302fb3b5f1 100644 --- a/docs/sources/features/datasources/prometheus.md +++ b/docs/sources/features/datasources/prometheus.md @@ -17,70 +17,70 @@ Grafana includes support for Prometheus Datasources. While the process of adding ## Adding the data source to Grafana -![](/img/docs/v2/add_Prometheus.png) - 1. Open the side menu by clicking the the Grafana icon in the top header. 2. In the side menu under the `Dashboards` link you should find a link named `Data Sources`. +3. Click the `+ Add data source` button in the top header. +4. Select `Prometheus` from the *Type* dropdown. - > NOTE: If this link is missing in the side menu it means that your current user does not have the `Admin` role for the current organization. +> NOTE: If your not seeing the `Data Sources` link in your side menu it means that your current user does not have the `Admin` role for the current organization. -3. Click the `Add new` link in the top header. -4. Select `Prometheus` from the dropdown. +## Data source options Name | Description ------------ | ------------- -Name | The data source name, important that this is the same as in Grafana v1.x if you plan to import old dashboards. -Default | Default data source means that it will be pre-selected for new panels. -Url | The http protocol, ip and port of you Prometheus server (default port is usually 9090) -Access | Proxy = access via Grafana backend, Direct = access directly from browser. -Basic Auth | Enable basic authentication to the Prometheus datasource. -User | Name of your Prometheus user -Password | Database user's password - - > Proxy access means that the Grafana backend will proxy all requests from the browser, and send them on to the Data Source. This is useful because it can eliminate CORS (Cross Origin Site Resource) issues, as well as eliminate the need to disseminate authentication details to the Data Source to the browser. - - > Direct access is still supported because in some cases it may be useful to access a Data Source directly depending on the use case and topology of Grafana, the user, and the Data Source. +*Name* | The data source name, important that this is the same as in Grafana v1.x if you plan to import old dashboards. +*Default* | Default data source means that it will be pre-selected for new panels. +*Url* | The http protocol, ip and port of you Prometheus server (default port is usually 9090) +*Access* | Proxy = access via Grafana backend, Direct = access directly from browser. +*Basic Auth* | Enable basic authentication to the Prometheus datasource. +*User* | Name of your Prometheus user +*Password* | Database user's password ## Query editor -Open a graph in edit mode by click the title. -![](/img/v2/prometheus_editor.png) +Open a graph in edit mode by click the title > Edit (or by pressing `e` key while hovering over panel). -For details on Prometheus metric queries check out the Prometheus documentation -- [Query Metrics - Prometheus documentation](http://prometheus.io/docs/querying/basics/). - -## Templated queries - -Prometheus Datasource Plugin provides the following functions in `Variables values query` field in Templating Editor to query `metric names` and `labels names` on the Prometheus server. +![](/img/docs/v43/prometheus_query_editor.png) Name | Description ------- | -------- -`label_values(label)` | Returns a list of label values for the `label` in every metric. -`label_values(metric, label)` | Returns a list of label values for the `label` in the specified metric. -`metrics(metric)` | Returns a list of metrics matching the specified `metric` regex. -`query_result(query)` | Returns a list of Prometheus query result for the `query`. +*Query expression* | Prometheus query expression, check out the [Prometheus documentation](http://prometheus.io/docs/querying/basics/). +*Legend format* | Controls the name of the time series, using name or pattern. For example `{{hostname}}` will be replaced with label value for the label `hostname`. +*Min step* | Set a lower limit for the prometheus step option. Step controls how big the jumps are when the Prometheus query engine performs range queries. Sadly there is no official prometheus documentation to link to for this very important option. +*Resolution* | Controls the step option. Small steps create high resolution graphs but can be slow over larger time ranges, lowering the resolution can speed things up. `1/2` will try to set step option to generate 1 data point over other pixel. A value of `1/10` will try to set step option so there is a data point every 10 pixels. -For details of `metric names` & `label names`, and `label values`, please refer to the [Prometheus documentation](http://prometheus.io/docs/concepts/data_model/#metric-names-and-labels). +## Templating -> Note: The part of queries is incompatible with the version before 2.6, if you specify like `foo.*`, please change like `metrics(foo.*)`. +Instead of hard-coding things like server, application and sensor name in you metric queries you can use variables in their place. +Variables are shown as dropdown select boxes at the top of the dashboard. These dropdowns makes it easy to change the data +being displayed in your dashboard. -You can create a template variable in Grafana and have that variable filled with values from any Prometheus metric exploration query. -You can then use this variable in your Prometheus metric queries. +Checkout the [Templating]({{< relref "reference/templating.md" >}}) documentation for an introduction to the templating feature and the different +types of template variables. -For example you can have a variable that contains all values for label `hostname` if you specify a query like this in the templating edit view. +### Query variable -```sql -label_values(hostname) -``` +Variable of the type *Query* allows you to query Prometheus for a list of metrics, labels or label values. The Prometheus data source plugin +provides the following functions you can use in the `Query` input field. -You can also use raw queries & regular expressions to extract anything you might need. +Name | Description +---- | -------- +*label_values(label)* | Returns a list of label values for the `label` in every metric. +*label_values(metric, label)* | Returns a list of label values for the `label` in the specified metric. +*metrics(metric)* | Returns a list of metrics matching the specified `metric` regex. +*query_result(query)* | Returns a list of Prometheus query result for the `query`. -### Using templated variables in queries +For details of *metric names*, *label names* and *label values* are please refer to the [Prometheus documentation](http://prometheus.io/docs/concepts/data_model/#metric-names-and-labels). -When the `Include All` option or `Multi-Value` option is enabled, Grafana converts the labels from plain text to a regex compatible string. -Which means you have to use `=~` instead of `=` in your Prometheus queries. For example `ALERTS{instance=~$instance}` instead of `ALERTS{instance=$instance}`. +### Using variables in queries -![](/img/docs/v2/prometheus_templating.png) +There are two syntaxes: + +- `$` Example: rate(http_requests_total{job=~"$job"}[5m]) +- `[[varname]]` Example: rate(http_requests_total{job="my[[job]]"}[5m]) + +Why two ways? The first syntax is easier to read and write but does not allow you to use a variable in the middle of word. When the *Multi-value* or *Include all value* +option is enabled, Grafana converts the labels from plain text to a regex compatible string. Which means you have to use `=~` instead of `=`. ## Annotations diff --git a/docs/sources/reference/templating.md b/docs/sources/reference/templating.md index f16e03c898b..51aff771115 100644 --- a/docs/sources/reference/templating.md +++ b/docs/sources/reference/templating.md @@ -10,6 +10,13 @@ weight = 1 # Templating +Instead of hard-coding things like server, application and sensor name in you metric queries you can use variables in their place. +Variables are shown as dropdown select boxes at the top of the dashboard. These dropdowns makes it easy to change the data +being displayed in your dashboard. + +Checkout the [Templating]({{< relref "reference/templating.md" >}}) documentation for an introduction to the templating feature and the different +types of template variables. + Templating allows for more interactive and dynamic dashboards. Instead of hard-coding things like server, application diff --git a/public/app/plugins/datasource/prometheus/partials/query.editor.html b/public/app/plugins/datasource/prometheus/partials/query.editor.html index f919800b813..bd3d06773a6 100644 --- a/public/app/plugins/datasource/prometheus/partials/query.editor.html +++ b/public/app/plugins/datasource/prometheus/partials/query.editor.html @@ -13,9 +13,10 @@ ng-model-onblur ng-change="ctrl.refreshMetricData()"> +
- - Min step +
+
@@ -36,14 +38,20 @@
-
- +
+
+
+
+ +
+
+
- -
+ +