> ## Documentation Index
> Fetch the complete documentation index at: https://learn.kubit.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect ClickHouse

> Connect a self-hosted or ClickHouse Cloud database so Kubit Atlas queries agent trace tables where they are.

Kubit Atlas can query agent traces in your own ClickHouse, self-hosted or ClickHouse Cloud. Kubit runs its queries against your trace tables in place, and Polaris labels every span. No data silo to secure. Traces retained in your control.

## When to use

| Use case | Example |
| - | - |
| Your OpenTelemetry Collector already writes traces to ClickHouse | The Collector's `clickhouse` exporter fills `otel.otel_traces` |
| You self-host Langfuse | Langfuse stores traces in your own ClickHouse |
| You want agent traces next to product data | Join `otel_traces` to your users or orders tables in the same cluster |

**Availability:** Langfuse Cloud keeps traces in Langfuse's own ClickHouse, not yours. For Langfuse Cloud, send traces with `KubitSpanProcessor` instead. See [Set up with your coding agent](https://learn.kubit.ai/coding-agent-setup.md).

## Before you start

* [ ] A ClickHouse user that can create users and grant privileges
* [ ] The trace table name. The OpenTelemetry Collector default is `otel.otel_traces`.
* [ ] A way for Kubit to reach the cluster: a public endpoint with an IP allowlist, or private networking 

## Steps

**1. Create a user for Kubit**

```sql theme={null}
CREATE USER kubit IDENTIFIED BY '<strong-password>';
```

**2. Grant read access to the trace tables**

```sql theme={null}
GRANT SELECT ON otel.* TO kubit;
```

Replace `otel` with the database that holds your trace tables.

**3. Grant write access for Polaris annotations**

Polaris writes labels and scores back to your cluster.

```sql theme={null}
-- TODO(eng): confirm database name and privileges Kubit needs for write-back
CREATE DATABASE IF NOT EXISTS kubit;
GRANT SELECT, INSERT, CREATE TABLE ON kubit.* TO kubit;
```

**4. Allow Kubit's IP addresses**

Add Kubit's egress IPs to your firewall or security group for the ClickHouse port.

**5. Add the connection in Kubit**

**6. Map your trace table**

## Connection parameters

| Parameter | Required? | Notes |
| - | - | - |
| **Host** | **Yes** | Hostname or IP of the cluster's public or private endpoint |
| **Port** | **Yes** | **TBD** |
| **User** | **Yes** | The `kubit` user created above |
| **Password** | **Yes** | Stored encrypted in Kubit |
| **Database** | **Yes** | The database with your trace tables |
| **TLS** | **TBD** | |

## Constraints

| Constraint | Value |
| - | - |
| Supported ClickHouse versions | **TBD** |
| Trace schema | OpenTelemetry Collector `clickhouse` exporter schema **TBD** |
| Query load on your cluster | **TBD** |

## Verify

Ask your assistant with the Kubit MCP server connected:

> "How many traces are in the last 24 hours, by service.name?"

The counts match:

```sql theme={null}
SELECT ServiceName, count(DISTINCT TraceId)
FROM otel.otel_traces
WHERE Timestamp > now() - INTERVAL 1 DAY
GROUP BY ServiceName;
```

## If it fails

| Symptom | Cause | Fix |
| - | - | - |
| Connection times out | Firewall or security group blocks Kubit's IPs | Allow Kubit's egress IPs on the ClickHouse port |
| `Code: 516. DB::Exception: kubit: Authentication failed: password is incorrect, or there is no user with such name. (AUTHENTICATION_FAILED)` | Wrong password or user | Reset the password with `ALTER USER kubit IDENTIFIED BY '<new-password>'` |
| `Code: 497. DB::Exception: kubit: Not enough privileges.` ending in `(ACCESS_DENIED)` | Missing `SELECT` grant | Run the `GRANT SELECT` step for the right database |
| Counts in Atlas are lower than in ClickHouse | Spans dropped by the default filter, or a time zone difference | |

## MCP prompt examples

> "Show me the top 10 execution paths for the support agent in the last 7 days"

> "Which traces in ClickHouse had an Exception on a tool span yesterday?"

## Related

* [Concepts](https://learn.kubit.ai/concepts.md): what Polaris adds to each span.
* [Span attributes](https://learn.kubit.ai/send-traces/span-attributes.md): the columns Atlas reads for users and sessions.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.