Connect Grafana to Tinybird¶

Grafana can connect to Tinybird using ClickHouse® plugins, taking advantage of Tinybird's ClickHouse® HTTP protocol compatibility.

This guide covers how to set up Grafana with Tinybird using two popular ClickHouse® plugins:

• ClickHouse® plugin
• Altinity plugin

Prerequisites¶

• A Tinybird workspace
• A Grafana instance (local or cloud)
• A Tinybird Auth Token with read permissions for the workspace data sources, and Organization data sources.

Install the ClickHouse® plugin¶

Install one of the ClickHouse® plugins in your Grafana instance:

1. ClickHouse® plugin - The official ClickHouse® plugin for Grafana
2. Altinity plugin - developed by Vertamedia, maintaned by Altinity since 2020

Select one based on your needs and install it through the Grafana plugin catalog or using grafana-cli.

Configure the ClickHouse® plugin¶

If you're using the official ClickHouse® plugin:

1. Go to Configuration > Data Sources in Grafana
2. Select Add data source and select ClickHouse®
3. Configure the connection with these settings:

Server address: clickhouse.tinybird.co # your host with 'clickhouse' subdomain instead of 'api', like clickhouse.eu-west-1.aws.tinybird.co
Server port: 443
Protocol: HTTP
Secure Connection: yes

4. Add your authentication credentials:

Username: <WORKSPACE_NAME> # not used for auth, helps you identify the connection
Password: <TOKEN> # your Tinybird Auth Token

5. Select Save & Test to verify the connection

Configure the ClickHouse® plugin for OpenTelemetry¶

Once you've configured the ClickHouse plugin, edit the Grafana Data Source. You'll see the Logs and Traces configurations. Check the Use OTel checkboxes and set your Tinybird workspace name as Default database.

From the Dashboards tab, you can import the Simple ClickHouse OTel dashboard as a starting point to analyze your OpenTelemetry logs and traces.

You can add and edit visualization panels by writing new SQL queries to analyze your logs, metrics and traces.

Use the Explore feature in Grafana to filter and analyze your OpenTelemetry logs:

Provisioning the ClickHouse data source¶

You can also provision the ClickHouse data source using a YAML file, which is useful for managing your Grafana configuration as code.

This snippet uses the following environment variables, which you must set before applying it:

• TINYBIRD_WORKSPACE_NAME: Your workspace name
• TINYBIRD_TOKEN: A scoped or admin token
• TINYBIRD_CLICKHOUSE_HOST: Your ClickHouse HTTP interface host

apiVersion: 1

datasources:
  - name: Tinybird OTel Cloud
    uid: tinybird-otel-cloud
    type: grafana-clickhouse-datasource
    access: proxy
    editable: true
    isDefault: false
    jsonData:
      defaultDatabase: ${TINYBIRD_WORKSPACE_NAME}
      host: ${TINYBIRD_CLICKHOUSE_HOST}
      logs:
        contextColumns: []
        defaultDatabase: ${TINYBIRD_WORKSPACE_NAME}
        defaultTable: otel_logs
        otelEnabled: true
        otelVersion: latest
        selectContextColumns: true
      pdcInjected: false
      port: 443
      protocol: http
      secure: true
      tlsSkipVerify: false
      traces:
        defaultDatabase: ${TINYBIRD_WORKSPACE_NAME}
        defaultTable: otel_traces
        durationUnit: nanoseconds
        otelEnabled: true
        otelVersion: latest
      useOtel: true
      username: otel
      version: 4.10.2
    secureJsonData:
      password: ${TINYBIRD_TOKEN}

Configure the Altinity plugin¶

If you're using the Altinity plugin:

1. Go to Configuration > Data Sources in Grafana
2. Select Add data source and select Altinity plugin for ClickHouse®
3. Configure the connection with these settings:

URL: https://clickhouse.tinybird.co
Access: Server

4. Select Basic auth and add credentials:

User: <WORKSPACE_NAME> # not used for auth, helps you identify the connection
Password: <TOKEN> # your Tinybird Auth Token

5. Select Save & Test to verify the connection

Test the connection¶

Once configured, test your connection by creating a simple query:

1. Create a new dashboard and add a panel
2. Select your newly created data source
3. Write a simple query to test the connection

If the connection is working, you should see the result.

Databases and tables¶

The SQL API exposes four databases: organization, system, tinybird, and workspace name:

• organization: for the Organization data sources, like organization.workspaces, organization.pipe_stats_rt
• system: for system.tables, system.columns
• tinybird: for the Workspace Service data sources like tinybird.datasources_ops_log, tinybird.pipe_stats_rt
• your workspace name: for your Workspace data sources.

Next steps¶

• Explore Grafana's visualization options with your Tinybird data
• Set up alerts based on your real-time data
• Create dashboards that combine data from multiple sources
• Use Grafana variables to make your dashboards interactive

Troubleshooting¶

Connection failed: Verify that your Auth Token has read permissions and that the host URL is correct for your region.

Query timeout: For large datasets, consider using Materialized Views or adding appropriate filters to your queries.

Authentication errors: Double-check that your Auth Token is correct and that you've entered it into the Password field.

Write operations fail: Remember that the ClickHouse® connection to Tinybird is read-only. You cannot use it to insert, update, or delete data.