mirror of
https://github.com/grafana/grafana.git
synced 2025-02-25 18:55:37 -06:00
Docs: Update InfluxDB data source documentation (#96343)
* created config doc, made initial changes * initial draft of config doc completed * additional edits * moved config doc into directory, renamed * made additional updates * template variables updates/cleanup * cleaned up intro page, some more minor edits * edited and re-formatted configure the data source doc * final edits * more edits * minor changes prior to PR * fix typo * Update docs/sources/datasources/influxdb/_index.md Co-authored-by: Jack Baldry <jack.baldry@grafana.com> * Update docs/sources/datasources/influxdb/_index.md Co-authored-by: Jack Baldry <jack.baldry@grafana.com> * Update docs/sources/datasources/influxdb/_index.md Co-authored-by: Jack Baldry <jack.baldry@grafana.com> * Update docs/sources/datasources/influxdb/_index.md Co-authored-by: Jack Baldry <jack.baldry@grafana.com> * Update docs/sources/datasources/influxdb/_index.md Co-authored-by: Jack Baldry <jack.baldry@grafana.com> * Update docs/sources/datasources/influxdb/query-editor/index.md Co-authored-by: Jack Baldry <jack.baldry@grafana.com> * Update docs/sources/datasources/influxdb/query-editor/index.md Co-authored-by: Jack Baldry <jack.baldry@grafana.com> * Update docs/sources/datasources/influxdb/template-variables/index.md Co-authored-by: Jack Baldry <jack.baldry@grafana.com> * Update docs/sources/datasources/influxdb/query-editor/index.md Co-authored-by: Jack Baldry <jack.baldry@grafana.com> * Update docs/sources/datasources/influxdb/configure-influxdb-data-source/_index.md Co-authored-by: Jack Baldry <jack.baldry@grafana.com> * Update docs/sources/datasources/influxdb/query-editor/index.md Co-authored-by: Jack Baldry <jack.baldry@grafana.com> * updates based on feedback * ran prettier --------- Co-authored-by: Irene Rodríguez <irene.rodriguez@grafana.com> Co-authored-by: Jack Baldry <jack.baldry@grafana.com>
This commit is contained in:
Larissa Wandzura
GitHub
parent
3e79ead240
commit
26be86ee15
@ -4,7 +4,7 @@ aliases:
|
|||||||
- ../data-sources/influxdb/provision-influxdb/
|
- ../data-sources/influxdb/provision-influxdb/
|
||||||
- ../features/datasources/influxdb/
|
- ../features/datasources/influxdb/
|
||||||
- provision-influxdb/
|
- provision-influxdb/
|
||||||
description: Guide for using InfluxDB in Grafana
|
description: InfluxDB data source for Grafana
|
||||||
keywords:
|
keywords:
|
||||||
- grafana
|
- grafana
|
||||||
- influxdb
|
- influxdb
|
||||||
@ -19,242 +19,42 @@ menuTitle: InfluxDB
|
|||||||
title: InfluxDB data source
|
title: InfluxDB data source
|
||||||
weight: 700
|
weight: 700
|
||||||
refs:
|
refs:
|
||||||
explore:
|
annotations:
|
||||||
- pattern: /docs/grafana/
|
- pattern: /docs/grafana/
|
||||||
destination: /docs/grafana/<GRAFANA_VERSION>/explore/
|
destination: /docs/grafana/<GRAFANA_VERSION>/dashboards/build-dashboards/annotate-visualizations/
|
||||||
- pattern: /docs/grafana-cloud/
|
- pattern: /docs/grafana-cloud/
|
||||||
destination: /docs/grafana/<GRAFANA_VERSION>/explore/
|
destination: /docs/grafana-cloud/visualizations/dashboards/build-dashboards/annotate-visualizations/
|
||||||
build-dashboards:
|
alerting:
|
||||||
- pattern: /docs/grafana/
|
- pattern: /docs/grafana/
|
||||||
destination: /docs/grafana/<GRAFANA_VERSION>/dashboards/build-dashboards/
|
destination: /docs/grafana/<GRAFANA_VERSION>/alerting/
|
||||||
- pattern: /docs/grafana-cloud/
|
- pattern: /docs/grafana-cloud/
|
||||||
destination: /docs/grafana/<GRAFANA_VERSION>/dashboards/build-dashboards/
|
destination: /docs/grafana-cloud/alerting-and-irm/alerting/
|
||||||
data-source-management:
|
transformations:
|
||||||
- pattern: /docs/grafana/
|
- pattern: /docs/grafana/
|
||||||
destination: /docs/grafana/<GRAFANA_VERSION>/administration/data-source-management/
|
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/query-transform-data/transform-data/
|
||||||
|
- pattern: /docs/grafana-cloud/
|
||||||
|
destination: /docs/grafana-cloud/visualizations/panels-visualizations/query-transform-data/transform-data/
|
||||||
---
|
---
|
||||||
|
|
||||||
# InfluxDB data source
|
# InfluxDB data source
|
||||||
|
|
||||||
{{< docs/shared lookup="influxdb/intro.md" source="grafana" version="<GRAFANA_VERSION>" >}}
|
{{< docs/shared lookup="influxdb/intro.md" source="grafana" version="<GRAFANA_VERSION>" >}}
|
||||||
|
|
||||||
Grafana includes built-in support for InfluxDB.
|
Grafana includes built-in support for InfluxDB. You do not have to install a plugin to add the InfluxDB data source.
|
||||||
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" >}}).
|
|
||||||
|
|
||||||
For instructions on how to add a data source to Grafana, refer to
|
Grafana offers multiple configuration options for the InfluxDB data source, including a choice of three query languages and a robust query editor that includes both a code editor and a visual query builder.
|
||||||
the [administration documentation](ref:data-source-management).
|
|
||||||
Only users with the organization administrator role can add data sources.
|
|
||||||
Administrators can also [configure the data source via YAML](#provision-the-data-source) with Grafana's provisioning
|
|
||||||
system.
|
|
||||||
|
|
||||||
Once you've added the InfluxDB data source, you can [configure it](#configure-the-data-source) so that your Grafana
|
## Get started with the InfluxDB data source
|
||||||
instance's users can create queries in its [query editor]({{< relref "./query-editor" >}}) when
|
|
||||||
they [build dashboards](ref:build-dashboards) and use [Explore](ref:explore).
|
|
||||||
|
|
||||||
## Configure the data source
|
The following documents will help you get started with the InfluxDB data source in Grafana:
|
||||||
|
|
||||||
To configure basic settings for the data source, complete the following steps:
|
- [Get started with Grafana and InfluxDB](/docs/grafana/<GRAFANA_VERSION>/getting-started/get-started-grafana-influxdb/)
|
||||||
|
- [Configure the InfluxDB data source](./configure-influxdb-data-source/)
|
||||||
|
- [InfluxDB query editor](./query-editor/)
|
||||||
|
- [InfluxDB templates and variables](./template-variables/)
|
||||||
|
|
||||||
1. Click **Connections** in the left-side menu.
|
Once you have configured the data source you can:
|
||||||
1. Under Your connections, click **Data sources**.
|
|
||||||
1. Enter `InfluxDB` in the search bar.
|
|
||||||
1. Select **InfluxDB**.
|
|
||||||
|
|
||||||
The **Settings** tab of the data source is displayed.
|
- Add [annotations](ref:annotations)
|
||||||
|
- Set up [alerting](ref:alerting)
|
||||||
1. Set the data source's basic configuration options carefully:
|
- Add [transformations](ref:transformations)
|
||||||
|
|
||||||
| 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](#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. |
|
|
||||||
|
|
||||||
You can also configure settings specific to the InfluxDB data source. These options are described in the sections below.
|
|
||||||
|
|
||||||
### Min time interval
|
|
||||||
|
|
||||||
The **Min time interval** setting defines a lower limit for the auto group-by time interval.
|
|
||||||
|
|
||||||
This value _must_ be formatted as a number followed by a valid time identifier:
|
|
||||||
|
|
||||||
| Identifier | Description |
|
|
||||||
| ---------- | ----------- |
|
|
||||||
| `y` | year |
|
|
||||||
| `M` | month |
|
|
||||||
| `w` | week |
|
|
||||||
| `d` | day |
|
|
||||||
| `h` | hour |
|
|
||||||
| `m` | minute |
|
|
||||||
| `s` | second |
|
|
||||||
| `ms` | millisecond |
|
|
||||||
|
|
||||||
We recommend setting this value to match your InfluxDB write frequency.
|
|
||||||
For example, use `1m` if InfluxDB writes data every minute.
|
|
||||||
|
|
||||||
You can also override this setting in a dashboard panel under its data source options.
|
|
||||||
|
|
||||||
### Select a query language
|
|
||||||
|
|
||||||
InfluxDB data source options differ depending on which query language you select:
|
|
||||||
|
|
||||||
- [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.
|
|
||||||
- [SQL](https://www.influxdata.com/products/sql/) native SQL language with
|
|
||||||
support [FlightSQL](https://www.influxdata.com/glossary/apache-arrow-flight-sql/).
|
|
||||||
- [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.
|
|
||||||
|
|
||||||
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/).
|
|
||||||
|
|
||||||
{{% admonition type="note" %}}
|
|
||||||
Though not required, we recommend that you append your query language choice to the data source's **Name** setting:
|
|
||||||
|
|
||||||
- InfluxDB-InfluxQL
|
|
||||||
- InfluxDB-SQL
|
|
||||||
- InfluxDB-Flux
|
|
||||||
|
|
||||||
{{% /admonition %}}
|
|
||||||
|
|
||||||
### Configure InfluxQL
|
|
||||||
|
|
||||||
Configure these options if you select the InfluxQL (classic InfluxDB) query language:
|
|
||||||
|
|
||||||
| Name | Description |
|
|
||||||
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
||||||
| **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. |
|
|
||||||
|
|
||||||
### Configure SQL
|
|
||||||
|
|
||||||
Configure these options if you select the SQL query language:
|
|
||||||
|
|
||||||
| Name | Description |
|
|
||||||
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
||||||
| **Database** | Sets the ID of the bucket to query. Copy this from the Buckets page of the InfluxDB UI. |
|
|
||||||
| **Token** | API token used for SQL queries. It can be generated on InfluxDB Cloud dashboard under [Load Data > API Tokens](https://docs.influxdata.com/influxdb/cloud-serverless/get-started/setup/#create-an-all-access-api-token) menu. |
|
|
||||||
| **Insecure Connection** | Disable gRPC TLS security. |
|
|
||||||
|
|
||||||
### Configure Flux
|
|
||||||
|
|
||||||
Configure these options if you select the Flux query language:
|
|
||||||
|
|
||||||
| 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/). Token must be set as `Authorization` header with the value `Token <generated-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. |
|
|
||||||
|
|
||||||
### Provision the data source
|
|
||||||
|
|
||||||
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][provisioning-data-sources].
|
|
||||||
|
|
||||||
{{% admonition type="note" %}}
|
|
||||||
`database` [field is deprecated](https://github.com/grafana/grafana/pull/58647).
|
|
||||||
We suggest to use `dbName` field in `jsonData`. Please see the examples below.
|
|
||||||
No need to change existing provisioning settings.
|
|
||||||
{{% /admonition %}}
|
|
||||||
|
|
||||||
#### Provisioning examples
|
|
||||||
|
|
||||||
**InfluxDB 1.x example:**
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
apiVersion: 1
|
|
||||||
|
|
||||||
datasources:
|
|
||||||
- name: InfluxDB_v1
|
|
||||||
type: influxdb
|
|
||||||
access: proxy
|
|
||||||
user: grafana
|
|
||||||
url: http://localhost:8086
|
|
||||||
jsonData:
|
|
||||||
dbName: site
|
|
||||||
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
|
|
||||||
jsonData:
|
|
||||||
version: Flux
|
|
||||||
organization: organization
|
|
||||||
defaultBucket: bucket
|
|
||||||
tlsSkipVerify: true
|
|
||||||
secureJsonData:
|
|
||||||
token: token
|
|
||||||
```
|
|
||||||
|
|
||||||
**InfluxDB 2.x for InfluxQL example:**
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
apiVersion: 1
|
|
||||||
|
|
||||||
datasources:
|
|
||||||
- name: InfluxDB_v2_InfluxQL
|
|
||||||
type: influxdb
|
|
||||||
access: proxy
|
|
||||||
url: http://localhost:8086
|
|
||||||
jsonData:
|
|
||||||
dbName: site
|
|
||||||
httpHeaderName1: 'Authorization'
|
|
||||||
secureJsonData:
|
|
||||||
httpHeaderValue1: 'Token <token>'
|
|
||||||
```
|
|
||||||
|
|
||||||
**InfluxDB 3.x for SQL example:**
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
apiVersion: 1
|
|
||||||
|
|
||||||
datasources:
|
|
||||||
- name: InfluxDB_v3_InfluxQL
|
|
||||||
type: influxdb
|
|
||||||
access: proxy
|
|
||||||
url: http://localhost:8086
|
|
||||||
jsonData:
|
|
||||||
version: SQL
|
|
||||||
dbName: site
|
|
||||||
httpMode: POST
|
|
||||||
insecureGrpc: false
|
|
||||||
secureJsonData:
|
|
||||||
token: '<api-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](#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" >}}).
|
|
||||||
|
|||||||
@ -0,0 +1,259 @@
|
|||||||
|
---
|
||||||
|
aliases:
|
||||||
|
- ../data-sources/influxdb/
|
||||||
|
- ../data-sources/influxdb/provision-influxdb/
|
||||||
|
- ../features/datasources/influxdb/
|
||||||
|
- provision-influxdb/
|
||||||
|
description: Guide for using InfluxDB in Grafana
|
||||||
|
keywords:
|
||||||
|
- grafana
|
||||||
|
- influxdb
|
||||||
|
- guide
|
||||||
|
- flux
|
||||||
|
labels:
|
||||||
|
products:
|
||||||
|
- cloud
|
||||||
|
- enterprise
|
||||||
|
- oss
|
||||||
|
menuTitle: Configure the InfluxDB data source
|
||||||
|
title: Configure the InfluxDB data source
|
||||||
|
weight: 300
|
||||||
|
refs:
|
||||||
|
provision-grafana:
|
||||||
|
- pattern: /docs/grafana/
|
||||||
|
destination: /docs/grafana/<GRAFANA_VERSION>/administration/provisioning/#provision-grafana
|
||||||
|
- pattern: /docs/grafana-cloud/
|
||||||
|
destination: /docs/grafana/<GRAFANA_VERSION>/administration/provisioning/#provision-grafana
|
||||||
|
---
|
||||||
|
|
||||||
|
# Configure the InfluxDB data source
|
||||||
|
|
||||||
|
This document provides instructions for configuring the InfluxDB data source and explains the available configuration options.
|
||||||
|
|
||||||
|
## Before you begin
|
||||||
|
|
||||||
|
To configure the InfluxDB data source you must have the `Administrator` role.
|
||||||
|
|
||||||
|
{{< admonition type="note" >}}
|
||||||
|
Select the query language you want to use with InfluxDB before adding the InfluxDB data source. Configuration options differ based on query language type.
|
||||||
|
{{< /admonition >}}
|
||||||
|
|
||||||
|
InfluxData provides three query languages. Some key points to consider:
|
||||||
|
|
||||||
|
- SQL is only available for InfluxDB v3.x.
|
||||||
|
- Flux is a functional data scripting language for InfluxDB 2.x. Refer to [Query InfluxDB with Flux](https://docs.influxdata.com/influxdb/cloud/query-data/get-started/query-influxdb/) for a basic guide on working with Flux.
|
||||||
|
- InfluxQL is SQL-like query language developed by InfluxData. It doesn't support more advanced functions such as JOINs.
|
||||||
|
|
||||||
|
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/).
|
||||||
|
|
||||||
|
## Add the InfluxDB data source
|
||||||
|
|
||||||
|
Complete the following steps to set up a new InfluxDB data source:
|
||||||
|
|
||||||
|
1. Click **Connections** in the left-side menu.
|
||||||
|
2. Click **Add new connection**.
|
||||||
|
3. Type `InfluxDB` in the search bar.
|
||||||
|
4. Select the **InfluxDB** data source.
|
||||||
|
5. Click **Add new data source** in the upper right.
|
||||||
|
|
||||||
|
You are taken to the **Settings** tab where you will configure the data source.
|
||||||
|
|
||||||
|
## InfluxDB common configuration options
|
||||||
|
|
||||||
|
The following configuration options apply to **all three query language options**.
|
||||||
|
|
||||||
|
- **Name** - Sets the name you use to refer to the data source in panels and queries. Examples: `InfluxDB-InfluxQL`, `InfluxDB_SQL`.
|
||||||
|
- **Default** - Toggle to set as the default data source.
|
||||||
|
- **Query language** - Select the query language for your InfluxDB instance. The three options are:
|
||||||
|
- **InfluxQL** - SQL-like language for querying InfluxDB, with statements such as SELECT, FROM, WHERE, and GROUP BY that are familiar to SQL users.
|
||||||
|
- **SQL** - Native SQL language starting with InfluxDB v.3.0. Refer to InfluxData's [SQL reference documentation](https://docs.influxdata.com/influxdb/cloud-serverless/reference/sql/) for a list of supported statements, operators, and functions.
|
||||||
|
- **Flux** - Flux is a data scripting language developed by InfluxData that allows you to query, analyze, and act on data. Refer to [Get started with Flux](https://docs.influxdata.com/influxdb/cloud/query-data/get-started/) for guidance on using Flux.
|
||||||
|
|
||||||
|
**HTTP section:**
|
||||||
|
|
||||||
|
- **URL** - The HTTP protocol, IP address, and port of your InfluxDB API. InfluxDB’s default API port is `8086`.
|
||||||
|
- **Allowed cookies** - Defines which cookies are forwarded to the data source. All other cookies are deleted by default.
|
||||||
|
- **Timeout** - Set an HTTP request timeout in seconds.
|
||||||
|
|
||||||
|
**Auth section:**
|
||||||
|
|
||||||
|
- **Basic auth** - The most common authentication method. Use your InfluxData user name and password to authenticate. Toggling requires you to add the user and password under **Basic auth details**.
|
||||||
|
- **With credentials** - Toggle to enable credentials such as cookies or auth headers to be sent with cross-site requests.
|
||||||
|
- **TLS client auth** - Toggle to use client authentication. When enabled, add the `Server name`, `Client cert` and `Client key` under the **TLS/SSL auth details** section. The client provides a certificate that the server validates to establish the client’s trusted identity. The client key encrypts the data between client and server.
|
||||||
|
- **With CA cert** - Authenticate with a CA certificate. Follow the instructions of your CA (Certificate Authority) to download the certificate file.
|
||||||
|
- **Skip TLS verify** - Toggle to bypass TLS certificate validation.
|
||||||
|
- **Forward OAuth identity** - Forward the OAuth access token (and also the OIDC ID token if available) of the user querying the data source.
|
||||||
|
|
||||||
|
**Basic auth details:**
|
||||||
|
|
||||||
|
If you enable **Basic auth** under the Auth section you need to configure the following:
|
||||||
|
|
||||||
|
- **User** - Add the username used to sign in to InfluxDB.
|
||||||
|
- **Password** - Defines the token you use to query the bucket defined in **Database**. Retrieve this from the [Tokens page](https://docs.influxdata.com/influxdb/v2.0/security/tokens/view-tokens/) in the InfluxDB UI.
|
||||||
|
|
||||||
|
**TLS/SSL auth details:**
|
||||||
|
|
||||||
|
TLS/SSL certificates are encrypted and stored in the Grafana database.
|
||||||
|
|
||||||
|
- **CA cert** - If you toggle **With CA cert** add your self-signed cert here.
|
||||||
|
- **Server name** - Name of the server. Example: server1.domain.com
|
||||||
|
- **Client cert** - Add the client certificate.
|
||||||
|
- **Client key** - Add the client key.
|
||||||
|
|
||||||
|
**Custom HTTP headers:**
|
||||||
|
|
||||||
|
- **Header** - Add a custom HTTP header. Select an option from the drop-down. Allows custom headers to be passed based on the needs of your InfluxDB instance.
|
||||||
|
- **Value** - The value for the header.
|
||||||
|
|
||||||
|
**Private data source connect:**
|
||||||
|
|
||||||
|
- **Private data source connect** - _Only for Grafana Cloud users._ Private data source connect, or PDC, allows you to establish a private, secured connection between a Grafana Cloud instance, or stack, and data sources secured within a private network. Click the drop-down to locate the URL for PDC. For more information regarding Grafana PDC refer to [Private data source connect (PDC)](https://grafana.com/docs/grafana-cloud/connect-externally-hosted/private-data-source-connect/).
|
||||||
|
|
||||||
|
Click **Manage private data source connect** to be taken to your PDC connection page, where you'll find your PDC configuration details.
|
||||||
|
|
||||||
|
Once you have added your connection settings, click **Save & test** to test the data source connection.
|
||||||
|
|
||||||
|
### InfluxQL-specific configuration section
|
||||||
|
|
||||||
|
The following settings are specific to the InfluxQL query language option.
|
||||||
|
|
||||||
|
**InfluxQL InfluxDB details section:**
|
||||||
|
|
||||||
|
- **Database** - Sets the ID of the bucket to query. Refer to [View buckets](https://docs.influxdata.com/influxdb/v2.0/organizations/buckets/view-buckets/) in InfluxData's documentation on how to locate the list of available buckets and their corresponding IDs.
|
||||||
|
- **User** - The user name used to sign in to InfluxDB.
|
||||||
|
- **Password** - Defines the token used to query the bucket defined in **Database**. Retrieve the password from the [Tokens page](https://docs.influxdata.com/influxdb/v2.0/security/tokens/view-tokens/) of the InfluxDB UI.
|
||||||
|
- **HTTP method** - Sets the HTTP method used to query your data source. The POST method allows for larger queries that would return an error using the GET method. The default method is `POST`.
|
||||||
|
- **Min time interval** - _(Optional)_ Sets the minimum time interval for auto group-by. Grafana recommends setting this to match the data write frequency. For example, if your data is written every minute, it’s recommended to set this interval to 1 minute, so that each group contains data from each new write. The default is `10s`. Refer to [Min time interval](#min-time-interval) for format examples.
|
||||||
|
- **Max series** - _(Optional)_ Sets a limit on the maximum number of series or tables that Grafana processes. Set a lower limit to prevent system overload, or increase it if you have many small time series and need to display more of them. The default is `1000`.
|
||||||
|
|
||||||
|
### SQL-specific configuration section
|
||||||
|
|
||||||
|
The following settings are specific to the SQL query language option.
|
||||||
|
|
||||||
|
**SQL InfluxDB details section:**
|
||||||
|
|
||||||
|
- **Database** - Specify the **bucket ID**. Refer to the **Buckets page** in the InfluxDB UI to locate the ID.
|
||||||
|
- **Token** The API token used for SQL queries. Generated on InfluxDB Cloud dashboard under [Load Data > API Tokens](https://docs.influxdata.com/influxdb/cloud-serverless/get-started/setup/#create-an-all-access-api-token) menu.
|
||||||
|
- **Insecure Connection** - Toggle to disable gRPC TLS security.
|
||||||
|
- **Max series** - _(Optional)_ Sets a limit on the maximum number of series or tables that Grafana processes. Set a lower limit to prevent system overload, or increase it if you have many small time series and need to display more of them. The default is `1000`.
|
||||||
|
|
||||||
|
### Flux-specific configuration section
|
||||||
|
|
||||||
|
The following settings are specific to the Flux query language option.
|
||||||
|
|
||||||
|
**Flux InfluxDB details section:**
|
||||||
|
|
||||||
|
- **Organization** - The [Influx organization](https://v2.docs.influxdata.com/v2.0/organizations/) used for Flux queries. Also used 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/). Token must be set as `Authorization` header with the value `Token <generated-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/) used for the `v.defaultBucket` macro in Flux queries.
|
||||||
|
- **Min time interval** - Sets the minimum time interval for auto group-by. Grafana recommends aligning this setting with the data write frequency. For example, if data is written every minute, set the interval to 1 minute to ensure each group includes data from every new write. The default is `10s`.
|
||||||
|
- **Max series** - Sets a limit on the maximum number of series or tables that Grafana processes. Set a lower limit to prevent system overload, or increase it if you have many small time series and need to display more of them. The default is `1000`.
|
||||||
|
|
||||||
|
### Min time interval
|
||||||
|
|
||||||
|
The **Min time interval** setting defines a lower limit for the auto group-by time interval.
|
||||||
|
|
||||||
|
This value **must be** formatted as a number followed by a valid time identifier:
|
||||||
|
|
||||||
|
| Identifier | Description |
|
||||||
|
| ---------- | ----------- |
|
||||||
|
| `y` | year |
|
||||||
|
| `M` | month |
|
||||||
|
| `w` | week |
|
||||||
|
| `d` | day |
|
||||||
|
| `h` | hour |
|
||||||
|
| `m` | minute |
|
||||||
|
| `s` | second |
|
||||||
|
| `ms` | millisecond |
|
||||||
|
|
||||||
|
You can also override this setting in a dashboard panel under its data source options.
|
||||||
|
|
||||||
|
## Provision the InfluxDB data source
|
||||||
|
|
||||||
|
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 [Provision Grafana](ref:provision-grafana).
|
||||||
|
|
||||||
|
{{% admonition type="note" %}}
|
||||||
|
The `database` [field is deprecated](https://github.com/grafana/grafana/pull/58647).
|
||||||
|
Grafana recommends using the `dbName` field in `jsonData`. There is no need to change existing provisioning settings.
|
||||||
|
{{% /admonition %}}
|
||||||
|
|
||||||
|
### Provisioning examples
|
||||||
|
|
||||||
|
Provisioning differs based on query language.
|
||||||
|
|
||||||
|
**InfluxDB 1.x example:**
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
apiVersion: 1
|
||||||
|
|
||||||
|
datasources:
|
||||||
|
- name: InfluxDB_v1
|
||||||
|
type: influxdb
|
||||||
|
access: proxy
|
||||||
|
user: grafana
|
||||||
|
url: http://localhost:8086
|
||||||
|
jsonData:
|
||||||
|
dbName: site
|
||||||
|
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
|
||||||
|
jsonData:
|
||||||
|
version: Flux
|
||||||
|
organization: organization
|
||||||
|
defaultBucket: bucket
|
||||||
|
tlsSkipVerify: true
|
||||||
|
secureJsonData:
|
||||||
|
token: token
|
||||||
|
```
|
||||||
|
|
||||||
|
**InfluxDB 2.x for InfluxQL example:**
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
apiVersion: 1
|
||||||
|
|
||||||
|
datasources:
|
||||||
|
- name: InfluxDB_v2_InfluxQL
|
||||||
|
type: influxdb
|
||||||
|
access: proxy
|
||||||
|
url: http://localhost:8086
|
||||||
|
jsonData:
|
||||||
|
dbName: site
|
||||||
|
httpHeaderName1: 'Authorization'
|
||||||
|
secureJsonData:
|
||||||
|
httpHeaderValue1: 'Token <token>'
|
||||||
|
```
|
||||||
|
|
||||||
|
**InfluxDB 3.x for SQL example:**
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
apiVersion: 1
|
||||||
|
|
||||||
|
datasources:
|
||||||
|
- name: InfluxDB_v3_InfluxQL
|
||||||
|
type: influxdb
|
||||||
|
access: proxy
|
||||||
|
url: http://localhost:8086
|
||||||
|
jsonData:
|
||||||
|
version: SQL
|
||||||
|
dbName: site
|
||||||
|
httpMode: POST
|
||||||
|
insecureGrpc: false
|
||||||
|
secureJsonData:
|
||||||
|
token: '<api-token>'
|
||||||
|
```
|
||||||
@ -2,14 +2,15 @@
|
|||||||
aliases:
|
aliases:
|
||||||
- ../../data-sources/influxdb/query-editor/
|
- ../../data-sources/influxdb/query-editor/
|
||||||
- influxdb-flux/
|
- influxdb-flux/
|
||||||
description: Guide for Flux in Grafana
|
description: This topic describes the InfluxDB query editor, modes and querying the InfluxDB data source.
|
||||||
labels:
|
labels:
|
||||||
products:
|
products:
|
||||||
- cloud
|
- cloud
|
||||||
- enterprise
|
- enterprise
|
||||||
- oss
|
- oss
|
||||||
title: Query Editor
|
title: InfluxDB query Editor
|
||||||
weight: 200
|
menuTitle: Query editor
|
||||||
|
weight: 400
|
||||||
refs:
|
refs:
|
||||||
explore:
|
explore:
|
||||||
- pattern: /docs/grafana/
|
- pattern: /docs/grafana/
|
||||||
@ -31,45 +32,80 @@ refs:
|
|||||||
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/logs/
|
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/logs/
|
||||||
- pattern: /docs/grafana-cloud/
|
- pattern: /docs/grafana-cloud/
|
||||||
destination: grafana-cloud/visualizations/panels-visualizations/visualizations/logs/
|
destination: grafana-cloud/visualizations/panels-visualizations/visualizations/logs/
|
||||||
|
query-editor:
|
||||||
|
- pattern: /docs/grafana/
|
||||||
|
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/query-transform-data/#query-editors
|
||||||
|
- pattern: /docs/grafana-cloud/
|
||||||
|
destination: /docs/grafana-cloud/visualizations/panels-visualizations/query-transform-data/#query-editors
|
||||||
|
build-dashboards:
|
||||||
|
- pattern: /docs/grafana/
|
||||||
|
destination: /docs/grafana/<GRAFANA_VERSION>/dashboards/build-dashboards/
|
||||||
|
- pattern: /docs/grafana-cloud/
|
||||||
|
destination: /docs/grafana-cloud/visualizations/dashboards/build-dashboards/
|
||||||
|
data-source-management:
|
||||||
|
- pattern: /docs/grafana/
|
||||||
|
destination: /docs/grafana/<GRAFANA_VERSION>/administration/data-source-management/
|
||||||
|
- pattern: /docs/grafana-cloud/
|
||||||
|
destination: /docs/grafana/<GRAFANA_VERSION>/administration/data-source-management/
|
||||||
|
annotations:
|
||||||
|
- pattern: /docs/grafana/
|
||||||
|
destination: /docs/grafana/<GRAFANA_VERSION>/dashboards/build-dashboards/annotate-visualizations/
|
||||||
|
- pattern: /docs/grafana-cloud/
|
||||||
|
destination: /docs/grafana-cloud/visualizations/dashboards/build-dashboards/annotate-visualizations/
|
||||||
|
configure-influxdb-data-source:
|
||||||
|
- pattern: /docs/grafana/
|
||||||
|
destination: /docs/grafana/<GRAFANA_VERSION>/datasources/influxdb/configure-influxdb-data-source/
|
||||||
|
- pattern: /docs/grafana-cloud/
|
||||||
|
destination: /docs/grafana/<GRAFANA_VERSION>/datasources/influxdb/configure-influxdb-data-source/
|
||||||
---
|
---
|
||||||
|
|
||||||
# InfluxDB query editor
|
# InfluxDB query editor
|
||||||
|
|
||||||
This topic explains querying specific to the InfluxDB data source.
|
Grafana's query editors are unique to each data source. For general information on Grafana query editors, refer to [Query editors](ref:query-editor). For general information on querying data sources in Grafana, refer to [Query and transform data](ref:query-transform-data).
|
||||||
For general documentation on querying data sources in Grafana, see [Query and transform data](ref:query-transform-data).
|
|
||||||
|
The InfluxDB query editor is located on the [Explore page](ref:explore). You can also access the InfluxDB query editor from a dashboard panel. Click the ellipsis in the upper right of the panel and select **Edit**.
|
||||||
|
|
||||||
|
You can also use the query editor to retrieve [log data](#query-logs) and [annotate](#apply-annotations) visualizations.
|
||||||
|
|
||||||
## Choose a query editing mode
|
## Choose a query editing mode
|
||||||
|
|
||||||
The InfluxDB data source's query editor has two modes depending on your choice of query language in
|
The InfluxDB data source has three different types of query editors, each corresponding to the query language selected in the [data source configuration](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/datasources/influxdb/configure-influxdb-data-source/#influxdb-configuration-options):
|
||||||
the [data source configuration]({{< relref "../#configure-the-data-source" >}}):
|
|
||||||
|
|
||||||
- [InfluxQL](#influxql-query-editor)
|
- [InfluxQL](#influxql-query-editor)
|
||||||
- [SQL](#sql-query-editor)
|
- [SQL](#sql-query-editor)
|
||||||
- [Flux](#flux-query-editor)
|
- [Flux](#flux-query-editor)
|
||||||
|
|
||||||
You also use the query editor to retrieve [log data](#query-logs) and [annotate](#apply-annotations) visualizations.
|
Editor options vary based on query language.
|
||||||
|
|
||||||
## InfluxQL query editor
|
## InfluxQL query editor
|
||||||
|
|
||||||
The InfluxQL query editor helps you select metrics and tags to create InfluxQL queries.
|
The InfluxQL query editor helps you select metrics and tags to create InfluxQL queries. There are two modes: `visual editor mode` and `raw query mode`. To switch between the two modes click the **pencil icon** in the upper right.
|
||||||
|
|
||||||
**To enter edit mode:**
|
Visual query editor mode contains the following components:
|
||||||
|
|
||||||
1. Hover over any part of the panel to display the actions menu on the top right corner.
|
- **FROM** - Select a measurement to query.
|
||||||
1. Click the menu and select **Edit**.
|
- **WHERE** - Select filters by clicking the **+ sign**.
|
||||||
|
- **SELECT** - Select fields and functions from the drop-down. You can add multiple fields and functions by clicking the **+ sign**.
|
||||||
|
- **GROUP BY** - Select a tag from the drop-down menu.
|
||||||
|
- **TIMEZONE** - _Optional_ Group data by a specific timezone.
|
||||||
|
- **ORDER BY TIME** - Sort data by time in either ascending or descending order.
|
||||||
|
- **LIMIT** - _Optional_ Limits the number of rows returned by the query.
|
||||||
|
- **SLIMIT** - _Optional_ Limits the number of series returned by the query. Refer to [SLIMIT clause](https://docs.influxdata.com/influxdb/cloud/query-data/influxql/explore-data/limit-and-slimit/#slimit-clause) for more information on this option.
|
||||||
|
- **FORMAT AS** - Select a format option from the drop-down menu.
|
||||||
|
- **ALIAS** - Add an alias. Refer to [Alias patterns](#alias-patterns) for more information.
|
||||||
|
|
||||||
|
### Raw query editor mode
|
||||||
|
|
||||||
|
You can write raw InfluxQL queries by switching to raw query mode. Click the pencil in the upper right of the query editor to switch modes. Note that when you switch to visual editor mode, you will lose any changes made in raw query mode.
|
||||||
|
|
||||||
|
If you use raw query mode, your query must include `WHERE $timeFilter`. You should also provide a group by time and an aggregation function. Otherwise, InfluxDB may return hundreds of thousands of data points, potentially causing your browser to hang.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
### Filter data (WHERE)
|
### Match by regular expressions
|
||||||
|
|
||||||
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.
|
You can enter regular expressions for metric names or tag filter values.
|
||||||
Wrap the regex pattern in forward slashes (`/`).
|
Wrap the regex pattern in forward slashes (`/`), as shown in this example: `/measurement/`.
|
||||||
|
|
||||||
Grafana automatically adjusts the filter tag condition to use the InfluxDB regex match condition operator (`=~`).
|
Grafana automatically adjusts the filter tag condition to use the InfluxDB regex match condition operator (`=~`).
|
||||||
|
|
||||||
@ -77,56 +113,35 @@ Grafana automatically adjusts the filter tag condition to use the InfluxDB regex
|
|||||||
|
|
||||||
In the `SELECT` row, you can specify which fields and functions to use.
|
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.
|
If you **group by time** you must use an aggregation function. Certain functions such as `derivative` also require an aggregation function.
|
||||||
Some functions like `derivative` also require an aggregation function.
|
|
||||||
|
|
||||||
The editor helps you build this part of the query.
|
If you have the following:
|
||||||
For example:
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
This query editor input generates an InfluxDB `SELECT` clause:
|
The query editor input generates an InfluxDB `SELECT` clause:
|
||||||
|
|
||||||
```sql
|
```sql
|
||||||
SELECT derivative(mean("value"), 10s) / 10 AS "REQ/s"
|
SELECT derivative(mean("value"), 10s) / 10 AS "REQ/s"
|
||||||
FROM....
|
FROM....
|
||||||
```
|
```
|
||||||
|
|
||||||
**To select multiple fields:**
|
You can also use a \* in a SELECT statement to select all fields.
|
||||||
|
|
||||||
1. Click the plus button.
|
```sql
|
||||||
1. Select **Field > field** to add another `SELECT` clause.
|
SELECT * FROM <measurement_name>
|
||||||
|
```
|
||||||
|
|
||||||
You can also `SELECT` an asterisk (`*`) to select all fields.
|
### GROUP BY results
|
||||||
|
|
||||||
### Group query results
|
To group results by a tag, specify the tag in the **GROUP BY** row:
|
||||||
|
|
||||||
To group results by a tag, define it in a "Group By".
|
1. Click the **+ sign** in the GROUP BY row.
|
||||||
|
1. Select a tag from the drop-down.
|
||||||
|
|
||||||
**To group by a tag:**
|
You can GROUP BY multiple options.
|
||||||
|
|
||||||
1. Click the plus icon at the end of the GROUP BY row.
|
To remove a GROUP BY option click the **X icon** next to the option.
|
||||||
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 patterns
|
||||||
|
|
||||||
@ -138,20 +153,21 @@ Otherwise, InfluxDB can easily return hundreds of thousands of data points that
|
|||||||
| `$col` | Column name. |
|
| `$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. |
|
| `$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.
|
You can also use the `[[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 example, entering the value `Host: [[tag_hostname]]` in the ALIAS BY field replaces it with the `hostname` tag value for each legend value.
|
||||||
for each legend value.
|
|
||||||
An example legend value would be `Host: server1`.
|
An example legend value is `Host: server1`.
|
||||||
|
|
||||||
## SQL query editor
|
## SQL query editor
|
||||||
|
|
||||||
Grafana support [SQL querying language](https://docs.influxdata.com/influxdb/cloud-serverless/query-data/sql/)
|
Grafana supports the [SQL query language](https://docs.influxdata.com/influxdb/cloud-serverless/query-data/sql/) in [InfluxDB v3.0](https://www.influxdata.com/blog/introducing-influxdb-3-0/) and higher.
|
||||||
with [InfluxDB v3.0](https://www.influxdata.com/blog/introducing-influxdb-3-0/) and higher.
|
|
||||||
|
You construct your SQL query directly in the query editor.
|
||||||
|
|
||||||
### Macros
|
### Macros
|
||||||
|
|
||||||
You can use macros within the query to replace them with the values from Grafana's context.
|
You can use macros in your query to automatically substitute them with values from Grafana's context.
|
||||||
|
|
||||||
| Macro example | Replaced with |
|
| Macro example | Replaced with |
|
||||||
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||||
@ -179,12 +195,12 @@ Examples:
|
|||||||
## Flux query editor
|
## Flux query editor
|
||||||
|
|
||||||
Grafana supports Flux when running InfluxDB v1.8 and higher.
|
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
|
If your data source is [configured for Flux](ref:configure-influxdb-data-source), you can use
|
||||||
the [Flux query and scripting language](https://www.influxdata.com/products/flux/) in the query editor, which serves as
|
the [Flux](https://docs.influxdata.com/flux/v0/) in the query editor, which serves as
|
||||||
a text editor for raw Flux queries with macro support.
|
a text editor for raw Flux queries with macro support.
|
||||||
|
|
||||||
For more information and connection details, refer
|
For more information and connection details, refer
|
||||||
to [1.8 compatibility](https://github.com/influxdata/influxdb-client-go/#influxdb-18-api-compatibility).
|
to [InfluxDB 1.8 API compatibility](https://github.com/influxdata/influxdb-client-go/#influxdb-18-api-compatibility).
|
||||||
|
|
||||||
### Use macros
|
### Use macros
|
||||||
|
|
||||||
@ -199,7 +215,7 @@ Macros support copying and pasting from [Chronograf](https://www.influxdata.com/
|
|||||||
| `v.defaultBucket` | The data source configuration's "Default Bucket" setting. |
|
| `v.defaultBucket` | The data source configuration's "Default Bucket" setting. |
|
||||||
| `v.organization` | The data source configuration's "Organization" setting. |
|
| `v.organization` | The data source configuration's "Organization" setting. |
|
||||||
|
|
||||||
For example, the query editor interpolates this query:
|
For example, consider the following Flux query:
|
||||||
|
|
||||||
```flux
|
```flux
|
||||||
from(bucket: v.defaultBucket)
|
from(bucket: v.defaultBucket)
|
||||||
@ -210,8 +226,7 @@ from(bucket: v.defaultBucket)
|
|||||||
|> yield(name: "mean")
|
|> yield(name: "mean")
|
||||||
```
|
```
|
||||||
|
|
||||||
Into this query to send to InfluxDB, with interval and time period values changing according to the active time
|
This Flux query is interpolated into the following query and sent to InfluxDB, with the interval and time period values changing according to the active time selection:
|
||||||
selection:
|
|
||||||
|
|
||||||
```flux
|
```flux
|
||||||
from(bucket: "grafana")
|
from(bucket: "grafana")
|
||||||
@ -222,33 +237,20 @@ from(bucket: "grafana")
|
|||||||
|> yield(name: "mean")
|
|> yield(name: "mean")
|
||||||
```
|
```
|
||||||
|
|
||||||
To view the interpolated version of a query with the query inspector, refer to [Panel Inspector](ref:panel-inspector).
|
To view the interpolated version of a query with the Query inspector, refer to [Panel Inspector](ref:panel-inspector).
|
||||||
|
|
||||||
## Query logs
|
## Query logs
|
||||||
|
|
||||||
You can query and display log data from InfluxDB in [Explore](ref:explore) and with the [Logs panel](ref:logs) for dashboards.
|
You can query and display log data from InfluxDB in [Explore](ref:explore) and in the dashboard [Logs panel](ref:logs).
|
||||||
|
|
||||||
Select the InfluxDB data source, then enter a query to display your logs.
|
Select an InfluxDB data source in the Query editor. Under the **Select measurement field** next to the **FROM** section, choose a measurement containing your log data, then choose the appropriate fields that will display the log message. Add any additional filters by clicking the **+ sign** next to the **WHERE** field. Add additional conditions in the GROUP BY, ORDER BY and the rest of the options.
|
||||||
|
|
||||||
### Create log queries
|
After InfluxDB returns the results, the log panel displays log rows along with a bar chart. The x-axis represents time, while the y-axis shows the frequency or count.
|
||||||
|
|
||||||
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
|
## Apply annotations
|
||||||
|
|
||||||
[Annotations][annotate-visualizations] overlay rich event information on top of graphs.
|
[Annotations](ref:annotations) overlay rich event information on top of graphs.
|
||||||
You can add annotation queries in the Dashboard menu's Annotations view.
|
You can add annotation queries in the dashboard menu's **Annotations view**.
|
||||||
|
|
||||||
For InfluxDB, your query **must** include `WHERE $timeFilter`.
|
For InfluxDB, your query **must** include `WHERE $timeFilter`.
|
||||||
|
|
||||||
|
|||||||
@ -17,7 +17,7 @@ labels:
|
|||||||
- oss
|
- oss
|
||||||
menuTitle: Template variables
|
menuTitle: Template variables
|
||||||
title: InfluxDB template variables
|
title: InfluxDB template variables
|
||||||
weight: 300
|
weight: 600
|
||||||
refs:
|
refs:
|
||||||
add-template-variables-chained-variables:
|
add-template-variables-chained-variables:
|
||||||
- pattern: /docs/grafana/
|
- pattern: /docs/grafana/
|
||||||
@ -39,57 +39,62 @@ refs:
|
|||||||
destination: /docs/grafana/<GRAFANA_VERSION>/dashboards/variables/add-template-variables/#add-ad-hoc-filters
|
destination: /docs/grafana/<GRAFANA_VERSION>/dashboards/variables/add-template-variables/#add-ad-hoc-filters
|
||||||
- pattern: /docs/grafana-cloud/
|
- pattern: /docs/grafana-cloud/
|
||||||
destination: /docs/grafana/<GRAFANA_VERSION>/dashboards/variables/add-template-variables/#add-ad-hoc-filters
|
destination: /docs/grafana/<GRAFANA_VERSION>/dashboards/variables/add-template-variables/#add-ad-hoc-filters
|
||||||
add-template-variables-adds-a-query-variable:
|
add-template-variables-add-a-query-variable:
|
||||||
- pattern: /docs/grafana/
|
- pattern: /docs/grafana/
|
||||||
destination: /docs/grafana/<GRAFANA_VERSION>/dashboards/variables/add-template-variables/#add-a-query-variable
|
destination: /docs/grafana/<GRAFANA_VERSION>/dashboards/variables/add-template-variables/#add-a-query-variable
|
||||||
- pattern: /docs/grafana-cloud/
|
- pattern: /docs/grafana-cloud/
|
||||||
destination: /docs/grafana/<GRAFANA_VERSION>/dashboards/variables/add-template-variables/#add-a-query-variable
|
destination: /docs/grafana/<GRAFANA_VERSION>/dashboards/variables/add-template-variables/#add-a-query-variable
|
||||||
|
variable-best-practices:
|
||||||
|
- pattern: /docs/grafana/
|
||||||
|
destination: /docs/grafana/<GRAFANA_VERSION>/dashboards/variables/#variable-best-practices
|
||||||
|
- pattern: /docs/grafana-cloud/
|
||||||
|
destination: /docs/grafana-cloud/visualizations/dashboards/variables/#variable-best-practices
|
||||||
---
|
---
|
||||||
|
|
||||||
# InfluxDB template variables
|
# InfluxDB template variables
|
||||||
|
|
||||||
Instead of hard-coding details such as server, application, and sensor names in metric queries, you can use variables.
|
Instead of hard-coding details such as server, application, and sensor names in metric queries, you can use variables. Grafana displays these variables in drop-down 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.
|
||||||
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](ref:variables) and [Add and manage variables](ref:add-template-variables) documentation.
|
For additional information using variables and templates, refer to the following documentation:
|
||||||
|
|
||||||
|
- [Variables](ref:variables)
|
||||||
|
- [Templates](ref:variables)
|
||||||
|
- [Add and manage variables](ref:add-template-variables)
|
||||||
|
- [Variable best practices](ref:variable-best-practices)
|
||||||
|
|
||||||
## Use query variables
|
## Use query variables
|
||||||
|
|
||||||
If you add a query template variable, you can write an InfluxDB exploration (metadata) query.
|
By adding a query template variable, you can write an InfluxDB metadata exploration query. These queries return results such as measurement names, key names, and key values.
|
||||||
These queries can return results like measurement names, key names, or key values.
|
|
||||||
|
|
||||||
For more information, refer to [Add query variable](ref:add-template-variables-adds-a-query-variable).
|
For more information, refer to [Add a query variable](ref: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**:
|
To create a variable containing all values for the `hostname` tag, use the following query format in the **Query** variable:
|
||||||
|
|
||||||
```sql
|
```sql
|
||||||
SHOW TAG VALUES WITH KEY = "hostname"
|
SHOW TAG VALUES WITH KEY = "hostname"
|
||||||
```
|
```
|
||||||
|
|
||||||
### Chain or nest variables
|
## Chain or nest variables
|
||||||
|
|
||||||
You can also create nested variables, sometimes called [chained variables](ref:add-template-variables-chained-variables).
|
You can also create nested variables, sometimes called [chained variables](ref: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:
|
For example, if you have a variable named `region`, you can configure the `hosts` variable to display only hosts from the selected region using the following query:
|
||||||
|
|
||||||
```sql
|
```sql
|
||||||
SHOW TAG VALUES WITH KEY = "hostname" WHERE region = '$region'
|
SHOW TAG VALUES WITH KEY = "hostname" WHERE region = '$region'
|
||||||
```
|
```
|
||||||
|
|
||||||
You can fetch key names for a given measurement:
|
You can also fetch key names for a given measurement:
|
||||||
|
|
||||||
```sql
|
```sql
|
||||||
SHOW TAG KEYS [FROM <measurement_name>]
|
SHOW TAG KEYS [FROM <measurement_name>]
|
||||||
```
|
```
|
||||||
|
|
||||||
If you have a variable with key names, you can use this variable in a group-by clause.
|
If you have a variable containing key names, you can use it in a **GROUP BY** clause. This allows you to adjust the grouping by selecting from the variable list at the top of the dashboard
|
||||||
This helps you change group-by using the variable list at the top of the dashboard.
|
|
||||||
|
|
||||||
### Use ad hoc filters
|
## Use ad hoc filters
|
||||||
|
|
||||||
InfluxDB supports the special **Ad hoc filters** variable type.
|
InfluxDB supports the **Ad hoc filters** variable type. This variable type allows you to define multiple key/value filters, which Grafana then automatically applies to all your InfluxDB queries.
|
||||||
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](ref:add-template-variables-add-ad-hoc-filters).
|
For more information, refer to [Add ad hoc filters](ref:add-template-variables-add-ad-hoc-filters).
|
||||||
|
|
||||||
@ -97,13 +102,13 @@ For more information, refer to [Add ad hoc filters](ref:add-template-variables-a
|
|||||||
|
|
||||||
The InfluxDB data source supports two variable syntaxes for use in the **Query** field:
|
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.
|
- `$<varname>` - This syntax is easy to read and write but does not allow you to use a variable in the middle of a word or expression.
|
||||||
|
|
||||||
```sql
|
```sql
|
||||||
SELECT mean("value") FROM "logins" WHERE "hostname" =~ /^$host$/ AND $timeFilter GROUP BY time($__interval), "hostname"
|
SELECT mean("value") FROM "logins" WHERE "hostname" =~ /^$host$/ AND $timeFilter GROUP BY time($__interval), "hostname"
|
||||||
```
|
```
|
||||||
|
|
||||||
- `${varname}`
|
- `${varname}` - Use this syntax when you want to interpolate a variable in the middle of an expression.
|
||||||
|
|
||||||
```sql
|
```sql
|
||||||
SELECT mean("value") FROM "logins" WHERE "hostname" =~ /^[[host]]$/ AND $timeFilter GROUP BY time($__interval), "hostname"
|
SELECT mean("value") FROM "logins" WHERE "hostname" =~ /^[[host]]$/ AND $timeFilter GROUP BY time($__interval), "hostname"
|
||||||
@ -113,4 +118,4 @@ When you enable the **Multi-value** or **Include all value** options, Grafana co
|
|||||||
|
|
||||||
### Templated dashboard example
|
### Templated dashboard example
|
||||||
|
|
||||||
To view an example templated dashboard, refer to this [InfluxDB templated dashboard](https://play.grafana.org/d/f62a0410-5abb-4dd8-9dfc-caddfc3e2ffd/eccb2445-b0a2-5e83-8e0f-6d5ea53ad575).
|
To view an example of a templated dashboard, refer to this [InfluxDB example dashboard](https://play.grafana.org/d/f62a0410-5abb-4dd8-9dfc-caddfc3e2ffd/eccb2445-b0a2-5e83-8e0f-6d5ea53ad575).
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user