Influxdata
/
docs-v2
mirror of https://github.com/influxdata/docs-v2.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
docs-v2/content/shared/v3-process-data/visualize/grafana.md

17 KiB
Raw Permalink Blame History

Use Grafana or Grafana Cloud to query and visualize data from {{% product-name %}}.

[!Note] {{< influxdb-version-detector >}}

[Grafana] enables you to query, visualize, alert on, and explore your metrics, logs, and traces wherever they are stored. [Grafana] provides you with tools to turn your time-series database (TSDB) data into insightful graphs and visualizations.

{{% cite %}}-- Grafana documentation{{% /cite %}}

Install Grafana or log in to Grafana Cloud

  1. Sign up for Grafana Cloud or follow the Grafana installation instructions to install Grafana for your operating system.

  2. If running Grafana locally, enable the newInfluxDSConfigPageDesign feature flag to use the latest InfluxDB data source plugin.

    {{< expand-wrapper >}} {{% expand "Option 1: Configuration file (recommended)" %}}

    Add the following to your grafana.ini configuration file:

    [feature_toggles]
enable = newInfluxDSConfigPageDesign

    Configuration file locations:

    • Linux: /etc/grafana/grafana.ini
    • macOS (Homebrew): /opt/homebrew/etc/grafana/grafana.ini
    • Windows: <GRAFANA_INSTALL_DIR>\conf\grafana.ini

    {{% /expand %}}

    {{% expand "Option 2: Command line" %}}

    Enable the feature flag when starting Grafana:

    {{< code-tabs-wrapper >}} {{% code-tabs %}} Linux macOS (Homebrew) Windows {{% /code-tabs %}} {{% code-tab-content %}}

    grafana-server --config /etc/grafana/grafana.ini \
  cfg:default.feature_toggles.enable=newInfluxDSConfigPageDesign

    {{% /code-tab-content %}} {{% code-tab-content %}}

    /opt/homebrew/opt/grafana/bin/grafana server \
  --config /opt/homebrew/etc/grafana/grafana.ini \
  --homepath /opt/homebrew/opt/grafana/share/grafana \
  --packaging=brew \
  cfg:default.paths.logs=/opt/homebrew/var/log/grafana \
  cfg:default.paths.data=/opt/homebrew/var/lib/grafana \
  cfg:default.paths.plugins=/opt/homebrew/var/lib/grafana/plugins \
  cfg:default.feature_toggles.enable=newInfluxDSConfigPageDesign

    {{% /code-tab-content %}} {{% code-tab-content %}}

    grafana-server.exe --config <GRAFANA_INSTALL_DIR>\conf\grafana.ini `
  cfg:default.feature_toggles.enable=newInfluxDSConfigPageDesign

    {{% /code-tab-content %}} {{< /code-tabs-wrapper >}}

    {{% /expand %}} {{< /expand-wrapper >}}

    For more information, see Configure feature toggles in the Grafana documentation.

  3. Visit your Grafana Cloud user interface (UI) or, if running Grafana locally, start Grafana and visit http://localhost:3000 in your browser.

{{% show-in "core,enterprise,clustered" %}}

[!Note]

Using Grafana Cloud with a local InfluxDB instance

If you need to keep your database local, consider running Grafana locally instead of using Grafana Cloud, as this avoids the need to expose your database to the internet.

To use InfluxDB running on your private network with Grafana Cloud, you must configure a private data source for Grafana Cloud. {{% /show-in %}}

InfluxDB data source

The InfluxDB data source plugin is included in the Grafana core distribution. Use the plugin to query and visualize data from {{< product-name >}} with both SQL and InfluxQL.

[!Note]

Grafana 12.2+

The instructions below are for Grafana 12.2+ with the newInfluxDSConfigPageDesign feature flag enabled. This introduces the newest version of the InfluxDB core plugin. The updated plugin includes SQL support for InfluxDB 3-based products such as {{< product-name >}}, and the interface dynamically adapts based on your product and query language selection in URL and authentication.

Before you begin

Prerequisites:

  • Grafana 12.2 or later
  • Administrator role in Grafana
  • {{% show-in "cloud-serverless" %}}An API token with read access to the bucket{{% /show-in %}}{{% show-in "cloud-dedicated,clustered" %}}A database token with read access to the database{{% /show-in %}}{{% show-in "core,enterprise" %}}Your {{% token-link "admin" "database" %}} with read access to the database{{% /show-in %}}

Quick reference: {{< product-name >}} configuration

Configuration Value
Product selection {{% hide-in "core,enterprise" %}}{{% product-name %}}{{% /hide-in %}}{{% show-in "core" %}}InfluxDB Enterprise 3.x (currently, no Core menu option){{% /show-in %}}{{% show-in "enterprise" %}}InfluxDB Enterprise 3.x{{% /show-in %}}
URL {{% show-in "cloud-dedicated,clustered" %}} Cluster URL{{% /show-in %}}{{% show-in "cloud-serverless" %}} Region URL--for example, https://us-west-2-1.aws.cloud2.influxdata.com{{% /show-in %}}{{% show-in "core,enterprise" %}}Server URL{{% /show-in %}}{{% hide-in "cloud-serverless" %}}--for example, https://{{< influxdb/host >}}{{% /hide-in %}}
Query languages SQL (requires HTTP/2), InfluxQL
Authentication {{% show-in "cloud-serverless" %}}Required (API token){{% /show-in %}}{{% show-in "core" %}}Admin token (if authentication is enabled){{% /show-in %}}{{% show-in "enterprise" %}}Admin or database token (if authentication is enabled){{% /show-in %}}{{% show-in "cloud-dedicated,clustered" %}}Required (database token){{% /show-in %}}
Database/Bucket {{% show-in "cloud-serverless" %}}Bucket name{{% /show-in %}}{{% hide-in "cloud-serverless" %}}Database name{{% /hide-in %}}

Create an InfluxDB data source

  1. In your Grafana interface, click Connections in the left sidebar.
  2. Click Data sources.
  3. Click Add new data source.
  4. Search for and select InfluxDB. The InfluxDB data source configuration page displays.
  5. In the Settings tab, enter a Name for your data source.

Configure URL and authentication

In the URL and authentication section, configure the following:

  • URL: Your {{% product-name %}}{{% show-in "cloud-dedicated,clustered" %}} cluster URL{{% /show-in %}}{{% show-in "cloud-serverless" %}} region URL--for example, https://us-west-2-1.aws.cloud2.influxdata.com{{% /show-in %}}{{% show-in "core,enterprise" %}} server URL{{% /show-in %}}{{% hide-in "cloud-serverless" %}}--for example, https://{{< influxdb/host >}}{{% /hide-in %}}
  • Product: From the dropdown, select {{% hide-in "core,enterprise" %}}{{% product-name %}}{{% /hide-in %}}{{% show-in "core" %}}InfluxDB Enterprise 3.x (currently, no Core menu option){{% /show-in %}}{{% show-in "core,enterprise" %}}InfluxDB Enterprise 3.x{{% /show-in %}}
  • Query Language: Select SQL or InfluxQL
  • (Optional) Advanced HTTP Settings, Auth, and TLS/SSL Settings as needed for your environment

Configure database settings

The fields in this section change based on your query language selection in URL and authentication.

{{< tabs-wrapper >}} {{% tabs %}} SQL InfluxQL {{% /tabs %}} {{% tab-content %}}

SQL configuration

When you select SQL as the query language, configure the following fields:

  • Database: {{% show-in "cloud-serverless" %}}Your bucket name. In {{< product-name >}}, buckets function as databases.{{% /show-in %}}{{% hide-in "cloud-serverless" %}}Your database name.{{% /hide-in %}}

  • Token: {{% show-in "cloud-serverless" %}}An API token with read access to the bucket{{% /show-in %}}{{% show-in "cloud-dedicated,clustered" %}}A database token with read access to the database{{% /show-in %}}{{% show-in "core,enterprise" %}}Your {{% token-link "admin" "database" %}} with read access to the database{{% /show-in %}}

{{% show-in "cloud-serverless" %}}{{< img-hd src="/img/grafana/influxdb3-cloud-serverless-grafana-sql.png" alt="SQL configuration for {{% product-name %}}" />}}{{% /show-in %}} {{% show-in "cloud-dedicated" %}}{{< img-hd src="/img/grafana/influxdb3-cloud-dedicated-grafana-sql.png" alt="SQL configuration for {{% product-name %}}" />}}{{% /show-in %}} {{% show-in "clustered" %}}{{< img-hd src="/img/grafana/influxdb3-clustered-grafana-sql.png" alt="SQL configuration for {{% product-name %}}" />}}{{% /show-in %}} {{% show-in "core" %}}{{< img-hd src="/img/grafana/influxdb3-core-grafana-sql.png" alt="SQL configuration for {{% product-name %}}" />}}{{% /show-in %}} {{% show-in "enterprise" %}}{{< img-hd src="/img/grafana/influxdb3-enterprise-grafana-sql.png" alt="SQL configuration for {{% product-name %}}" />}}{{% /show-in %}}

{{% show-in "core,enterprise,clustered" %}}

Use SQL without TLS/SSL

If using SQL to query {{% product-name %}} without TLS/SSL, enable the Insecure Connection option in your InfluxDB datasource configuration:

  1. Under Database settings, enable Advanced Database Settings.
  2. Enable Insecure Connection.

{{% img-hd src="/img/grafana/grafana-sql-insecure-connection.png" alt="Query InfluxDB using SQL without TLS/SSL" /%}} {{% /show-in %}}

[!Important]

Grafana queries through a proxy require HTTP/2

For SQL queries, Grafana uses the Flight SQL protocol (gRPC) to query {{% product-name %}}, which requires HTTP/2. If you query {{% product-name %}} through a proxy (such as HAProxy, nginx, or a load balancer), verify that your proxy is configured to support HTTP/2. Without HTTP/2 support, SQL queries through Grafana will fail to connect.

InfluxQL queries use HTTP/1.1 and are not affected by this requirement.

Click Save & test. Grafana attempts to connect to {{% product-name %}} and returns the result of the test.

{{% /tab-content %}} {{% tab-content %}}

InfluxQL configuration

{{% show-in "cloud-serverless" %}}

[!Important]

DBRP mapping required

To query {{% product-name %}} with InfluxQL, you must first map database and retention policy (DBRP) combinations to your InfluxDB Cloud buckets. The configuration form displays a warning if DBRP mapping is not configured.

For more information, see Map databases and retention policies to buckets. {{% /show-in %}}

When you select InfluxQL as the query language, configure the following fields:

  • Database: {{% show-in "cloud-serverless" %}}The database name mapped to your InfluxDB bucket.{{% /show-in %}}{{% hide-in "cloud-serverless" %}}Your database name.{{% /hide-in %}}

  • User: A username (can be any non-empty value).

  • Password: {{% show-in "cloud-serverless" %}}Your API token with read access to the bucket.{{% /show-in %}}{{% hide-in "cloud-serverless" %}}Your database token with read access to the database.{{% /hide-in %}}

  • HTTP Method: Select POST (recommended) or GET

{{% show-in "cloud-serverless" %}}{{< img-hd src="/img/grafana/influxdb3-cloud-serverless-grafana-influxql.png" alt="InfluxQL configuration for {{% product-name %}} with DBRP warning" />}}{{% /show-in %}} {{% show-in "cloud-dedicated" %}}{{< img-hd src="/img/grafana/influxdb3-cloud-dedicated-grafana-influxql.png" alt="InfluxQL configuration for {{% product-name %}} with DBRP warning" />}}{{% /show-in %}} {{% show-in "clustered" %}}{{< img-hd src="/img/grafana/influxdb3-clustered-grafana-influxql.png" alt="InfluxQL configuration for {{% product-name %}} with DBRP warning" />}}{{% /show-in %}} {{% show-in "core" %}}{{< img-hd src="/img/grafana/influxdb3-core-grafana-influxql.png" alt="InfluxQL configuration for {{% product-name %}}" />}}{{% /show-in %}} {{% show-in "enterprise" %}}{{< img-hd src="/img/grafana/influxdb3-enterprise-grafana-influxql.png" alt="InfluxQL configuration for {{% product-name %}} with DBRP warning" />}}{{% /show-in %}}

Click Save & test. Grafana attempts to connect to {{% product-name %}} and returns the result of the test.

{{% /tab-content %}} {{< /tabs-wrapper >}}

Query and visualize data

With your InfluxDB connection configured, use Grafana to query and visualize time series data.

Query InfluxDB with Grafana

After you configure and save an InfluxDB datasource, use Grafana to build, run, and inspect queries against {{% show-in "cloud-serverless" %}}your InfluxDB bucket{{% /show-in %}}{{% hide-in "cloud-serverless" %}}{{% product-name %}}{{% /hide-in %}}.

{{< tabs-wrapper >}} {{% tabs %}} SQL InfluxQL {{% /tabs %}} {{% tab-content %}}

[!Note] {{% sql/sql-schema-intro %}} To learn more, see Query Data.

  1. Click Explore.

  2. In the dropdown, select the saved InfluxDB data source to query.

  3. Use the SQL query form to build your query:

    • Table: Select the table (measurement) to query.

    • Column: Select one or more fields and tags to return as columns in query results.

      With SQL, select the time column to include timestamps with the data. Grafana relies on the time column to correctly graph time series data.

    • Optional: Toggle filter to generate WHERE clause statements.

      • WHERE: Configure condition expressions to include in the WHERE clause.

    • Optional: Toggle group to generate GROUP BY clause statements.

      • GROUP BY: Select columns to group by. If you include an aggregation function in the SELECT list, you must group by one or more of the queried columns. SQL returns the aggregation for each group.

    • {{< req text="Recommended" color="green" >}}: Toggle order to generate ORDER BY clause statements.

      • ORDER BY: Select columns to sort by. You can sort by time and multiple fields or tags. To sort in descending order, select DESC.

  4. {{< req text="Recommended" color="green" >}}: Change format to Time series.

    • Use the Format dropdown to change the format of the query results. For example, to visualize the query results as a time series, select Time series.

  5. Click Run query to execute the query.

{{% /tab-content %}} {{% tab-content %}}

  1. Click Explore.
  2. In the dropdown, select the InfluxDB data source that you want to query.
  3. Use the InfluxQL query form to build your query:
    • FROM: Select the measurement that you want to query.
    • WHERE: To filter the query results, enter a conditional expression.
    • SELECT: Select fields to query and an aggregate function to apply to each. The aggregate function is applied to each time interval defined in the GROUP BY clause.
    • GROUP BY: By default, Grafana groups data by time to downsample results and improve query performance. You can also add other tags to group by.
  4. Click Run query to execute the query.

{{% /tab-content %}} {{< /tabs-wrapper >}}

With your InfluxDB connection configured, use Grafana to query and visualize time series data.

Build visualizations with Grafana

For a comprehensive walk-through of creating visualizations with Grafana, see the Grafana documentation.

Query inspection in Grafana

To learn more about query management and inspection in Grafana, see the Grafana Explore documentation.