diff --git a/docs/sources/features/datasources/cloudwatch.md b/docs/sources/features/datasources/cloudwatch.md index f5586bef2d8..d178c176602 100644 --- a/docs/sources/features/datasources/cloudwatch.md +++ b/docs/sources/features/datasources/cloudwatch.md @@ -208,9 +208,9 @@ it costs $0.01 per 1,000 GetMetricStatistics or ListMetrics requests. For each q issue a GetMetricStatistics request and every time you pick a dimension in the query editor Grafana will issue a ListMetrics request. -## Configure datasource with provisioning +## Configure the Datasource with Provisioning -It's now possible to configure datasources using config files with Grafanas provisioning system. You can read more about how it works and all the settings you can set for datasources on the [provisioning docs page](/administration/provisioning/#datasources) +It's now possible to configure datasources using config files with Grafana's provisioning system. You can read more about how it works and all the settings you can set for datasources on the [provisioning docs page](/administration/provisioning/#datasources) Here are some provisioning examples for this datasource. diff --git a/docs/sources/features/datasources/elasticsearch.md b/docs/sources/features/datasources/elasticsearch.md index 6039eb77ff8..31ce78f0bfe 100644 --- a/docs/sources/features/datasources/elasticsearch.md +++ b/docs/sources/features/datasources/elasticsearch.md @@ -160,9 +160,9 @@ Time | The name of the time field, needs to be date field. Text | Event description field. Tags | Optional field name to use for event tags (can be an array or a CSV string). -## Configure datasource with provisioning +## Configure the Datasource with Provisioning -It's now possible to configure datasources using config files with Grafanas provisioning system. You can read more about how it works and all the settings you can set for datasources on the [provisioning docs page](/administration/provisioning/#datasources) +It's now possible to configure datasources using config files with Grafana's provisioning system. You can read more about how it works and all the settings you can set for datasources on the [provisioning docs page](/administration/provisioning/#datasources) Here are some provisioning examples for this datasource. diff --git a/docs/sources/features/datasources/graphite.md b/docs/sources/features/datasources/graphite.md index a44bd445482..7a4113a89ef 100644 --- a/docs/sources/features/datasources/graphite.md +++ b/docs/sources/features/datasources/graphite.md @@ -53,7 +53,6 @@ or keyboard arrow keys. You can select a wildcard and still continue. {{< docs-imagebox img="/img/docs/v45/graphite_query1_still.png" animated-gif="/img/docs/v45/graphite_query1.gif" >}} - ### Functions Click the plus icon to the right to add a function. You can search for the function or select it from the menu. Once @@ -64,7 +63,6 @@ by the x icon. {{< docs-imagebox img="/img/docs/v45/graphite_query2_still.png" animated-gif="/img/docs/v45/graphite_query2.gif" >}} - ### Optional parameters Some functions like aliasByNode support an optional second argument. To add this parameter specify for example 3,-2 as the first parameter and the function editor will adapt and move the -2 to a second parameter. To remove the second optional parameter just click on it and leave it blank and the editor will remove it. @@ -72,7 +70,6 @@ Some functions like aliasByNode support an optional second argument. To add this {{< docs-imagebox img="/img/docs/v45/graphite_query3_still.png" animated-gif="/img/docs/v45/graphite_query3.gif" >}} - ### Nested Queries You can reference queries by the row “letter” that they’re on (similar to Microsoft Excel). If you add a second query to a graph, you can reference the first query simply by typing in #A. This provides an easy and convenient way to build compounded queries. @@ -80,7 +77,6 @@ You can reference queries by the row “letter” that they’re on (similar to {{< docs-imagebox img="/img/docs/v45/graphite_nested_queries_still.png" animated-gif="/img/docs/v45/graphite_nested_queries.gif" >}} - ## Point consolidation All Graphite metrics are consolidated so that Graphite doesn't return more data points than there are pixels in the graph. By default, @@ -98,6 +94,18 @@ 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. +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, then you need to use the Grafana functions `tags` and `tag_values`. + +Query | Description +------------ | ------------- +*tags()* | Returns all tags. +*tags(server=~backend\*)* | Returns only tags that occur in series matching the filter expression. +*tag_values(server)* | Return tag values for the specified tag. +*tag_values(server, server=~backend*)* | Returns filtered tag values that occur for the specified tag in series matching those expressions. +*tag_values(server, server=~backend*, app=~${apps:regex})* | Multiple filter expressions and expressions can contain other variables. + +For more details, see the [Graphite docs on the autocomplete api for tags](http://graphite.readthedocs.io/en/latest/tags.html#auto-complete-support). + ### 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 @@ -106,10 +114,10 @@ variable with all possible values that exist 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 +### 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) +![variable](/img/docs/v2/templated_variable_parameter.png) There are two syntaxes: @@ -122,6 +130,18 @@ the second syntax in expressions like `my.server[[serverNumber]].count`. Example: [Graphite Templated Dashboard](http://play.grafana.org/dashboard/db/graphite-templated-nested) +### Variable Usage in Tag Queries + +Multi-value variables in tag queries use the advanced formatting syntax introduced in Grafana 5.0 for variables: `{var:regex}`. Non-tag queries will use the default glob formatting for multi-value variables. + +Example of a tag expression with regex formatting and using the Equal Tilde operator, `=~`: + +```text +server=~${servers:regex} +``` + +Checkout the [Advanced Formatting Options section in the Variables]({{< relref "reference/templating.md#advanced-formatting-options" >}}) documentation for examples and details. + ## Annotations [Annotations]({{< relref "reference/annotations.md" >}}) allows you to overlay rich event information on top of graphs. You add annotation @@ -130,9 +150,9 @@ queries via the Dashboard menu / Annotations view. Graphite supports two ways to query annotations. A regular metric query, for this you use the `Graphite query` textbox. A Graphite events query, use the `Graphite event tags` textbox, specify a tag or wildcard (leave empty should also work) -## Configure datasource with provisioning +## Configure the Datasource with Provisioning -It's now possible to configure datasources using config files with Grafanas provisioning system. You can read more about how it works and all the settings you can set for datasources on the [provisioning docs page](/administration/provisioning/#datasources) +It's now possible to configure datasources using config files with Grafana's provisioning system. You can read more about how it works and all the settings you can set for datasources on the [provisioning docs page](/administration/provisioning/#datasources) Here are some provisioning examples for this datasource. diff --git a/docs/sources/features/datasources/influxdb.md b/docs/sources/features/datasources/influxdb.md index f46912c68b5..1426f55e40b 100644 --- a/docs/sources/features/datasources/influxdb.md +++ b/docs/sources/features/datasources/influxdb.md @@ -195,9 +195,9 @@ For InfluxDB you need to enter a query like in the above example. You need to ha part. If you only select one column you will not need to enter anything in the column mapping fields. The Tags field can be a comma separated string. -## Configure datasource with provisioning +## Configure the Datasource with Provisioning -It's now possible to configure datasources using config files with Grafanas provisioning system. You can read more about how it works and all the settings you can set for datasources on the [provisioning docs page](/administration/provisioning/#datasources) +It's now possible to configure datasources using config files with Grafana's provisioning system. You can read more about how it works and all the settings you can set for datasources on the [provisioning docs page](/administration/provisioning/#datasources) Here are some provisioning examples for this datasource. diff --git a/docs/sources/features/datasources/mysql.md b/docs/sources/features/datasources/mysql.md index dd6d9766b27..f91417a43b7 100644 --- a/docs/sources/features/datasources/mysql.md +++ b/docs/sources/features/datasources/mysql.md @@ -226,6 +226,14 @@ WHERE $__timeFilter(atimestamp) and hostname in([[hostname]]) ORDER BY atimestamp ASC ``` +#### Disabling Quoting for Multi-value Variables + +Grafana automatically creates a quoted, comma-separated string for multi-value variables. For example: if `server01` and `server02` are selected then it will be formatted as: `'server01', 'server02'`. Do disable quoting, use the csv formatting option for variables: + +`${servers:csv}` + +Read more about variable formatting options in the [Variables]({{< relref "reference/templating.md#advanced-formatting-options" >}}) documentation. + ## Annotations [Annotations]({{< relref "reference/annotations.md" >}}) allow you to overlay rich event information on top of graphs. You add annotation queries via the Dashboard menu / Annotations view. @@ -266,9 +274,9 @@ tags | Optional field name to use for event tags as a comma separated string. Time series queries should work in alerting conditions. Table formatted queries is not yet supported in alert rule conditions. -## Configure datasource with provisioning +## Configure the Datasource with Provisioning -It's now possible to configure datasources using config files with Grafanas provisioning system. You can read more about how it works and all the settings you can set for datasources on the [provisioning docs page](/administration/provisioning/#datasources) +It's now possible to configure datasources using config files with Grafana's provisioning system. You can read more about how it works and all the settings you can set for datasources on the [provisioning docs page](/administration/provisioning/#datasources) Here are some provisioning examples for this datasource. @@ -282,4 +290,4 @@ datasources: database: grafana user: grafana password: password -``` \ No newline at end of file +``` diff --git a/docs/sources/features/datasources/opentsdb.md b/docs/sources/features/datasources/opentsdb.md index 307abec8ddf..1f6f022a18c 100644 --- a/docs/sources/features/datasources/opentsdb.md +++ b/docs/sources/features/datasources/opentsdb.md @@ -88,9 +88,9 @@ Query | Description For details on OpenTSDB metric queries checkout the official [OpenTSDB documentation](http://opentsdb.net/docs/build/html/index.html) -## Configure datasource with provisioning +## Configure the Datasource with Provisioning -It's now possible to configure datasources using config files with Grafanas provisioning system. You can read more about how it works and all the settings you can set for datasources on the [provisioning docs page](/administration/provisioning/#datasources) +It's now possible to configure datasources using config files with Grafana's provisioning system. You can read more about how it works and all the settings you can set for datasources on the [provisioning docs page](/administration/provisioning/#datasources) Here are some provisioning examples for this datasource. diff --git a/docs/sources/features/datasources/postgres.md b/docs/sources/features/datasources/postgres.md index fa4e5d241ca..8aa1b7f59b0 100644 --- a/docs/sources/features/datasources/postgres.md +++ b/docs/sources/features/datasources/postgres.md @@ -95,7 +95,7 @@ You can control the name of the Table panel columns by using regular `as ` SQL c The resulting table panel: -![](/img/docs/v46/postgres_table.png) +![postgres table](/img/docs/v46/postgres_table.png) ## Time series queries @@ -217,6 +217,14 @@ WHERE $__timeFilter(atimestamp) and hostname in([[hostname]]) ORDER BY atimestamp ASC ``` +#### Disabling Quoting for Multi-value Variables + +Grafana automatically creates a quoted, comma-separated string for multi-value variables. For example: if `server01` and `server02` are selected then it will be formatted as: `'server01', 'server02'`. Do disable quoting, use the csv formatting option for variables: + +`${servers:csv}` + +Read more about variable formatting options in the [Variables]({{< relref "reference/templating.md#advanced-formatting-options" >}}) documentation. + ## Annotations [Annotations]({{< relref "reference/annotations.md" >}}) allow you to overlay rich event information on top of graphs. You add annotation queries via the Dashboard menu / Annotations view. @@ -258,9 +266,9 @@ tags | Optional field name to use for event tags as a comma separated string. Time series queries should work in alerting conditions. Table formatted queries is not yet supported in alert rule conditions. -## Configure datasource with provisioning +## Configure the Datasource with Provisioning -It's now possible to configure datasources using config files with Grafanas provisioning system. You can read more about how it works and all the settings you can set for datasources on the [provisioning docs page](/administration/provisioning/#datasources) +It's now possible to configure datasources using config files with Grafana's provisioning system. You can read more about how it works and all the settings you can set for datasources on the [provisioning docs page](/administration/provisioning/#datasources) Here are some provisioning examples for this datasource. @@ -277,5 +285,4 @@ datasources: password: "Password!" jsonData: sslmode: "disable" # disable/require/verify-ca/verify-full - -``` \ No newline at end of file +``` diff --git a/docs/sources/features/datasources/prometheus.md b/docs/sources/features/datasources/prometheus.md index 29d668e399f..4ff0baee108 100644 --- a/docs/sources/features/datasources/prometheus.md +++ b/docs/sources/features/datasources/prometheus.md @@ -101,9 +101,9 @@ The step option is useful to limit the number of events returned from your query Since 4.6.0 Grafana exposes metrics for Prometheus on the `/metrics` endpoint. We also bundle a dashboard within Grafana so you can get started viewing your metrics faster. You can import the bundled dashboard by going to the data source edit page and click the dashboard tab. There you can find a dashboard for Grafana and one for Prometheus. Import and start viewing all the metrics! -## Configure datasource with provisioning +## Configure the Datasource with Provisioning -It's now possible to configure datasources using config files with Grafanas provisioning system. You can read more about how it works and all the settings you can set for datasources on the [provisioning docs page](/administration/provisioning/#datasources) +It's now possible to configure datasources using config files with Grafana's provisioning system. You can read more about how it works and all the settings you can set for datasources on the [provisioning docs page](/administration/provisioning/#datasources) Here are some provisioning examples for this datasource. @@ -115,4 +115,4 @@ datasources: type: prometheus access: proxy url: http://localhost:9090 -``` \ No newline at end of file +``` diff --git a/docs/sources/reference/templating.md b/docs/sources/reference/templating.md index 6dbc9cc9d11..8341b9770bd 100644 --- a/docs/sources/reference/templating.md +++ b/docs/sources/reference/templating.md @@ -36,6 +36,29 @@ interpolation the variable value might be **escaped** in order to conform to the 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. +### Advanced Formatting Options + +> Only available in Grafana v5.1+. + +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 datasource 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`. This is now possible with the advanced formatting options. + +Syntax: `${var_name:option}` + +Filter Option | Example | Raw | Interpolated | Description +------------ | ------------- | ------------- | ------------- | ------------- +`glob` | ${servers:glob} | `'test1', 'test2'` | `{test1,test2}` | (Default) Formats multi-value variable into a glob (for Graphite queries) +`regex` | ${servers:regex} | `'test.', 'test2'` | (test\.|test2) | Formats multi-value variable into a regex string +`pipe` | ${servers:pipe} | `'test.', 'test2'` | test.|test2 | Formats multi-value variable into a pipe-separated string +`csv`| ${servers:csv} | `'test1', 'test2'` | `test1,test2` | Formats multi-value variable as a comma-separated string +`distributed`| ${servers:distributed} | `'test1', 'test2'` | `test1,servers=test2` | Formats multi-value variable in custom format for OpenTSDB. +`lucene`| ${servers:lucene} | `'test', 'test2'` | `("test" OR "test2")` | Formats multi-value variable as a lucene expression. + +Test the formatting options on the [Grafana Play site](http://play.grafana.org/d/cJtIfcWiz/template-variable-formatting-options?orgId=1). + +If any invalid formatting option is specified, then `glob` is the default/fallback option. + +An alternative syntax (that might be deprecated in the future) is `[[var_name:option]]`. + ### Variable options A variable is presented as a dropdown select box at the top of the dashboard. It has a current value and a set of **options**. The **options** @@ -166,7 +189,7 @@ Option | Description ------- | -------- *Multi-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. +*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 about what is a valid value for your data source. ### Formatting multiple values @@ -277,4 +300,3 @@ Variable values are always synced to the URL using the syntax `var-=val - [Graphite Templated Dashboard](http://play.grafana.org/dashboard/db/graphite-templated-nested) - [Elasticsearch Templated Dashboard](http://play.grafana.org/dashboard/db/elasticsearch-templated) - [InfluxDB Templated Dashboard](http://play.grafana.org/dashboard/db/influxdb-templated-queries) -