chmonitor

Monitor distributed cluster topology, replication health, and Keeper/ZooKeeper coordination state.

Routes/clusters, /keeper/overview, /keeper, /keeper/info, /keeper/connections, /keeper/connection-log, /keeper/log, /keeper/watches
Feature idcluster
Default accesspublic
Requires authNo (set CHM_FEATURE_CLUSTER_ACCESS=authenticated to gate)
System tablessystem.clusters, system.zookeeper, system.zookeeper_info, system.zookeeper_connection, system.zookeeper_connection_log, system.zookeeper_log, system.zookeeper_watches
ClickHouse grantsSELECT on the system tables above

What it does

The Cluster section answers two questions: what nodes make up your cluster, and how is Keeper/ZooKeeper coordinating them?

The Clusters page renders an interactive topology map of every shard and replica pulled from system.clusters. Use it to confirm shard layouts, spot misconfigured hosts, or audit cluster membership after a scaling event.

The Keeper sub-section shows the ZooKeeper/ClickHouse Keeper coordination layer: node health, liveness, request latency, the znode tree, active watches, and connection history. These pages are only available when your ClickHouse server has Keeper or ZooKeeper configured.

Pages

PageRouteWhat it showsSystem tables
Clusters/clustersInteractive topology map, shard/replica membershipsystem.clusters
Keeper Overview/keeper/overviewLiveness, request load, latency, per-node cluster statesystem.zookeeper_info
Data Browser/keeper?path=/Browse the znode treesystem.zookeeper
Keeper Info/keeper/infoPer-node role, raft log, znode counts, latencysystem.zookeeper_info
Connections/keeper/connectionsLive connections from this server to Keepersystem.zookeeper_connection
Connection Log/keeper/connection-logHistory of connect/disconnect events with reasonssystem.zookeeper_connection_log
Request Log/keeper/logPer-request log of Keeper operations and responsessystem.zookeeper_log
Watches/keeper/watchesCurrently active watches registered by this serversystem.zookeeper_watches

Permissions & access

All Cluster pages use the cluster feature id.

Disable the entire section:

CHM_FEATURE_CLUSTER_ENABLED=false

Require authentication:

CHM_FEATURE_CLUSTER_ACCESS=authenticated

Using a config file (CHM_CONFIG_FILE):

[features.cluster]
enabled = true
access = "authenticated"

Configuration

No feature-specific configuration. Keeper pages appear automatically when system.zookeeper_info is accessible on the connected host. If the table is absent (no Keeper configured), pages show an empty state rather than an error.

Notes & limitations

  • Keeper tables are optional. system.zookeeper, system.zookeeper_info, system.zookeeper_connection, system.zookeeper_connection_log, system.zookeeper_log, and system.zookeeper_watches only exist when ClickHouse Keeper or ZooKeeper is configured. Pages backed by missing tables show an informational empty state.
  • system.zookeeper_log requires <zookeeper_log> to be enabled in the ClickHouse server config.
  • The topology map requires system.clusters and correctly populated host_name/port values. Clusters defined only in remote_servers with unresolvable hostnames still appear but may lack connection metadata.
  • The Connections page shows live connections at query time; historical data is in the Connection Log.