---
title: Connect Grafana to Tinybird
meta:
  description: This guide covers the steps to connect Grafana to Tinybird using Altinity and ClickHouse plugins, enabling the visualization of Tinybird data within Grafana.
headingMaxLevels: 2
---

# 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](https://grafana.com/grafana/plugins/grafana-clickhouse-datasource/)** 
- **[Altinity plugin](https://grafana.com/grafana/plugins/vertamedia-clickhouse-datasource/)**

{% callout type="info" %}
The ClickHouse® connection to Tinybird is read-only. You can use it to visualize data from your Tinybird data sources, but you cannot modify data through this connection.
{% /callout %}

{% callout type="tip" %}
Remember you can expose metrics like API Endpoints in Prometheus format. See an [example](https://www.tinybird.co/templates/tinybird-org-metrics).  
And if you want to connect regular API Endpoints and not Data Sources you can use Infinity data source plugin for Grafana.
{% /callout %}

## Prerequisites

- A Tinybird workspace
- A Grafana instance (local or cloud)
- A Tinybird Auth Token with scopes `WORKSPACE:READ_ALL` and optionally `ORG_DATASOURCES:READ`. See [how to create it](../clickhouse-interface#auth-token-requirements).

## 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:

```bash
Server address: {% user("clickhouseHost") %} # your host with 'clickhouse' subdomain instead of 'api', like clickhouse.eu-west-1.aws.tinybird.co
Server port: 443
Protocol: HTTP
Secure Connection: yes
```

{% callout type="info" %}
See the list of [ClickHouse hosts](../clickhouse-interface#clickhouse-interface-hosts) to find the correct one for your region.
{% /callout %}

4. Add your authentication credentials:

```bash
Username: <WORKSPACE_NAME> # not used for auth, helps you identify the connection
Password: {% user("JWT") %} # your Tinybird Auth Token
```

5. Select **Save & Test** to verify the connection

{% image src="/img/grafana-plugin-1.png" alt="ClickHouse® plugin configuration" caption="ClickHouse® plugin configuration" /%}

## Configure the ClickHouse® plugin for OpenTelemetry

{% callout type="tip" %}
Use the [OpenTelemetry template](https://tinybird.co/templates/opentelemetry) to build an end to end observability solution with OpenTelemetry and Tinybird.

This section assumes you have the OpenTelemetry template deployed in a Tinybird Workspace.
{% /callout %}

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`.

{% image src="/img/grafana-plugin-3.png" alt="ClickHouse® plugin configuration for OpenTelemetry" caption="ClickHouse® plugin configuration for OpenTelemetry" /%}

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

{% image src="/img/grafana-plugin-4.png" alt="ClickHouse® plugin configuration for OpenTelemetry" caption="ClickHouse® OTel dashboard" /%}

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

{% image src="/img/grafana-plugin-6.png" alt="ClickHouse® plugin configuration for OpenTelemetry" caption="ClickHouse® Simple OTel dashboard" /%}

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

{% image src="/img/grafana-plugin-5.png" alt="ClickHouse® plugin configuration for OpenTelemetry" caption="OpenTelemetry logs explorer" /%}

### 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

{% callout type="info" %}
See the list of [ClickHouse hosts](../clickhouse-interface#clickhouse-interface-hosts) to find the correct one for your region.
{% /callout %}

```yaml
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:

```bash
URL: https://{% user("clickhouseHost") %}
Access: Server
```

{% callout type="info" %}
See the list of [ClickHouse hosts](../clickhouse-interface#clickhouse-interface-hosts) to find the correct one for your region.
{% /callout %}

4. Select Basic auth and add credentials:

```bash
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

{% image src="/img/grafana-plugin-2.png" alt="Altinity plugin configuration" caption="Altinity plugin configuration" /%}

## 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.