| name | clickhouse-observability |
| description | Monitor ClickHouse with Prometheus metrics, Grafana dashboards, system table
queries, and alerting for query performance, merge health, and resource usage.
Use when setting up ClickHouse monitoring, building Grafana dashboards, or
configuring alerts for production ClickHouse deployments.
Trigger with "clickhouse monitoring", "clickhouse metrics", "clickhouse Grafana",
"clickhouse observability", "monitor clickhouse", "clickhouse Prometheus".
|
| allowed-tools | Read, Write, Edit |
| version | 1.7.0 |
| license | MIT |
| author | Jeremy Longshore <jeremy@intentsolutions.io> |
| tags | ["saas","database","analytics","clickhouse","olap"] |
| compatibility | Designed for Claude Code |
ClickHouse Observability
Overview
Set up comprehensive monitoring for ClickHouse using built-in system tables,
Prometheus integration, Grafana dashboards, and alerting rules. The workflow
layers four signal sources: system.* tables (always available, zero
dependencies), a Prometheus scrape endpoint, application-level client
instrumentation, and alert rules that fire on the failure modes that actually
page an on-call — high error rate, latency creep, merge backlog, and resource
exhaustion.
Deep configs live in references/ so this file stays a fast, followable map.
Prerequisites
- ClickHouse instance with
system.* table access
- Prometheus (or compatible: Grafana Alloy, Victoria Metrics)
- Grafana for dashboards
- AlertManager or PagerDuty for alerts
Instructions
Step 1: Query system tables for a health snapshot
Start with zero dependencies — the system.* tables already hold everything.
Run this for an instant server-health read:
SELECT
(SELECT count() FROM system.processes) AS running_queries,
(SELECT value FROM system.metrics WHERE metric = 'MemoryTracking') AS memory_bytes,
(SELECT count() FROM system.merges) AS active_merges;
Query throughput, insert rates, and per-table part counts (the merge-health
signal), plus a full table of which system.* table to poll at what frequency:
system table queries & reference.
Step 2: Wire up Prometheus scraping
ClickHouse Cloud exposes a managed Prometheus endpoint (Basic auth with a Cloud
API key); self-hosted uses the built-in :9363 /metrics endpoint enabled in
config.xml. Write the scrape config to your prometheus.yml. Full Cloud +
self-hosted scrape configs and the config.xml block:
Prometheus scrape config & Grafana dashboards.
