public/grafana
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Docs: Refactor data sources content (#57573)

Browse Source 
* Docs: Revise data source index

* Docs: Consolidate data source administration docs

* Docs: Revise panels docs related to data sources

* Docs: Revise Alertmanager data source

* Docs: Reorganize AWS CloudWatch data source docs

* Docs: Reorganize Azure Monitor data source docs

* Docs: Move azuremonitor to azure-monitor

* Docs: Revise Elasticsearch docs

* Docs: Move Elasticsearch index into bundle

* Docs: Revise GCM docs

* Docs: Revise Graphite docs

* Docs: Move Graphite index into bundle

* Docs: Revise InfluxDB docs

* Docs: Revise Jaeger docs

* Docs: Move Jaeger index into bundle

* Docs: Revise Loki docs

* Docs: Move Loki index into bundle

* Docs: Revise MS SQL docs

* Docs: Move MS SQL index into bundle

* Docs: Revise Prometheus docs

* Docs: Move Prometheus index into bundle

* Docs: Revise Tempo docs

* Docs: Move Tempo index into bundle

* Docs: Revise TestData DB docs

* Docs: Move TestData DB index into bundle

* Docs: Revise Zipkin docs

* Docs: Move Zipkin index into bundle

* Docs: Move other data sources' index pages into bundles

* Docs: Revise frontmatter

* Fixing hugo markdown errors

* Docs: Add query editor and template var sections to overview doc

* Docs: Remove CTAs across data source docs

* Docs: Remove CTA

* Docs: Remove CTA

* Docs: Fix links, images, typos, and usage consistency.

* Docs: Fix typos

* Docs: Fix CI issues

* Update docs/sources/datasources/_index.md

Co-authored-by: Torkel Ödegaard <torkel@grafana.com>

* Update docs/sources/datasources/_index.md

Co-authored-by: Torkel Ödegaard <torkel@grafana.com>

* Docs: Fix query editor links

* Update docs/sources/panels-visualizations/_index.md

Co-authored-by: Torkel Ödegaard <torkel@grafana.com>

* Update docs/sources/panels-visualizations/_index.md

Co-authored-by: Torkel Ödegaard <torkel@grafana.com>

* Docs: Rebundle child pages per writers' toolkit

* Docs: Fix prettier for CI

* Docs: Fix relrefs from outside data sources docs

* Docs: Fix broken relrefs within datasources

* Docs: Fix relrefs to data sources docs

* Fixed some more refs

Co-authored-by: Torkel Ödegaard <torkel@grafana.com>
This commit is contained in:
Garrett Guillotte
2022-11-01 10:22:06 -05:00
committed by GitHub
co-authored by Torkel Ödegaard
parent 22648d8581
commit 852d069a3c
77 changed files with 5722 additions and 4410 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/sources/datasources/influxdb/_index.md
+127 -96
View File
@@ -1,13 +1,17 @@
---
aliases:
- /docs/grafana/latest/datasources/influxdb/
- /docs/grafana/latest/features/datasources/influxdb/
- /docs/grafana/latest/datasources/influxdb/
- /docs/grafana/latest/datasources/influxdb/provision-influxdb/
- /docs/grafana/latest/data-sources/influxdb/
- /docs/grafana/latest/data-sources/influxdb/provision-influxdb/
description: Guide for using InfluxDB in Grafana
keywords:
- grafana
- influxdb
- guide
- flux
menuTitle: InfluxDB
title: InfluxDB data source
weight: 700
---
@@ -16,45 +20,40 @@ weight: 700
{{< docs/shared "influxdb/intro.md" >}}
This topic explains options, variables, querying, and other options specific to this data source. Refer to [Add a data source]({{< relref "../add-a-data-source/" >}}) for instructions on how to add a data source to Grafana. Only users with the organization admin role can add data sources.
Grafana includes built-in support for InfluxDB.
This topic explains options, variables, querying, and other features specific to the InfluxDB data source, which include its [feature-rich code editor for queries and visual query builder]({{< relref "./query-editor/" >}}).
## Data source options
For instructions on how to add a data source to Grafana, refer to the [administration documentation]({{< relref "../../administration/data-source-management/" >}}).
Only users with the organization administrator role can add data sources.
Administrators can also [configure the data source via YAML]({{< relref "#provision-the-data-source" >}}) with Grafana's provisioning system.
To access data source settings, hover your mouse over the **Configuration** (gear) icon, then click **Data sources**, and then click the data source.
Once you've added the InfluxDB data source, you can [configure it]({{< relref "#configure-the-data-source" >}}) so that your Grafana instance's users can create queries in its [query editor]({{< relref "./query-editor/" >}}) when they [build dashboards]({{< relref "../../dashboards/build-dashboards/" >}}) and use [Explore]({{< relref "../../explore/" >}}).
InfluxDB data source options differ depending on which [query language](#query-languages) you select: InfluxQL or Flux.
## Configure the data source
> **Note:** Though not required, it's a good practice to append the language choice to the data source name. For example:
**To access the data source configuration page:**
- InfluxDB-InfluxQL
- InfluxDB-Flux
1. Hover the cursor over the **Configuration** (gear) icon.
1. Select **Data Sources**.
1. Select the InfluxDB data source.
### InfluxQL (classic InfluxDB query)
Set the data source's basic configuration options carefully:
These options apply if you are using the InfluxQL query language. If you are using Flux, refer to [Flux support in Grafana]({{< relref "influxdb-flux/" >}}).
| Name | Description |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Name** | Sets the name you use to refer to the data source in panels and queries. We recommend something like `InfluxDB-InfluxQL`. |
| **Default** | Sets whether the data source is pre-selected for new panels. |
| **URL** | The HTTP protocol, IP address, and port of your InfluxDB API. InfluxDB's default API port is 8086. |
| **Min time interval** | _(Optional)_ Refer to [Min time interval]({{< relref "#configure-min-time-interval" >}}). |
| **Max series** | _(Optional)_ Limits the number of series and tables that Grafana processes. Lower this number to prevent abuse, and increase it if you have many small time series and not all are shown. Defaults to 1,000. |
| Name | Description |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Name` | The data source name. This is how you refer to the data source in panels and queries. We recommend something like `InfluxDB-InfluxQL`. |
| `Default` | Default data source means that it will be pre-selected for new panels. |
| `URL` | The HTTP protocol, IP address and port of your InfluxDB API. InfluxDB API port is by default 8086. |
| `Access` | Direct browser access has been deprecated. Use “Server (default)” or the datasource won’t function. |
| `Allowed cookies` | Cookies that will be forwarded to the data source. All other cookies will be deleted. |
| `Database` | The ID of the bucket you want to query from, copied from the [Buckets page](https://docs.influxdata.com/influxdb/v2.0/organizations/buckets/view-buckets/) of the InfluxDB UI. |
| `User` | The username you use to sign into InfluxDB. |
| `Password` | The token you use to query the bucket above, copied from the [Tokens page](https://docs.influxdata.com/influxdb/v2.0/security/tokens/view-tokens/) of the InfluxDB UI. |
| `HTTP mode` | How to query the database (`GET` or `POST` HTTP verb). The `POST` verb allows heavy queries that would return an error using the `GET` verb. Default is `GET`. |
| `Min time interval` | (Optional) Refer to [Min time interval]({{< relref "#min-time-interval" >}}). |
| `Max series` | (Optional) Limits the number of series/tables that Grafana processes. Lower this number to prevent abuse, and increase it if you have lots of small time series and not all are shown. Defaults to 1000. |
You can also configure settings specific to the InfluxDB data source:
### Flux
### Min time interval
For information on data source settings and using Flux in Grafana, refer to [Flux support in Grafana]({{< relref "influxdb-flux/" >}}).
The **Min time interval** setting defines a lower limit for the auto group-by time interval.
#### Min time interval
A lower limit for the auto group by time interval. 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 _must_ 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:
This value _must_ be formatted as a number followed by a valid time identifier:
| Identifier | Description |
| ---------- | ----------- |
@@ -67,91 +66,123 @@ This option can also be overridden/configured in a dashboard panel under data so
| `s` | second |
| `ms` | millisecond |
## Query languages
We recommend setting this value to match your InfluxDB write frequency.
For example, use `1m` if InfluxDB writes data every minute.
You can query InfluxDB using InfluxQL or Flux:
You can also override this setting in a dashboard panel under its data source options.
- [InfluxQL](https://docs.influxdata.com/influxdb/v1.8/query_language/explore-data/) is a SQL-like language for querying InfluxDB, with statements such as SELECT, FROM, WHERE, and GROUP BY that are familiar to SQL users. InfluxQL is available in InfluxDB 1.0 onwards.
- [Flux](https://docs.influxdata.com/influxdb/v2.0/query-data/get-started/) provides significantly broader functionality than InfluxQL, supporting not only queries, but built-in functions for data shaping, string manipulation, joining to non-InfluxDB data sources and more, but also processing time-series data. It’s more similar to JavaScript with a functional style.
### Select a query language
To help you choose the best language for your needs, here’s a comparison of [Flux vs InfluxQL](https://docs.influxdata.com/influxdb/v1.8/flux/flux-vs-influxql/), and [why InfluxData created Flux](https://www.influxdata.com/blog/why-were-building-flux-a-new-data-scripting-and-query-language/).
InfluxDB data source options differ depending on which query language you select:
## InfluxQL query editor
- [InfluxQL](https://docs.influxdata.com/influxdb/v1.8/query_language/explore-data/), a SQL-like language for querying InfluxDB, with statements such as SELECT, FROM, WHERE, and GROUP BY that are familiar to SQL users.
InfluxQL is available in InfluxDB 1.0 onwards.
- [Flux](https://docs.influxdata.com/influxdb/v2.0/query-data/get-started/), which provides significantly broader functionality than InfluxQL. It supports not only queries but also built-in functions for data shaping, string manipulation, and joining to non-InfluxDB data sources, but also processing time-series data.
It's similar to JavaScript with a functional style.
Enter edit mode by clicking the panel title and clicking **Edit**. The editor allows you to select metrics and tags.
To help choose the best language for your needs, refer to a [comparison of Flux vs InfluxQL](https://docs.influxdata.com/influxdb/v1.8/flux/flux-vs-influxql/) and [why InfluxData created Flux](https://www.influxdata.com/blog/why-were-building-flux-a-new-data-scripting-and-query-language/).
![InfluxQL query editor](/static/img/docs/influxdb/influxql-query-editor-8-0.png)
> **Note:** Though not required, we recommend that you append your query language choice to the data source's **Name** setting:
>
> - InfluxDB-InfluxQL
> - InfluxDB-Flux
### Filter data (WHERE)
### Configure InfluxQL
To add a tag filter, click the plus icon to the right of the `WHERE` condition. You can remove tag filters by clicking on the tag key and then selecting `--remove tag filter--`.
Configure these options if you select the InfluxQL (classic InfluxDB) query language:
**Regex matching**
| Name | Description |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Access** | Only Server access mode is functional. Direct browser access is deprecated. |
| **Allowed cookies** | Defines which cookies are forwarded to the data source. All other cookies are deleted. |
| **Database** | Sets the ID of the bucket to query. Copy this from the [Buckets page](https://docs.influxdata.com/influxdb/v2.0/organizations/buckets/view-buckets/) of the InfluxDB UI. |
| **User** | Sets the username to sign into InfluxDB. |
| **Password** | Defines the token you use to query the bucket defined in **Database**. Copy this from the [Tokens page](https://docs.influxdata.com/influxdb/v2.0/security/tokens/view-tokens/) of the InfluxDB UI. |
| **HTTP mode** | Sets the HTTP method used to query your data source. The POST verb allows for larger queries that would return an error using the GET verb. Defaults to GET. |
You can type in regex patterns for metric names or tag filter values. Be sure to wrap the regex pattern in forward slashes (`/`). Grafana automatically adjusts the filter tag condition to use the InfluxDB regex match condition operator (`=~`).
### Configure Flux
### Field and Aggregation functions
Configure these options if you select the Flux query language:
In the `SELECT` row you can specify what fields and functions you want to use. If you have a
group by time you need an aggregation function. Some functions like derivative require an aggregation function. The editor tries to simplify and unify this part of the query. For example:
| Name | Description |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Organization** | The [Influx organization](https://v2.docs.influxdata.com/v2.0/organizations/) that will be used for Flux queries. This is also used to for the `v.organization` query macro. |
| **Token** | The authentication token used for Flux queries. With Influx 2.0, use the [influx authentication token to function](https://v2.docs.influxdata.com/v2.0/security/tokens/create-token/). For influx 1.8, the token is `username:password`. |
| **Default bucket** | _(Optional)_ The [Influx bucket](https://v2.docs.influxdata.com/v2.0/organizations/buckets/) that will be used for the `v.defaultBucket` macro in Flux queries. |
![](/static/img/docs/influxdb/select_editor.png)
### Provision the data source
The above generates the following InfluxDB `SELECT` clause:
You can define and configure the data source in YAML files as part of Grafana's provisioning system.
For more information about provisioning, and for available configuration options, refer to [Provisioning Grafana]({{< relref "../../administration/provisioning/#data-sources" >}}).
```sql
SELECT derivative(mean("value"), 10s) /10 AS "REQ/s" FROM ....
#### Provisioning examples
**InfluxDB 1.x example:**
```yaml
apiVersion: 1
datasources:
- name: InfluxDB_v1
type: influxdb
access: proxy
database: site
user: grafana
url: http://localhost:8086
jsonData:
httpMode: GET
secureJsonData:
password: grafana
```
#### Select multiple fields
**InfluxDB 2.x for Flux example:**
Use the plus button and select Field > field to add another SELECT clause. You can also
specify an asterix `*` to select all fields.
```yaml
apiVersion: 1
### Group By
To group by a tag, click the plus icon at the end of the GROUP BY row. Pick a tag from the dropdown that appears.
You can remove the "Group By" by clicking on the `tag` and then click on the x icon.
### Text Editor Mode (RAW)
You can switch to raw query mode by clicking hamburger icon and then `Switch editor mode`.
> If you use Raw Query be sure your query at minimum have `WHERE $timeFilter`.
> Also, always have a group by time and an aggregation function, otherwise InfluxDB can easily return hundreds of thousands of data points that will hang the browser.
### Alias patterns
- $m = replaced with measurement name
- $measurement = replaced with measurement name
- $1 - $9 = replaced with part of measurement name (if you separate your measurement name with dots)
- $col = replaced with column name
- $tag_exampletag = replaced with the value of the `exampletag` tag. The syntax is `$tag*yourTagName`(must start with`$tag*`). To use your tag as an alias in the ALIAS BY field then the tag must be used to group by in the query.
- You can also use [[tag_hostname]] pattern replacement syntax. For example, in the ALIAS BY field using this text `Host: [[tag_hostname]]` would substitute in the `hostname` tag value for each legend value and an example legend value would be: `Host: server1`.
## Querying logs
Querying and displaying log data from InfluxDB is available in [Explore]({{< relref "../../explore/" >}}), and in the [logs panel]({{< relref "../../panels-visualizations/visualizations/logs/" >}}) in dashboards.
Select the InfluxDB data source, and then enter a query to display your logs.
### Log queries
The Logs Explorer (the `Measurements/Fields` button) next to the query field shows a list of measurements and fields. Choose the desired measurement that contains your log data and then choose which field Explore should use to display the log message.
Once the result is returned, the log panel shows a list of log rows and a bar chart where the x-axis shows the time and the y-axis shows the frequency/count.
### Filter search
To add a filter, click the plus icon to the right of the `Measurements/Fields` button or a condition. You can remove tag filters by clicking on the first select and choosing `--remove filter--`.
## Annotations
[Annotations]({{< relref "../../dashboards/build-dashboards/annotate-visualizations" >}}) allows you to overlay rich event information on top of graphs. Add annotation queries using the Annotations view in the Dashboard menu.
An example query:
```SQL
SELECT title, description from events WHERE $timeFilter ORDER BY time ASC
datasources:
- name: InfluxDB_v2_Flux
type: influxdb
access: proxy
url: http://localhost:8086
jsonData:
version: Flux
organization: organization
defaultBucket: bucket
tlsSkipVerify: true
secureJsonData:
token: token
```
For InfluxDB, you need to enter a query like the one in the example above. The `where $timeFilter` component is required. If you only select one column, then you do not need to enter anything in the column mapping fields. The **Tags** field can be a comma-separated string.
**InfluxDB 2.x for InfluxQL example:**
```yaml
apiVersion: 1
datasources:
- name: InfluxDB_v2_InfluxQL
type: influxdb
access: proxy
url: http://localhost:8086
# This database should be mapped to a bucket
database: site
jsonData:
httpMode: GET
httpHeaderName1: 'Authorization'
secureJsonData:
httpHeaderValue1: 'Token <token>'
```
## Query the data source
The InfluxDB data source's query editor has two modes, InfluxQL and Flux, depending on your choice of query language in the [data source configuration]({{< relref "#configure-the-data-source" >}}):
For details, refer to the [query editor documentation]({{< relref "./query-editor/" >}}).
## Use template variables
Instead of hard-coding details such as server, application, and sensor names in metric queries, you can use variables.
Grafana lists these variables in dropdown select boxes at the top of the dashboard to help you change the data displayed in your dashboard.
Grafana refers to such variables as template variables.
For details, see the [template variables documentation]({{< relref "./template-variables/" >}}).
docs/sources/datasources/influxdb/influxdb-flux.md
-79
View File
@@ -1,79 +0,0 @@
---
aliases:
- /docs/grafana/latest/datasources/influxdb/influxdb-flux/
description: Guide for Flux in Grafana
title: Flux support in Grafana
weight: 200
---
# Flux query language in Grafana
Grafana supports Flux running on InfluxDB 1.8+. See [1.8 compatibility](https://github.com/influxdata/influxdb-client-go/#influxdb-18-api-compatibility) for more information and connection details.
| Name | Description |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Name` | The data source name. This is how you refer to the data source in panels and queries. We recommend something like `InfluxDB-Flux`. |
| `Default` | Default data source means that it will be pre-selected for new panels. |
| `URL` | The HTTP protocol, IP address and port of your InfluxDB API. InfluxDB 2.0 API port is by default 8086. |
| `Organization` | The [Influx organization](https://v2.docs.influxdata.com/v2.0/organizations/) that will be used for Flux queries. This is also used to for the `v.organization` query macro. |
| `Token` | The authentication token used for Flux queries. With Influx 2.0, use the [influx authentication token to function](https://v2.docs.influxdata.com/v2.0/security/tokens/create-token/). For influx 1.8, the token is `username:password`. |
| `Default bucket` | (Optional) The [Influx bucket](https://v2.docs.influxdata.com/v2.0/organizations/buckets/) that will be used for the `v.defaultBucket` macro in Flux queries. |
| `Min time interval` | (Optional) Refer to [Min time interval]({{< relref "#min-time-interval" >}}). |
| `Max series` | (Optional) Limits the number of series/tables that Grafana processes. Lower this number to prevent abuse, and increase it if you have lots of small time series and not all are shown. Defaults to 1000. |
## Min time interval
A lower limit for the auto group by time interval. 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:
| Identifier | Description |
| ---------- | ----------- |
| `y` | year |
| `M` | month |
| `w` | week |
| `d` | day |
| `h` | hour |
| `m` | minute |
| `s` | second |
| `ms` | millisecond |
You can use the [Flux query and scripting language](https://www.influxdata.com/products/flux/). Grafana's Flux query editor is a text editor for raw Flux queries with Macro support.
## Supported macros
The macros support copying and pasting from [Chronograf](https://www.influxdata.com/time-series-platform/chronograf/).
| Macro example | Description |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `v.timeRangeStart` | Will be replaced by the start of the currently active time selection. For example, _2020-06-11T13:31:00Z_ |
| `v.timeRangeStop` | Will be replaced by the end of the currently active time selection. For example, _2020-06-11T14:31:00Z_ |
| `v.windowPeriod` | Will be replaced with an interval string compatible with Flux that corresponds to Grafana's calculated interval based on the time range of the active time selection. For example, _5s_ |
| `v.defaultBucket` | Will be replaced with the data source configuration's "Default Bucket" setting |
| `v.organization` | Will be replaced with the data source configuration's "Organization" setting |
For example, the following query will be interpolated as the query that follows it, with interval and time period values changing according to active time selection\):
Grafana Flux query:
```flux
from(bucket: v.defaultBucket)
|> range(start: v.timeRangeStart, stop: v.timeRangeStop)
|> filter(fn: (r) => r["_measurement"] == "cpu" or r["_measurement"] == "swap")
|> filter(fn: (r) => r["_field"] == "usage_system" or r["_field"] == "free")
|> aggregateWindow(every: v.windowPeriod, fn: mean)
|> yield(name: "mean")
```
Interpolated query send to Influx:
```flux
from(bucket: "grafana")
|> range(start: 2020-06-11T13:59:07Z, stop: 2020-06-11T14:59:07Z)
|> filter(fn: (r) => r["_measurement"] == "cpu" or r["_measurement"] == "swap")
|> filter(fn: (r) => r["_field"] == "usage_system" or r["_field"] == "free")
|> aggregateWindow(every: 2s, fn: mean)
|> yield(name: "mean")
```
You can view the interpolated version of a query with the query inspector. For more information, refer to [Panel Inspector]({{< relref "../../panels-visualizations/panel-inspector/" >}}).
docs/sources/datasources/influxdb/influxdb-templates.md
-68
View File
@@ -1,68 +0,0 @@
---
aliases:
- /docs/grafana/latest/datasources/influxdb/influxdb-templates/
description: Guide for templates in InfluxDB
title: InfluxDB templates
weight: 300
---
## InfluxDB templates
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 "../../dashboards/variables/" >}}).
## Using variables in InfluxDB queries
There are two syntaxes:
`$<varname>` Example:
```sql
SELECT mean("value") FROM "logins" WHERE "hostname" =~ /^$host$/ AND $timeFilter GROUP BY time($__interval), "hostname"
```
`[[varname]]` Example:
```sql
SELECT mean("value") FROM "logins" WHERE "hostname" =~ /^[[host]]$/ AND $timeFilter GROUP BY time($__interval), "hostname"
```
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 a word. When the **Multi-value** or **Include all value** options are enabled, Grafana converts the labels from plain text to a regex compatible string. Which means you have to use `=~` instead of `=`.
Example dashboard:
[InfluxDB Templated Dashboard](https://play.grafana.org/dashboard/db/influxdb-templated)
## 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 "../../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**.
```sql
SHOW TAG VALUES WITH KEY = "hostname"
```
## Chained or nested 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:
```sql
SHOW TAG VALUES WITH KEY = "hostname" WHERE region = '$region'
```
You can fetch key names for a given measurement.
```sql
SHOW TAG KEYS [FROM <measurement_name>]
```
If you have a variable with key names you can use this variable in a group by clause. This will allow you to change group by using the variable list at the top of the dashboard.
### Ad hoc filters variable
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 "../../dashboards/variables/add-template-variables/#add-ad-hoc-filters" >}}).
docs/sources/datasources/influxdb/provision-influxdb.md
-69
View File
@@ -1,69 +0,0 @@
---
aliases:
- /docs/grafana/latest/datasources/influxdb/provision-influxdb/
description: Guide for provisioning InfluxDB
title: Provision InfluxDB
weight: 400
---
# Provision InfluxDB
You can configure data sources using config files with Grafana's provisioning system. You can read more about how it works and all the settings you can set for data sources on the [provisioning docs page]({{< relref "../../administration/provisioning/#datasources" >}}).
Here are some provisioning examples for this data source.
## InfluxDB 1.x example
```yaml
apiVersion: 1
datasources:
- name: InfluxDB_v1
type: influxdb
access: proxy
database: site
user: grafana
url: http://localhost:8086
jsonData:
httpMode: GET
secureJsonData:
password: grafana
```
## InfluxDB 2.x for Flux example
```yaml
apiVersion: 1
datasources:
- name: InfluxDB_v2_Flux
type: influxdb
access: proxy
url: http://localhost:8086
secureJsonData:
token: token
jsonData:
version: Flux
organization: organization
defaultBucket: bucket
tlsSkipVerify: true
```
## InfluxDB 2.x for InfluxQl example
```yaml
apiVersion: 1
datasources:
- name: InfluxDB_v2_InfluxQL
type: influxdb
access: proxy
url: http://localhost:8086
# This database should be mapped to a bucket
database: site
jsonData:
httpMode: GET
httpHeaderName1: 'Authorization'
secureJsonData:
httpHeaderValue1: 'Token <token>'
```
docs/sources/datasources/influxdb/query-editor/index.md
+196
View File
@@ -0,0 +1,196 @@
---
aliases:
- /docs/grafana/latest/datasources/influxdb/influxdb-flux/
- /docs/grafana/latest/datasources/influxdb/query-editor/
- /docs/grafana/latest/data-sources/influxdb/query-editor/
description: Guide for Flux in Grafana
title: Flux support in Grafana
weight: 200
---
# InfluxDB query editor
This topic explains querying specific to the InfluxDB data source.
For general documentation on querying data sources in Grafana, see [Query and transform data]({{< relref "../../../panels-visualizations/query-transform-data" >}}).
## Choose a query editing mode
The InfluxDB data source's query editor has two modes depending on your choice of query language in the [data source configuration]({{< relref "../#configure-the-data-source" >}}):
- [InfluxQL]({{< relref "#influxql-query-editor" >}})
- [Flux]({{< relref "#flux-query-editor" >}})
You also use the query editor to retrieve [log data]({{< relref "#query-logs" >}}) and [annotate]({{< relref "#apply-annotations" >}}) visualizations.
## InfluxQL query editor
The InfluxQL query editor helps you select metrics and tags to create InfluxQL queries.
**To enter edit mode:**
1. Click the panel title.
1. Click **Edit**.
![InfluxQL query editor](/static/img/docs/influxdb/influxql-query-editor-8-0.png)
### Filter data (WHERE)
To add a tag filter, click the plus icon to the right of the `WHERE` condition.
To remove tag filters, click the tag key, then select **--remove tag filter--**.
#### Match by regular expressions
You can enter regular expressions for metric names or tag filter values.
Wrap the regex pattern in forward slashes (`/`).
Grafana automatically adjusts the filter tag condition to use the InfluxDB regex match condition operator (`=~`).
### Field and aggregation functions
In the `SELECT` row, you can specify which fields and functions to use.
If you have a group by time, you must have an aggregation function.
Some functions like `derivative` also require an aggregation function.
The editor helps you build this part of the query.
For example:
![](/static/img/docs/influxdb/select_editor.png)
This query editor input generates an InfluxDB `SELECT` clause:
```sql
SELECT derivative(mean("value"), 10s) /10 AS "REQ/s" FROM ....
```
**To select multiple fields:**
1. Click the plus button.
1. Select **Field > field** to add another `SELECT` clause.
You can also `SELECT` an asterisk (`*`) to select all fields.
### Group query results
To group results by a tag, define it in a "Group By".
**To group by a tag:**
1. Click the plus icon at the end of the GROUP BY row.
1. Select a tag from the dropdown that appears.
**To remove the "Group By":**
1. Click the tag.
1. Click the "x" icon.
### Text editor mode (RAW)
You can write raw InfluxQL queries by switching the editor mode.
However, be careful when writing queries manually.
If you use raw query mode, your query _must_ include at least `WHERE $timeFilter`.
Also, _always_ provide a group by time and an aggregation function.
Otherwise, InfluxDB can easily return hundreds of thousands of data points that can hang your browser.
**To switch to raw query mode:**
1. Click the hamburger icon.
1. Toggle **Switch editor mode**.
### Alias patterns
| Alias pattern | Replaced with |
| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `$m` | Measurement name. |
| `$measurement` | Measurement name. |
| `$1` - `$9` | Part of measurement name (if you separate your measurement name with dots). |
| `$col` | Column name. |
| `$tag_exampletag` | The value of the `exampletag` tag. The syntax is `$tag*yourTagName` and must start with `$tag*`. To use your tag as an alias in the ALIAS BY field, you must use the tag to group by in the query. |
You can also use `[[tag_hostname]]` pattern replacement syntax.
For example, entering the value `Host: [[tag_hostname]]` in the ALIAS BY field replaces it with the `hostname` tag value for each legend value.
An example legend value would be `Host: server1`.
## Flux query editor
Grafana supports Flux when running InfluxDB v1.8 and higher.
If your data source is [configured for Flux]({{< relref "./#configure-the-data-source" >}}), you can use the [Flux query and scripting language](https://www.influxdata.com/products/flux/) in the query editor, which serves as a text editor for raw Flux queries with macro support.
For more information and connection details, refer to [1.8 compatibility](https://github.com/influxdata/influxdb-client-go/#influxdb-18-api-compatibility).
### Use macros
You can enter macros in the query to replace them with values from Grafana's context.
Macros support copying and pasting from [Chronograf](https://www.influxdata.com/time-series-platform/chronograf/).
| Macro example | Replaced with |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `v.timeRangeStart` | The start of the currently active time selection, such as `2020-06-11T13:31:00Z`. |
| `v.timeRangeStop` | The end of the currently active time selection, such as `2020-06-11T14:31:00Z`. |
| `v.windowPeriod` | An interval string compatible with Flux that corresponds to Grafana's calculated interval based on the time range of the active time selection, such as `5s`. |
| `v.defaultBucket` | The data source configuration's "Default Bucket" setting. |
| `v.organization` | The data source configuration's "Organization" setting. |
For example, the query editor interpolates this query:
```flux
from(bucket: v.defaultBucket)
|> range(start: v.timeRangeStart, stop: v.timeRangeStop)
|> filter(fn: (r) => r["_measurement"] == "cpu" or r["_measurement"] == "swap")
|> filter(fn: (r) => r["_field"] == "usage_system" or r["_field"] == "free")
|> aggregateWindow(every: v.windowPeriod, fn: mean)
|> yield(name: "mean")
```
Into this query to send to InfluxDB, with interval and time period values changing according to the active time selection:
```flux
from(bucket: "grafana")
|> range(start: 2020-06-11T13:59:07Z, stop: 2020-06-11T14:59:07Z)
|> filter(fn: (r) => r["_measurement"] == "cpu" or r["_measurement"] == "swap")
|> filter(fn: (r) => r["_field"] == "usage_system" or r["_field"] == "free")
|> aggregateWindow(every: 2s, fn: mean)
|> yield(name: "mean")
```
To view the interpolated version of a query with the query inspector, refer to [Panel Inspector]({{< relref "../../../panels-visualizations/panel-inspector" >}}).
## Query logs
You can query and display log data from InfluxDB in [Explore]({{< relref "../../../explore" >}}) and with the [Logs panel]({{< relref "../../../panels-visualizations/visualizations/logs" >}}) for dashboards.
Select the InfluxDB data source, then enter a query to display your logs.
### Create log queries
The Logs Explorer next to the query field, accessed by the **Measurements/Fields** button, lists measurements and fields.
Choose the desired measurement that contains your log data, then choose which field to use to display the log message.
Once InfluxDB returns the result, the log panel lists log rows and displays a bar chart, where the x axis represents the time and the y axis represents the frequency/count.
### Filter search
To add a filter, click the plus icon to the right of the **Measurements/Fields** button, or next to a condition.
To remove tag filters, click the first select, then choose **--remove filter--**.
## Apply annotations
[Annotations]({{< relref "../../../dashboards/build-dashboards/annotate-visualizations" >}}) overlay rich event information on top of graphs.
You can add annotation queries in the Dashboard menu's Annotations view.
For InfluxDB, your query **must** include `WHERE $timeFilter`.
If you select only one column, you don't need to enter anything in the column mapping fields.
The **Tags** field's value can be a comma-separated string.
### Annotation query example
```sql
SELECT title, description from events WHERE $timeFilter ORDER BY time ASC
```
docs/sources/datasources/influxdb/template-variables/index.md
+85
View File
@@ -0,0 +1,85 @@
---
aliases:
- /docs/grafana/latest/datasources/influxdb/influxdb-templates/
- /docs/grafana/latest/data-sources/influxdb/influxdb-templates/
- /docs/grafana/latest/data-sources/influxdb/template-variables/
description: Guide for template variables in InfluxDB
keywords:
- grafana
- influxdb
- queries
- template
- variable
menuTitle: Template variables
title: InfluxDB template variables
weight: 300
---
# InfluxDB template variables
Instead of hard-coding details such as server, application, and sensor names in metric queries, you can use variables.
Grafana lists these variables in dropdown select boxes at the top of the dashboard to help you change the data displayed in your dashboard.
Grafana refers to such variables as template variables.
For an introduction to templating and template variables, refer to the [Templating]({{< relref "../../../dashboards/variables" >}}) and [Add and manage variables]({{< relref "../../../dashboards/variables/add-template-variables" >}}) documentation.
## Use query variables
If you add a query template variable, you can write an InfluxDB exploration (metadata) query.
These queries can return results 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, to create a variable that contains all values for tag `hostname`, specify a query like this in the query variable **Query**:
```sql
SHOW TAG VALUES WITH KEY = "hostname"
```
### Chain or nest variables
You can also create nested variables, sometimes called [chained variables]({{< relref "../../../dashboards/variables/add-template-variables#chained-variables" >}}).
For example, if you had a variable called `region`, you could have the `hosts` variable show only hosts from the selected region with a query like:
```sql
SHOW TAG VALUES WITH KEY = "hostname" WHERE region = '$region'
```
You can fetch key names for a given measurement:
```sql
SHOW TAG KEYS [FROM <measurement_name>]
```
If you have a variable with key names, you can use this variable in a group-by clause.
This helps you change group-by using the variable list at the top of the dashboard.
### Use ad hoc filters
InfluxDB supports the special **Ad hoc filters** variable type.
You can use this variable type to specify any number of key/value filters, and Grafana applies them automatically to all of your InfluxDB queries.
For more information, refer to [Add ad hoc filters]({{< relref "../../../dashboards/variables/add-template-variables#add-ad-hoc-filters" >}}).
## Choose a variable syntax
The InfluxDB data source supports two variable syntaxes for use in the **Query** field:
- `$<varname>`, which is easier to read and write but does not allow you to use a variable in the middle of a word.
```sql
SELECT mean("value") FROM "logins" WHERE "hostname" =~ /^$host$/ AND $timeFilter GROUP BY time($__interval), "hostname"
```
- `${varname}`
```sql
SELECT mean("value") FROM "logins" WHERE "hostname" =~ /^[[host]]$/ AND $timeFilter GROUP BY time($__interval), "hostname"
```
When you enable the **Multi-value** or **Include all value** options, Grafana converts the labels from plain text to a regex-compatible string, so you must use `=~` instead of `=`.
### Templated dashboard example
To view an example templated dashboard, refer to [InfluxDB Templated Dashboard](https://play.grafana.org/dashboard/db/influxdb-templated).