Connect ClickHouse

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.

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

Create a user for Kubit

CREATE USER kubit IDENTIFIED BY '<strong-password>';

Grant read access to the trace tables

GRANT SELECT ON otel.* TO kubit;

Replace otel with the database that holds your trace tables.

Grant write access for Polaris annotations

Polaris writes labels and scores back to your cluster.

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

Allow Kubit's IP addresses

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

Add the connection in Kubit

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:

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?”

Concepts: what Polaris adds to each span.
Span attributes: the columns Atlas reads for users and sessions.

Start here

Get started

Send traces

Bring your own warehouse

When to use

Before you start

Steps

Connection parameters

Constraints

Verify

If it fails

MCP prompt examples

​When to use

​Before you start

​Steps

​Connection parameters

​Constraints

​Verify

​If it fails

​MCP prompt examples

​Related

When to use

Before you start

Steps

Connection parameters

Constraints

Verify

If it fails

MCP prompt examples

Related