ClickHouseNotes

第 27 章：监控告警

zjc 于 2026-01-27 发布

这是《ClickHouse 零基础实战指南》的独立章节版。本章从概念、实操和生产排查三个视角展开，代码块保留了原书可直接运行的版本。 ClickHouse 监控要覆盖服务存活、资源、存储、合并、副本、查询、写入和业务指标。只有服务 green 不代表链路健康。

27.1 监控层次

基础设施
  -> ClickHouse 服务
  -> 存储与合并
  -> 副本与集群
  -> 查询与写入
  -> 业务数据质量

27.2 系统表

常用表：

系统表 用途
system.metrics 当前指标
system.events 累计事件
system.asynchronous_metrics 异步指标
system.query_log 查询日志
system.part_log part 操作
system.merges 当前合并
system.replicas 副本状态
system.disks 磁盘
system.clusters 集群

查看核心指标：

SELECT metric, value
FROM system.metrics
WHERE metric IN (
    'Query',
    'Merge',
    'ReplicatedFetch',
    'DistributedSend',
    'Read',
    'Write'
);

27.3 Prometheus

ClickHouse 提供 Prometheus 格式的 HTTP 端点，也可以使用 exporter。抓取配置示例：

scrape_configs:
  - job_name: clickhouse
    static_configs:
      - targets:
          - ch-01:8123
          - ch-02:8123

采集内容要结合版本确认。常见监控项：

分类 指标
服务 uptime、version、HTTP 可用
CPU 使用率、iowait
内存 used、swap、OOM
磁盘 空间、IO util、延迟
查询 QPS、失败率、耗时
写入 行数、字节、失败
合并 当前数、耗时、异常
副本 readonly、queue、delay

27.4 磁盘监控

SELECT
    name,
    path,
    total_space,
    free_space,
    unreserved_space
FROM system.disks
ORDER BY free_space;

告警建议：

  1. 空间使用率超过 70% 预警；
  2. 超过 85% 处理；
  3. 剩余空间低于合并预估临时空间则高危；
  4. 磁盘只读立即处理。

27.5 合并与 part 监控

SELECT
    database,
    table,
    count() AS active_parts,
    sum(rows) AS rows,
    sum(bytes_on_disk) AS bytes
FROM system.parts
WHERE active
GROUP BY database, table
ORDER BY active_parts DESC;

SELECT count() AS running_merges
FROM system.merges;

告警：

条件 级别
单分区 parts 持续增长 预警
接近 max parts_in_total 高危
merge 异常增加 预警
磁盘 IO util 持续 90%+ 高危

27.6 副本监控

SELECT
    database,
    table,
    replica_name,
    is_readonly,
    queue_size,
    inserts_in_queue,
    merges_in_queue,
    absolute_delay
FROM system.replicas;

告警：

  1. 任一副本 readonly；
  2. queue_size 持续增长；
  3. absolute_delay 超过阈值；
  4. Keeper 会话断开；
  5. 副本消失。

27.7 查询监控

SELECT
    count() AS total,
    countIf(type = 'QueryFinish') AS finished,
    countIf(type = 'ExceptionWhileProcessing') AS failed,
    avg(query_duration_ms) AS avg_ms,
    max(query_duration_ms) AS max_ms
FROM system.query_log
WHERE event_date = today();

Top 慢查询：

SELECT query, query_duration_ms, read_bytes, memory_usage
FROM system.query_log
WHERE type = 'QueryFinish'
ORDER BY query_duration_ms DESC
LIMIT 20;

27.8 Kafka 链路监控

必须采集：

  1. consumer group lag；
  2. topic 分区落后；
  3. 消息错误数；
  4. dead letter 数量；
  5. ClickHouse 写入失败；
  6. 目标表行数环比。

查看 ClickHouse 消费者：

SELECT database, table, consumer_id, assignments.topic
FROM system.kafka_consumers;

27.9 日志

常见日志：

/var/log/clickhouse-server/clickhouse-server.log
/var/log/clickhouse-server/clickhouse-server.err.log

搜索关键字：

rg -n "Too many parts|MEMORY_LIMIT_EXCEEDED|KeeperException|DNS_ERROR|Timeout|Broken part|Disk space" \
  /var/log/clickhouse-server

日志保留要与故障回溯窗口匹配，并集中采集到日志系统。

27.10 告警分级

级别 示例
P0 集群不可用、磁盘满、多数 Keeper 失败
P1 大量写入失败、副本 readonly、核心报表无数据
P2 lag 增长、慢查询增加、parts 上涨
P3 配置漂移、低峰任务超时

每条告警应有 runbook：原因、检查 SQL、处理步骤、升级路径。

本章小结

监控 ClickHouse 不能只看进程和端口。磁盘、合并、副本队列、查询成本、Kafka lag 和业务对账共同决定系统健康。告警必须可行动，并配套可执行的排查手册。

思考题

  1. 为什么磁盘空间监控要预留合并空间？
  2. 副本 queue_size 增长说明什么？
  3. 如何发现高成本 SQL？
  4. Kafka lag 应按什么维度告警？
  5. 一条合格告警应包含哪些信息？