mirror of https://github.com/grafana/grafana
Docs: InfluxDB doc improvements (#32815)
* Create getting-started-influxdb.md * Update getting-started-prometheus.md * Update getting-started-sql.md * data source edits * single source intro * Create first-step.md * Update influxdb.md * Update getting-started-influxdb.md * Update influxdb.md * break up long file * Update influxdb-templates.md * more updates * Update _index.md * Update _index.md * Update getting-started-sql.md * Update _index.md * edits * Update docs/sources/datasources/influxdb/_index.md Co-authored-by: Ursula Kallio <73951760+osg-grafana@users.noreply.github.com> * Delete influxdb.md * Update getting-started-influxdb.md * Update influx-flux.md * Update _index.md * Update getting-started-influxdb.md * Update getting-started-influxdb.md * content * content changes * Update _index.md * link fixes * Update getting-started-influxdb.md * Update getting-started-influxdb.md * Merge branch 'master' into docs-influxdb * updated port Co-authored-by: Ursula Kallio <73951760+osg-grafana@users.noreply.github.com>pull/33173/head^2
Diana Payton
4 years ago
committed by
GitHub
parent
6bbcd43b4c
commit
c986aaa0a8
@ -1,328 +0,0 @@ |
||||
+++ |
||||
title = "InfluxDB" |
||||
description = "Guide for using InfluxDB in Grafana" |
||||
keywords = ["grafana", "influxdb", "guide", "flux"] |
||||
aliases = ["/docs/grafana/latest/features/datasources/influxdb"] |
||||
weight = 700 |
||||
+++ |
||||
|
||||
# Using InfluxDB in Grafana |
||||
|
||||
Grafana ships with a feature-rich data source plugin for InfluxDB. The plugin includes a custom query editor and supports annotations and query templates. |
||||
|
||||
## Add the data source |
||||
|
||||
1. Open the side menu by clicking the Grafana icon in the top header. |
||||
1. In the side menu under the `Dashboards` link you should find a link named `Data Sources`. |
||||
1. Click the `+ Add data source` button in the top header. |
||||
1. Select *InfluxDB* from the *Type* dropdown. |
||||
1. Select *InfluxQL* or *Flux* from the `Query Language` list. |
||||
|
||||
> **Note:** If you're not seeing the `Data Sources` link in your side menu it means that your current user does not have the `Admin` role for the current organization. |
||||
|
||||
|
||||
### InfluxQL (classic InfluxDB query) |
||||
|
||||
Name | Description |
||||
----------- | ------------- |
||||
`Name` | The data source name. This is how you refer to the data source in panels and queries. |
||||
`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` | Server (default) = URL needs to be accessible from the Grafana backend/server, Browser = URL needs to be accessible from the browser. |
||||
`Database` | Name of your InfluxDB database |
||||
`User` | Name of your database user |
||||
`Password` | Database user's password |
||||
`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` | Refer to [Min time interval]({{< relref "#min-time-interval" >}}). |
||||
`Max series`| 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. |
||||
|
||||
Access mode controls how requests to the data source will be handled. Server should be the preferred way if nothing else stated. |
||||
|
||||
### Server access mode (Default) |
||||
|
||||
All requests will be made from the browser to Grafana backend/server which in turn will forward the requests to the data source and by that circumvent possible Cross-Origin Resource Sharing (CORS) requirements. The URL needs to be accessible from the grafana backend/server if you select this access mode. |
||||
|
||||
### Browser access mode |
||||
|
||||
All requests will be made from the browser directly to the data source and may be subject to Cross-Origin Resource Sharing (CORS) requirements. The URL needs to be accessible from the browser if you select this access mode. |
||||
|
||||
### 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 |
||||
|
||||
## Query Editor |
||||
|
||||
{{< docs-imagebox img="/img/docs/v45/influxdb_query_still.png" class="docs-image--no-shadow" animated-gif="/img/docs/v45/influxdb_query.gif" >}} |
||||
|
||||
You can access the InfluxDB editor under the metrics tab when you are in the edit mode of the Graph or Singlestat panels. |
||||
Enter edit mode by clicking the panel title and clicking **Edit**. The editor allows you to select metrics and tags. |
||||
|
||||
### Filter data (WHERE) |
||||
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--`. |
||||
|
||||
**Regex matching** |
||||
|
||||
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 (`=~`). |
||||
|
||||
### Field and Aggregation functions |
||||
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: |
||||
|
||||
 |
||||
|
||||
The above generates the following InfluxDB `SELECT` clause: |
||||
|
||||
```sql |
||||
SELECT derivative(mean("value"), 10s) /10 AS "REQ/s" FROM .... |
||||
``` |
||||
|
||||
#### Select multiple fields |
||||
Use the plus button and select Field > field to add another SELECT clause. You can also |
||||
specify an asterix `*` to select all fields. |
||||
|
||||
### 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 please 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 |
||||
- $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`. |
||||
|
||||
### Table query / raw data |
||||
|
||||
 |
||||
|
||||
You can remove the group by time by clicking on the `time` part and then the `x` icon. You can |
||||
change the option `Format As` to `Table` if you want to show raw data in the `Table` panel. |
||||
|
||||
## Flux support |
||||
|
||||
> Starting in v7.1, Grafana can execute Flux queries. |
||||
|
||||
The client 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 |
||||
---------------- | ------------- |
||||
`URL` | The HTTP protocol, IP address and port of your InfluxDB API (InfluxDB 2.0 API port is by default 9999) |
||||
`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` | 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` | Refer to [Min time interval]({{< relref "#min-time-interval" >}}). |
||||
`Max series`| 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 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 [Chronograph](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. |
||||
|
||||
## Querying Logs (BETA) |
||||
|
||||
> Only available in Grafana v6.3+. |
||||
|
||||
Querying and displaying log data from InfluxDB is available in [Explore]({{< relref "../explore" >}}), and in the [logs panel]({{< relref "../panels/visualizations/logs-panel.md" >}}) 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--`. |
||||
|
||||
## Templating |
||||
|
||||
Instead of hard-coding things like server, application and sensor name in your metric queries you can use variables in their place. |
||||
Variables are shown as dropdown select boxes at the top of the dashboard. These dropdowns make it easy to change the data |
||||
being displayed in your dashboard. |
||||
|
||||
Check out the [Templating]({{< relref "../variables/_index.md" >}}) documentation for an introduction to the templating feature and the different |
||||
types of template variables. |
||||
|
||||
### Query variable |
||||
|
||||
If you add a template variable of the type `Query`, then you can write an InfluxDB exploration (metadata) query. These queries can |
||||
return things like measurement names, key names or key values. |
||||
|
||||
For example, you can have a variable that contains all values for tag `hostname` if you specify a query like this in the template variable *Query* setting. |
||||
|
||||
```sql |
||||
SHOW TAG VALUES WITH KEY = "hostname" |
||||
``` |
||||
|
||||
You can also create nested 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 dropdown at the top |
||||
of the dashboard. |
||||
|
||||
### Using variables in 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) |
||||
|
||||
### 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 will automatically |
||||
be applied to all your InfluxDB queries. |
||||
|
||||
## Annotations |
||||
|
||||
[Annotations]({{< relref "../dashboards/annotations.md" >}}) 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 |
||||
``` |
||||
|
||||
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. |
||||
|
||||
## Configure the data source with provisioning |
||||
|
||||
You can now 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 |
||||
password: grafana |
||||
url: http://localhost:8086 |
||||
jsonData: |
||||
httpMode: GET |
||||
``` |
||||
|
||||
### 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>' |
||||
|
||||
``` |
||||
@ -0,0 +1,149 @@ |
||||
+++ |
||||
title = "InfluxDB data source" |
||||
description = "Guide for using InfluxDB in Grafana" |
||||
keywords = ["grafana", "influxdb", "guide", "flux"] |
||||
aliases = ["/docs/grafana/latest/features/datasources/influxdb", "/docs/grafana/latest/datasources/influxdb"] |
||||
weight = 700 |
||||
+++ |
||||
|
||||
# InfluxDB data source |
||||
|
||||
{{< 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.md" >}}) for instructions on how to add a data source to Grafana. Only users with the organization admin role can add data sources. |
||||
|
||||
## Data source options |
||||
|
||||
To access data source settings, hover your mouse over the **Configuration** (gear) icon, then click **Data sources**, and then click the data source. |
||||
|
||||
InfluxDB data source options differ depending on which [query language](#query-languages) you select: InfluxQL or Flux. |
||||
|
||||
> **Note:** Though not required, it's a good practice to append the language choice to the data source name. For example: |
||||
> |
||||
- InfluxDB-InfluxQL |
||||
- InfluxDB-Flux |
||||
|
||||
### InfluxQL (classic InfluxDB query) |
||||
|
||||
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.md" >}}). |
||||
|
||||
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` | Server (default) = URL needs to be accessible from the Grafana backend/server, Browser = URL needs to be accessible from the browser. |
||||
`Whitelisted 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. |
||||
|
||||
### Flux |
||||
|
||||
For information on data source settings and using Flux in Grafana, refer to [Flux support in Grafana]({{< relref "influxdb-flux.md" >}}). |
||||
|
||||
#### 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: |
||||
|
||||
Identifier | Description |
||||
------------ | ------------- |
||||
`y` | year |
||||
`M` | month |
||||
`w` | week |
||||
`d` | day |
||||
`h` | hour |
||||
`m` | minute |
||||
`s` | second |
||||
`ms` | millisecond |
||||
|
||||
## Query languages |
||||
|
||||
You can query InfluxDB using InfluxQL or Flux: |
||||
|
||||
- [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. |
||||
|
||||
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/). |
||||
|
||||
## InfluxQL query editor |
||||
|
||||
Enter edit mode by clicking the panel title and clicking **Edit**. The editor allows you to select metrics and tags. |
||||
|
||||
 |
||||
|
||||
### Filter data (WHERE) |
||||
|
||||
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--`. |
||||
|
||||
**Regex matching** |
||||
|
||||
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 (`=~`). |
||||
|
||||
### Field and Aggregation functions |
||||
|
||||
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: |
||||
|
||||
 |
||||
|
||||
The above generates the following InfluxDB `SELECT` clause: |
||||
|
||||
```sql |
||||
SELECT derivative(mean("value"), 10s) /10 AS "REQ/s" FROM .... |
||||
``` |
||||
|
||||
#### Select multiple fields |
||||
|
||||
Use the plus button and select Field > field to add another SELECT clause. You can also |
||||
specify an asterix `*` to select all fields. |
||||
|
||||
### 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 |
||||
- $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/_index.md" >}}), and in the [logs panel]({{< relref "../../panels/visualizations/logs-panel.md" >}}) 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/annotations.md" >}}) 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 |
||||
``` |
||||
|
||||
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. |
||||
@ -0,0 +1,77 @@ |
||||
+++ |
||||
title = "Flux support in Grafana" |
||||
description = "Guide for Flux 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 [Chronograph](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 [Inspect a panel]({{< relref "../../panels/inspect-panel.md" >}}) and [Queries]({{< relref "../../panels/queries.md" >}}). |
||||
@ -0,0 +1,65 @@ |
||||
+++ |
||||
title = "InfluxDB templates" |
||||
description = "Guide for templates in InfluxDB" |
||||
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 "../../variables/_index.md" >}}). |
||||
|
||||
## 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 "../../variables/variable-types/add-query-variable.md" >}}). |
||||
|
||||
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 "../../variables/variable-types/chained-variables.md" >}}). |
||||
|
||||
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 "../../variables/variable-types/add-ad-hoc-filters.md" >}}). |
||||
@ -0,0 +1,67 @@ |
||||
+++ |
||||
title = "Provision InfluxDB" |
||||
description = "Guide for provisioning 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 |
||||
password: grafana |
||||
url: http://localhost:8086 |
||||
jsonData: |
||||
httpMode: GET |
||||
``` |
||||
|
||||
## 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>' |
||||
|
||||
``` |
||||
@ -0,0 +1,110 @@ |
||||
+++ |
||||
title = "With Grafana and InfluxDB" |
||||
description = "Guide for getting started with Grafana and InfluxDB" |
||||
keywords = ["grafana", "intro", "guide", "started"] |
||||
weight = 250 |
||||
+++ |
||||
|
||||
# Getting started with Grafana and InfluxDB |
||||
|
||||
{{< docs/shared "influxdb/intro.md" >}} |
||||
|
||||
{{< docs/shared "getting-started/first-step.md" >}} |
||||
|
||||
## Step 2. Get InfluxDB |
||||
|
||||
You can [download InfluxDB](https://portal.influxdata.com/downloads/) and install it locally or you can sign up for [InfluxDB Cloud](https://www.influxdata.com/products/influxdb-cloud/). |
||||
|
||||
> **Note:** Windows installers are not available for some versions of InfluxDB. |
||||
|
||||
## Step 3. Install other InfluxDB software |
||||
|
||||
[Install Telegraf](https://docs.influxdata.com/telegraf/v1.18/introduction/installation/). This tool is an agent that helps you get metrics into InfluxDB. For more information, refer to [Telegraf documentation](https://docs.influxdata.com/telegraf/v1.18/). |
||||
|
||||
If you chose to use InfluxDB Cloud, then you should [download and install the InfluxDB Cloud CLI](https://portal.influxdata.com/downloads/). This tool allows you to send command line instructions to your cloud account. For more information, refer to [Influx CLI documentation](https://docs.influxdata.com/influxdb/cloud/write-data/developer-tools/influx-cli/). |
||||
|
||||
## Step 4. Get data into InfluxDB |
||||
|
||||
If you downloaded and installed InfluxDB on your local machine, then use the [Quick Start][https://docs.influxdata.com/influxdb/v2.0/write-data/#quick-start-for-influxdb-oss] feature to visualize InfluxDB metrics. |
||||
|
||||
If you are using the cloud account, then the wizards will guide you through the initial process. For more information, refer to [Configure Telegraf](https://docs.influxdata.com/influxdb/cloud/write-data/no-code/use-telegraf/#configure-telegraf). |
||||
|
||||
> **Note:** Windows users might need to make additional adjustments. Look for special instructions in the InfluxData documentation and [Using Telegraf on Windows](https://www.influxdata.com/blog/using-telegraf-on-windows/) blog post. |
||||
|
||||
> **Note:** The regular system monitoring template in InfluxDB Cloud is not compatible with Windows. Windows users who use InfluxDB Cloud to monitor their system will need to use the [Windows System Monitoring Template](https://github.com/influxdata/community-templates/tree/master/windows_system). |
||||
|
||||
## Step 4. Add your InfluxDB data source to Grafana |
||||
|
||||
You can have more than one InfluxDB data source defined in Grafana. |
||||
|
||||
1. Follow the general instructions to [add a data source]({{< relref "../datasources/add-a-data-source.md" >}}). |
||||
1. Decide if you will use InfluxQL or Flux as your query language. |
||||
- For InfluxQL, refer to [InfluxDB data source]({{< relref "../datasources/influxdb/_index.md" >}}) for information about specific data source fields. |
||||
- For Flux, refer to [Flux query language in Grafana]({{< relref "../datasources/influxdb/influxdb-flux.md" >}}) for information about specific data source fields. |
||||
|
||||
### InfluxDB guides |
||||
|
||||
InfluxDB publishes guidance for connecting different versions of their product to Grafana. |
||||
|
||||
- **InfluxDB OSS or Enterprise 1.8+.** To turn on Flux, refer to [Configure InfluxDB](https://docs.influxdata.com/influxdb/v1.8/administration/config/#flux-enabled-false.). Select your InfluxDB version in the upper right corner. |
||||
- **InfluxDB OSS or Enterprise 2.x.** Refer to [Use Grafana with InfluxDB](https://docs.influxdata.com/influxdb/v2.0/tools/grafana/). Select your InfluxDB version in the upper right corner. |
||||
- **InfluxDB Cloud.** Refer to [Use Grafana with InfluxDB Cloud](https://docs.influxdata.com/influxdb/cloud/tools/grafana/). |
||||
|
||||
### Important tips |
||||
|
||||
- Make sure your Grafana token has read access. If it doesn't, then you'll get an authentication error and be unable to connect Grafana to InfluxDB. |
||||
- Avoid apostrophes and other non-standard characters in bucket and token names. |
||||
- If the text name of the organization or bucket doesn't work, then try the ID number. |
||||
- If you change your bucket name in InfluxDB, then you must also change it in Grafana and your Telegraf .conf file as well. |
||||
|
||||
## Step 5. Add a query |
||||
|
||||
This step varies depending on the query language that you selected when you set up your data source in Grafana. |
||||
|
||||
### InfluxQL query language |
||||
|
||||
In the query editor, click **select measurement**. |
||||
|
||||
 |
||||
|
||||
Grafana displays a list of possible series. Click one to select it, and Grafana graphs any available data. If there is no data to display, then try another selection or check your data source. |
||||
|
||||
### Flux query language |
||||
|
||||
Create a simple Flux query. |
||||
|
||||
1. [Add a panel](../panels/add-a-panel.md). |
||||
1. In the query editor, select your InfluxDB-Flux data source. For more information, refer to [Queries](../panels/queries.md). |
||||
1. Select the **Table** visualization. |
||||
1. In the query editor text field, enter `buckets()` and then click outside of the query editor. |
||||
|
||||
This generic query returns a list of buckets. |
||||
|
||||
 |
||||
|
||||
You can also create Flux queries in the InfluxDB Explore view. |
||||
|
||||
1. In your browser, log in to the InfluxDB native UI (OSS is typically something like http://localhost:8086 or for InfluxDB Cloud use: https://cloud2.influxdata.com). |
||||
1. Click **Explore** to open the Data Explorer. |
||||
1. The InfluxDB Data Explorer provides two mechanisms for creating Flux queries: a graphical query editor and a script editor. Using the graphical query editor, [create a query](https://docs.influxdata.com/influxdb/cloud/query-data/execute-queries/data-explorer/). It will look something like this: |
||||
|
||||
 |
||||
|
||||
1. Click **Script Editor** to view the text of the query, and then copy all the lines of your Flux code, which will look something like this: |
||||
|
||||
 |
||||
|
||||
1. In Grafana, [add a panel](../panels/add-a-panel.md) and then paste your Flux code into the query editor. |
||||
1. Click **Apply**. Your new panel should be visible with data from your Flux query. |
||||
|
||||
## Step 6. Check InfluxDB metrics in Grafana Explore |
||||
|
||||
In your Grafana instance, go to the [Explore]({{< relref "../explore/_index.md" >}}) view and build queries to experiment with the metrics you want to monitor. Here you can also debug issues related to collecting metrics. |
||||
|
||||
## Step 7. Start building dashboards |
||||
|
||||
There you go! Use Explore and Data Explorer to experiment with your data, and add the queries that you like to your dashboard as panels. Have fun! |
||||
|
||||
Here are some resources to learn more: |
||||
- Grafana documentation: [InfluxDB data source](../datasources/influxdb/_index.md) |
||||
- InfluxDB documentation: [Comparison of Flux vs InfluxQL](https://docs.influxdata.com/influxdb/v1.8/flux/flux-vs-influxql/) |
||||
@ -0,0 +1,5 @@ |
||||
--- |
||||
title: Intro paragraph |
||||
--- |
||||
|
||||
[InfluxDB](https://www.influxdata.com/products/) is an open-source time series database (TSDB) developed by [InfluxData](https://www.influxdata.com/). It is optimized for fast, high-availability storage and retrieval of time series data in fields such as operations monitoring, application metrics, IoT sensor data, and real-time analytics. |
||||
Loading…
Reference in new issue