探索 ClickHouse Keeper 状态监控，构建全栈可观测性

ClickHouse Keeper监控全解析

原创于 2025-09-08 10:15:59 发布 · 954 阅读

14 ·

CC 4.0 BY-SA版权

文章标签：

#clickhouse #keeper #学习

OLAP 专栏收录该内容

34 篇文章

订阅专栏

在 ClickHouse 集群架构中，ClickHouse Keeper（自 v21.8 起引入）作为 ZooKeeper 的轻量级替代品，承担着协调复制、管理元数据、选举 leader等关键职责。它虽不存储业务数据，但一旦出现异常，会导致数据无法写入、副本不同步、查询失败等严重问题。

因此，对 ClickHouse Keeper 的状态进行监控，是构建 全栈可观测性（Full-stack Observability） 的关键一环。

本篇将深入详解如何监控 ClickHouse Keeper 的健康状态、性能指标与潜在风险，并集成到统一监控体系中。

🎯 一、为什么必须监控 ClickHouse Keeper？

风险	后果
Leader 选举失败	写入阻塞，复制停滞
网络延迟高	合并任务变慢，TTL 清理延迟
节点宕机	副本无法同步，可能脑裂
日志堆积	操作队列积压，数据不一致

✅ 监控目标：

实时掌握 Keeper 集群健康状态
提前发现性能瓶颈
快速定位故障节点
构建自动化告警机制

🏗️ 二、ClickHouse Keeper 的核心组件

[Client (ClickHouse)] ←→ [ClickHouse Keeper Node 1] (Leader)
                             [ClickHouse Keeper Node 2] (Follower)
                             [ClickHouse Keeper Node 3] (Follower)

基于 Raft 协议 实现一致性
一个集群中只有一个 Leader
所有写操作通过 Leader 提交，再同步给 Follower

🔍 三、关键监控指标

1. 角色状态（Leader/Follower）

SELECT * FROM system.clusters WHERE cluster = 'keeper_cluster';

或通过 Keeper 自身接口：

echo "is_leader" | nc keeper1 9181
# 输出: "yes" 或 "no"

✅ 健康状态：有且仅有一个 Leader

2. 节点存活状态

echo "status" | nc keeper1 9181

输出示例：

mode: follower
term: 10
leader_id: 1
node_id: 2
...

✅ 关键字段：

mode: leader / follower
leader_id: 当前 leader 节点 ID
term: 任期，频繁变化可能表示网络不稳定

3. Raft 日志延迟（Latency）

echo "metrics" | nc keeper1 9181 | grep "raft_log_last_committed_index"

或监控：

raft_log_last_committed_index：已提交日志位置
raft_log_last_stored_index：已存储日志位置
差值越大，延迟越高

4. 请求处理延迟

echo "metrics" | nc keeper1 9181

关注：

session_request_processing_time_us：请求处理耗时（微秒）
commit_log_sync_time_us：日志同步耗时
建议 P99 < 100ms

5. 连接数与会话

echo "sessions" | nc keeper1 9181

输出：

Session 12345 (192.168.1.10:56789) timeout: 30000ms

✅ 监控活跃会话数，防止连接泄露

📊 四、实战：使用 Prometheus + Grafana 监控

1. 配置 Prometheus 抓取 ClickHouse Keeper 指标

在 prometheus.yml 中添加：

- job_name: 'clickhouse-keeper'
  static_configs:
    - targets: ['keeper1:9181', 'keeper2:9181', 'keeper3:9181']
  metrics_path: '/metrics'
  scheme: http

✅ ClickHouse Keeper 默认暴露 /metrics 接口（v22+）

2. 推荐监控面板（Grafana）

创建一个名为 “ClickHouse Keeper Cluster Monitor” 的仪表盘，包含以下 Panels：

Panel 1：集群角色分布

clickhouse_keeper_mode{job="clickhouse-keeper"}

使用 Gauge 或 Text 显示每个节点角色

Panel 2：Leader 切换次数（告警）

changes(clickhouse_keeper_term[5m]) > 0

✅ 频繁切换可能表示网络或磁盘问题

Panel 3：请求延迟（P99）

histogram_quantile(0.99, sum(rate(clickhouse_keeper_session_request_processing_time_us_bucket[1m])) by (le))

Panel 4：Raft 日志同步延迟

clickhouse_keeper_raft_log_last_stored_index - clickhouse_keeper_raft_log_last_committed_index

✅ 应接近 0

Panel 5：活跃会话数

clickhouse_keeper_sessions_count

Panel 6：磁盘写入延迟

clickhouse_keeper_commit_log_sync_time_us

🛠️ 五、结合 ClickHouse 系统表监控复制状态

Keeper 的问题会直接影响 ClickHouse 副本同步。

查询 `system.replicas` 状态

SELECT 
    table,
    is_leader,
    is_readonly,
    queue_size,
    absolute_delay,
    total_replicas,
    active_replicas
FROM system.replicas 
WHERE database = 'default';

✅ 关键指标：

queue_size > 100：操作积压，可能 Keeper 延迟
absolute_delay > 60：同步延迟高
active_replicas < total_replicas：副本失联

⚠️ 六、常见问题与排查

问题	排查方法
`is_readonly = 1`	检查 Keeper 连接，`echo "status" \| nc`
`queue_size` 持续增长	检查 Keeper 延迟、磁盘 I/O
无法写入	检查是否无 Leader，或网络分区
合并慢	检查 `commit_log_sync_time_us` 是否过高
节点无法加入集群	检查 `raft_configuration` 是否一致

✅ 七、最佳实践建议

项目	建议
节点数量	3 或 5（奇数，避免脑裂）
磁盘	使用 SSD，独立挂载
网络	低延迟、高带宽，避免跨机房
配置一致性	所有节点 `config.xml` 中 `raft_configuration` 必须一致
监控频率	Prometheus 抓取间隔 ≤ 15s
告警规则	设置 Leader 切换、延迟过高、会话异常告警

🎯 八、总结：ClickHouse Keeper 监控的核心价值

能力	说明
👁️ 可观测性	实时掌握集群协调层状态
🚨 主动告警	提前发现 Keeper 性能瓶颈
🔍 故障定位	区分是 Keeper 问题还是 ClickHouse 问题
📈 性能优化	优化 Raft 日志、减少延迟
🧩 全栈监控	与 ClickHouse、Kafka、MinIO 统一监控