TraceHouse for Grafana

Monitor ClickHouse merges, queries, parts, replication, and storage from Grafana.

What is TraceHouse?

TraceHouse queries ClickHouse system.* tables (parts, merges, queries, replication queue, etc.) through the Grafana ClickHouse datasource. No external agents needed.

Features

Database Explorer

Browse databases, tables, columns, and storage details.

Time Travel

Replay how tables, parts, and merges evolved over any time window. See when parts were created, merged, or moved.

Query History

Query breakdown by user, query kind, and status. Identify slow queries, see normalized query patterns, and link from query history to time-travel views.

3D Analytics

3D surface visualizations for query and merge patterns over time.

Grafana Panel Export

Export TraceHouse analytics views as native Grafana panels for dashboards and ongoing monitoring.

Learn more about Grafana panel export

System Map

Visual overview of table sizes, part counts, and storage distribution across your cluster.

Overview Dashboard

Cluster health at a glance: CPU, memory, active queries, running merges, and replication lag across all nodes.

Merge Tracker

Real-time merge monitoring with per-merge progress bars, throughput, elapsed/remaining time, and X-ray detail view.

Engine Internals

Inspect MergeTree parts, partitions, storage policies, and data distribution.

Cluster Topology

Multi-node view with shard/replica status and per-node resource utilization.

Replication

Replication queue depth, log lag, and inter-replica sync status.

Requirements

• Grafana >= 11.6.11 <12, >=12.0.10 <12.1, >=12.1.7 <12.2, or >=12.2.5
• ClickHouse 21.8+ with system.* tables accessible
• Grafana ClickHouse datasource plugin installed and configured

Getting Started

1. Install the plugin from the Grafana plugin catalog or side-load the signed zip
2. Enable the plugin under Administration > Plugins > TraceHouse
3. Ensure you have a ClickHouse datasource configured pointing to your cluster
4. Open TraceHouse from the sidebar and start exploring

Configuration

Go to the TraceHouse Configuration page to set:

• Allowed Refresh Rates — Control which auto-refresh intervals are available. Disabling aggressive rates (1s, 2s) reduces load on your ClickHouse cluster.
• Default Refresh Rate — The refresh interval applied when a user first opens any TraceHouse page.

Documentation

• Documentation
• GitHub Repository
• Bug Reports & Feature Requests

License

Apache 2.0 — see LICENSE for details.