Configure the OpenTSDB data source

This document explains how to configure the OpenTSDB data source in Grafana.

Before you begin

Before configuring the OpenTSDB data source, ensure you have:

• Grafana permissions: Organization administrator role to add data sources.
• OpenTSDB instance: A running OpenTSDB server (version 2.1 or later recommended).
• Network access: The Grafana server can reach the OpenTSDB HTTP API endpoint (default port 4242).
• Metrics in OpenTSDB: For autocomplete to work, metrics must exist in your OpenTSDB database.

Add the data source

To add and configure the OpenTSDB data source:

1. Click Connections in the left-side menu.
2. Click Add new connection.
3. Type OpenTSDB in the search bar.
4. Select OpenTSDB.
5. Click Add new data source in the upper right.
6. Configure the data source settings as described in the following sections.

Configuration options

The following table describes the available configuration options:

Auth settings

Configure authentication if your OpenTSDB server requires it:

OpenTSDB settings

Configure these settings based on your OpenTSDB server version and configuration:

Version-specific features

The version setting enables different query features in Grafana:

Select the version that matches your OpenTSDB server. If you're unsure, check your OpenTSDB version with the /api/version endpoint.

Verify the connection

Click Save & test to verify that Grafana can connect to your OpenTSDB server. A successful test confirms that the URL is correct and the server is responding.

If the test fails, refer to Troubleshooting for common issues and solutions.

Provision the data source

You can define and configure the data source in YAML files as part of the Grafana provisioning system. For more information about provisioning, and for available configuration options, refer to Provisioning Grafana.

YAML example

The following example provisions an OpenTSDB data source:

apiVersion: 1

datasources:
  - name: OpenTSDB
    type: opentsdb
    access: proxy
    url: http://localhost:4242
    jsonData:
      # OpenTSDB version: 1 = <=2.1, 2 = 2.2, 3 = 2.3, 4 = 2.4
      tsdbVersion: 3
      # Resolution: 1 = second, 2 = millisecond
      tsdbResolution: 1
      # Maximum results for suggest/lookup API calls
      lookupLimit: 1000

YAML example with basic authentication

The following example provisions an OpenTSDB data source with basic authentication:

apiVersion: 1

datasources:
  - name: OpenTSDB
    type: opentsdb
    access: proxy
    url: http://localhost:4242
    basicAuth: true
    basicAuthUser: <USERNAME>
    jsonData:
      tsdbVersion: 3
      tsdbResolution: 1
      lookupLimit: 1000
    secureJsonData:
      basicAuthPassword: <PASSWORD>

YAML example with custom headers

The following example provisions an OpenTSDB data source with custom HTTP headers:

apiVersion: 1

datasources:
  - name: OpenTSDB
    type: opentsdb
    access: proxy
    url: http://localhost:4242
    jsonData:
      tsdbVersion: 3
      tsdbResolution: 1
      lookupLimit: 1000
      httpHeaderName1: X-Custom-Header
    secureJsonData:
      httpHeaderValue1: <HEADER_VALUE>

The following table describes the available fields:

Provision with Terraform

You can provision the OpenTSDB data source using Terraform with the Grafana Terraform provider.

For more information about provisioning resources with Terraform, refer to the Grafana as code using Terraform documentation.

Terraform example

The following example provisions an OpenTSDB data source:

terraform {
  required_providers {
    grafana = {
      source  = "grafana/grafana"
      version = ">= 2.0.0"
    }
  }
}

provider "grafana" {
  url  = "<YOUR_GRAFANA_URL>"
  auth = "<YOUR_SERVICE_ACCOUNT_TOKEN>"
}

resource "grafana_data_source" "opentsdb" {
  type = "opentsdb"
  name = "OpenTSDB"
  url  = "http://localhost:4242"

  json_data_encoded = jsonencode({
    # OpenTSDB version: 1 = <=2.1, 2 = 2.2, 3 = 2.3, 4 = 2.4
    tsdbVersion = 3
    # Resolution: 1 = second, 2 = millisecond
    tsdbResolution = 1
    # Maximum results for suggest/lookup API calls
    lookupLimit = 1000
  })
}

Terraform example with basic authentication

The following example provisions an OpenTSDB data source with basic authentication:

resource "grafana_data_source" "opentsdb_auth" {
  type                = "opentsdb"
  name                = "OpenTSDB"
  url                 = "http://localhost:4242"
  basic_auth_enabled  = true
  basic_auth_username = "<USERNAME>"

  json_data_encoded = jsonencode({
    tsdbVersion    = 3
    tsdbResolution = 1
    lookupLimit    = 1000
  })

  secure_json_data_encoded = jsonencode({
    basicAuthPassword = "<PASSWORD>"
  })
}

Replace the following placeholders:

• <YOUR_GRAFANA_URL>: Your Grafana instance URL (for example, https://your-org.grafana.net for Grafana Cloud)
• <YOUR_SERVICE_ACCOUNT_TOKEN>: A service account token with data source permissions
• <USERNAME>: The username for basic authentication
• <PASSWORD>: The password for basic authentication

Next steps

Now that you've configured OpenTSDB, you can:

• Query OpenTSDB data to build dashboards and visualizations
• Use template variables to create dynamic, reusable dashboards
• Add annotations to overlay events on your graphs
• Set up alerting to get notified when metrics cross thresholds
• Troubleshoot issues if you encounter problems