MergeTree 的健康状况 几乎全在 system 表——不像 PostgreSQL 需凑 pg_stat_* + OS。平台工程师应把 system.parts、system.merges、system.replicas、system.query_log 纳入基线监控，并与 可观测性系列 的 metrics/logs 栈对接：Pull SQL → Prometheus clickhouse_exporter 或定制 cron。

本文说明 字段含义、组合查询、告警阈值思路——不编造具体数字阈值；阈值须按集群规模与 SLA 在本环境标定。

版本锚定：ClickHouse 24.x LTS。

一、监控分层

flowchart TB
  subgraph l1 [L1 存活]
    UP[HTTP /ping]
    ZK[Keeper 连通]
  end
  subgraph l2 [L2 存储健康]
    P[parts 数量]
    M[merge 队列]
    R[replica lag]
  end
  subgraph l3 [L3 查询]
    Q[query_log 延迟]
    MEM[memory tracking]
  end
  subgraph l4 [L4 业务]
    SLA[dashboard p95]
  end
  l1 --> l2 --> l3 --> l4

二、system.parts

Part 是 MergeTree 数据单元（第 02 篇）。

2.1 核心字段

2.2 常用查询

-- 每表 active part 数（too many parts 前兆）
SELECT database, table, count() AS parts, sum(rows) AS rows, sum(bytes_on_disk) AS bytes
FROM system.parts
WHERE active
GROUP BY database, table
ORDER BY parts DESC;

-- 分区级 part 数
SELECT database, table, partition, count() AS parts
FROM system.parts
WHERE active
GROUP BY database, table, partition
HAVING parts > 50
ORDER BY parts DESC;

告警思路：单表 active parts 持续增长且不回落 → merge 跟不上（第 15 篇）。阈值取决于 parts_to_throw_insert 配置（第 16 篇）。

2.3 Wide vs Compact

part_type 字段（版本相关）——Wide 每列独立文件；监控磁盘时 bytes_on_disk 已含全部。

三、system.merges

后台 merge 任务实时视图。

SELECT database, table, elapsed, progress, num_parts, memory_usage
FROM system.merges
ORDER BY elapsed DESC;

告警思路：

• 长期非空且 elapsed 极大 → merge 堵或单 part 过大；
• memory_usage 接近 max_memory_usage → merge OOM 风险。

与 Merge 机制（第 06 篇） 对照读 merge_algorithm。

四、system.replication_queue

ReplicatedMergeTree 待执行 log entry（第 08 篇）。

SELECT database, table, replica_name, position, node_name, type, create_time, num_tries, last_exception
FROM system.replication_queue
ORDER BY create_time
LIMIT 50;

SELECT database, table,
       max(log_max_index - log_pointer) AS lag_approx
FROM system.replicas
GROUP BY database, table;

（字段名以 24.x 为准——log_pointer、log_max_index 等。）

五、system.replicas

副本状态汇总。

SELECT database, table, replica_name, is_leader, is_readonly, absolute_delay, queue_size
FROM system.replicas
WHERE absolute_delay > 0
ORDER BY absolute_delay DESC;

告警：is_readonly=1 或 absolute_delay 超 SLA → 副本故障模式（第 15 篇）。

六、system.query_log

需配置 query_log（通常默认开启）。

SELECT
    type,
    event_time,
    query_duration_ms,
    read_rows,
    read_bytes,
    written_rows,
    memory_usage,
    exception_code,
    query
FROM system.query_log
WHERE event_date = today()
  AND type = 'QueryFinish'
ORDER BY query_duration_ms DESC
LIMIT 20;

慢查挖掘：

SELECT normalizeQuery(query) AS q, count(), avg(query_duration_ms), max(read_rows)
FROM system.query_log
WHERE event_date >= today() - 7 AND type = 'QueryFinish' AND query_duration_ms > 1000
GROUP BY q
ORDER BY count() DESC
LIMIT 20;

不粘贴示例输出。

七、system.metrics 与 asynchronous_metrics

• system.metrics：Gauge 类瞬时值（如 Merge, Query, TCPConnection）；
• system.asynchronous_metrics：异步采集（CPU、内存、磁盘）。

SELECT metric, value FROM system.metrics WHERE metric LIKE '%Merge%';
SELECT metric, value FROM system.asynchronous_metrics WHERE metric LIKE '%Memory%';

对接 Prometheus：社区 exporter 映射这些指标——版本与 metric 名随 CH 演进，部署时 diff 24.x 文档。

八、system.events

累积 counter，重启清零。

SELECT event, value FROM system.events
WHERE event IN ('InsertedRows', 'MergedRows', 'OSIOWaitMicroseconds')
ORDER BY value DESC
LIMIT 30;

计算 ingest 速率：两次采样 InsertedRows 差 / Δt。

九、system.mutations

SELECT database, table, mutation_id, command, create_time, parts_to_do, is_done, latest_failed_part
FROM system.mutations
WHERE NOT is_done
ORDER BY create_time;

parts_to_do 长期不降 → mutation 堆积（第 15 篇）。

十、system.detached_parts

异常 part 被 detach 后躺在此——磁盘泄漏与复制异常信号。

SELECT database, table, name, reason, bytes_on_disk
FROM system.detached_parts;

十一、内存 tracking

Settings：

• max_memory_usage — 单查询；
• max_memory_usage_for_user；
• max_server_memory_usage — 进程级（比例 of RAM）。

SELECT formatReadableSize(value) FROM system.settings WHERE name = 'max_server_memory_usage';

system.processes 看当前查询内存：

SELECT query_id, user, elapsed, formatReadableSize(memory_usage) AS mem, query
FROM system.processes
ORDER BY memory_usage DESC;

十二、分布式监控

逐 shard 跑相同 SQL 或通过 cluster()：

SELECT hostName(), count() AS parts
FROM clusterAllReplicas('prod', system.parts)
WHERE active AND database = 'db' AND table = 'events_local'
GROUP BY hostName();

第 09 篇 Distributed 写入不均时 parts 倾斜可见。

十三、与 observability 栈集成

指标体系 建议：Ticket 级 告警 parts/merge lag；Page 级 仅当 CH 故障影响业务 SLA。

十四、基线采集脚本框架

#!/bin/bash
# 示例：cron 每分采集 parts 计数 — 须配置 clickhouse-client
clickhouse-client --query "
  SELECT now(), database, table, count() AS parts
  FROM system.parts WHERE active
  GROUP BY database, table
  FORMAT CSV
" >> /var/log/ch_parts_baseline.csv

十五、DuckDB 监控（对照）

DuckDB 无 system.parts——嵌入式用：

PRAGMA database_size;
SELECT * FROM duckdb_memory();

生产 OLAP 监控主战场仍是 ClickHouse；DuckDB 进程内由宿主应用 metrics。

十六、小结

附录 A、system.parts 与 disk 联合

SELECT
    database,
    table,
    formatReadableSize(sum(bytes_on_disk)) AS disk,
    count() AS parts,
    sum(rows) AS rows
FROM system.parts
WHERE active
GROUP BY database, table
ORDER BY sum(bytes_on_disk) DESC
LIMIT 30;

附录 B、ProfileEvents 示例键

从 query_log.ProfileEvents JSON 解析——键名随版本增删。

附录 C、query_log 表引擎与 TTL

query_log 自身是 MergeTree——可 TTL event_date + INTERVAL 30 DAY 防磁盘涨。log_queries_min_type 控制写入类型。

附录 D、Prometheus 映射思路

exporter 定时 scrape——阈值在 Grafana 按环境设。

附录 E、告警分级建议

对齐 可观测性告警分级 思路。

附录 F、system.disks 与 storage_policy

SELECT name, path, formatReadableSize(free_space), formatReadableSize(total_space)
FROM system.disks;

多卷 storage_policy 时 merge 临时空间可能在 default disk——规划见 第 16 篇。

附录 G、text_log / trace_log

OpenTelemetry 集成可选 system.opentelemetry_span_log（版本相关）——与 observability trace 联动。

附录 H、只读副本监控

system.replicas 中 is_readonly=1 且 zookeeper_exception 非空——Keeper 会话问题。只读副本适合报表，但 delay 过大仍 stale。

附录 I、system.metrics 常用项

Query, Merge, PartMutation, ReplicatedFetch, TCPConnection, HTTPConnection, MemoryTracking——baseline 拍快照对比 delta。

附录 J、asynchronous_metrics 硬件

OSMemoryAvailable, OSCpuLoad, DiskAvailable, Uptime——节点级。与 node_exporter redundant 但 CH 内聚。

附录 K、system.errors

最近错误 counter——突增 NETWORK_ERROR / MEMORY_LIMIT_EXCEEDED 关联告警。

附录 L、part_log / text_log

part_log 记录 part 创建/merge 历史——审计 parts 从哪来。text_log 服务器 log 入库。

附录 M、Grants 审计

附录 N、Weekly review SQL pack

合并 parts top10、slow query top10、replica delay、mutation undone——平台 weekly 例会模板。

附录 · 深度补充（系列交叉索引）

深度 1

第 14 章与系列其它篇章的交叉：读路径见 第 05 篇；merge 见 第 06 篇；索引见 第 07 篇；副本见 第 08 篇；Distributed 见 第 09 篇；监控见 第 14 篇；故障见 第 15 篇；配置见 第 16 篇。 实施任何 setting 变更前，在 staging 用 system.parts / query_log 建立 24h 基线，变更后再对比——避免无证据调参。

深度 2

第 14 章与系列其它篇章的交叉：读路径见 第 05 篇；merge 见 第 06 篇；索引见 第 07 篇；副本见 第 08 篇；Distributed 见 第 09 篇；监控见 第 14 篇；故障见 第 15 篇；配置见 第 16 篇。 实施任何 setting 变更前，在 staging 用 system.parts / query_log 建立 24h 基线，变更后再对比——避免无证据调参。

深度 3

第 14 章与系列其它篇章的交叉：读路径见 第 05 篇；merge 见 第 06 篇；索引见 第 07 篇；副本见 第 08 篇；Distributed 见 第 09 篇；监控见 第 14 篇；故障见 第 15 篇；配置见 第 16 篇。 实施任何 setting 变更前，在 staging 用 system.parts / query_log 建立 24h 基线，变更后再对比——避免无证据调参。

深度 4

第 14 章与系列其它篇章的交叉：读路径见 第 05 篇；merge 见 第 06 篇；索引见 第 07 篇；副本见 第 08 篇；Distributed 见 第 09 篇；监控见 第 14 篇；故障见 第 15 篇；配置见 第 16 篇。 实施任何 setting 变更前，在 staging 用 system.parts / query_log 建立 24h 基线，变更后再对比——避免无证据调参。

深度 5

第 14 章与系列其它篇章的交叉：读路径见 第 05 篇；merge 见 第 06 篇；索引见 第 07 篇；副本见 第 08 篇；Distributed 见 第 09 篇；监控见 第 14 篇；故障见 第 15 篇；配置见 第 16 篇。 实施任何 setting 变更前，在 staging 用 system.parts / query_log 建立 24h 基线，变更后再对比——避免无证据调参。

深度 6

第 14 章与系列其它篇章的交叉：读路径见 第 05 篇；merge 见 第 06 篇；索引见 第 07 篇；副本见 第 08 篇；Distributed 见 第 09 篇；监控见 第 14 篇；故障见 第 15 篇；配置见 第 16 篇。 实施任何 setting 变更前，在 staging 用 system.parts / query_log 建立 24h 基线，变更后再对比——避免无证据调参。

深度 7

第 14 章与系列其它篇章的交叉：读路径见 第 05 篇；merge 见 第 06 篇；索引见 第 07 篇；副本见 第 08 篇；Distributed 见 第 09 篇；监控见 第 14 篇；故障见 第 15 篇；配置见 第 16 篇。 实施任何 setting 变更前，在 staging 用 system.parts / query_log 建立 24h 基线，变更后再对比——避免无证据调参。

深度 8

第 14 章与系列其它篇章的交叉：读路径见 第 05 篇；merge 见 第 06 篇；索引见 第 07 篇；副本见 第 08 篇；Distributed 见 第 09 篇；监控见 第 14 篇；故障见 第 15 篇；配置见 第 16 篇。 实施任何 setting 变更前，在 staging 用 system.parts / query_log 建立 24h 基线，变更后再对比——避免无证据调参。

深度 9

第 14 章与系列其它篇章的交叉：读路径见 第 05 篇；merge 见 第 06 篇；索引见 第 07 篇；副本见 第 08 篇；Distributed 见 第 09 篇；监控见 第 14 篇；故障见 第 15 篇；配置见 第 16 篇。 实施任何 setting 变更前，在 staging 用 system.parts / query_log 建立 24h 基线，变更后再对比——避免无证据调参。

深度 10

第 14 章与系列其它篇章的交叉：读路径见 第 05 篇；merge 见 第 06 篇；索引见 第 07 篇；副本见 第 08 篇；Distributed 见 第 09 篇；监控见 第 14 篇；故障见 第 15 篇；配置见 第 16 篇。 实施任何 setting 变更前，在 staging 用 system.parts / query_log 建立 24h 基线，变更后再对比——避免无证据调参。

深度 11

第 14 章与系列其它篇章的交叉：读路径见 第 05 篇；merge 见 第 06 篇；索引见 第 07 篇；副本见 第 08 篇；Distributed 见 第 09 篇；监控见 第 14 篇；故障见 第 15 篇；配置见 第 16 篇。 实施任何 setting 变更前，在 staging 用 system.parts / query_log 建立 24h 基线，变更后再对比——避免无证据调参。

深度 12

第 14 章与系列其它篇章的交叉：读路径见 第 05 篇；merge 见 第 06 篇；索引见 第 07 篇；副本见 第 08 篇；Distributed 见 第 09 篇；监控见 第 14 篇；故障见 第 15 篇；配置见 第 16 篇。 实施任何 setting 变更前，在 staging 用 system.parts / query_log 建立 24h 基线，变更后再对比——避免无证据调参。

深度 13

第 14 章与系列其它篇章的交叉：读路径见 第 05 篇；merge 见 第 06 篇；索引见 第 07 篇；副本见 第 08 篇；Distributed 见 第 09 篇；监控见 第 14 篇；故障见 第 15 篇；配置见 第 16 篇。 实施任何 setting 变更前，在 staging 用 system.parts / query_log 建立 24h 基线，变更后再对比——避免无证据调参。

深度 14

第 14 章与系列其它篇章的交叉：读路径见 第 05 篇；merge 见 第 06 篇；索引见 第 07 篇；副本见 第 08 篇；Distributed 见 第 09 篇；监控见 第 14 篇；故障见 第 15 篇；配置见 第 16 篇。 实施任何 setting 变更前，在 staging 用 system.parts / query_log 建立 24h 基线，变更后再对比——避免无证据调参。

深度 15

第 14 章与系列其它篇章的交叉：读路径见 第 05 篇；merge 见 第 06 篇；索引见 第 07 篇；副本见 第 08 篇；Distributed 见 第 09 篇；监控见 第 14 篇；故障见 第 15 篇；配置见 第 16 篇。 实施任何 setting 变更前，在 staging 用 system.parts / query_log 建立 24h 基线，变更后再对比——避免无证据调参。

深度 16

第 14 章与系列其它篇章的交叉：读路径见 第 05 篇；merge 见 第 06 篇；索引见 第 07 篇；副本见 第 08 篇；Distributed 见 第 09 篇；监控见 第 14 篇；故障见 第 15 篇；配置见 第 16 篇。 实施任何 setting 变更前，在 staging 用 system.parts / query_log 建立 24h 基线，变更后再对比——避免无证据调参。

深度 17

第 14 章与系列其它篇章的交叉：读路径见 第 05 篇；merge 见 第 06 篇；索引见 第 07 篇；副本见 第 08 篇；Distributed 见 第 09 篇；监控见 第 14 篇；故障见 第 15 篇；配置见 第 16 篇。 实施任何 setting 变更前，在 staging 用 system.parts / query_log 建立 24h 基线，变更后再对比——避免无证据调参。

深度 18

第 14 章与系列其它篇章的交叉：读路径见 第 05 篇；merge 见 第 06 篇；索引见 第 07 篇；副本见 第 08 篇；Distributed 见 第 09 篇；监控见 第 14 篇；故障见 第 15 篇；配置见 第 16 篇。 实施任何 setting 变更前，在 staging 用 system.parts / query_log 建立 24h 基线，变更后再对比——避免无证据调参。

深度 19

第 14 章与系列其它篇章的交叉：读路径见 第 05 篇；merge 见 第 06 篇；索引见 第 07 篇；副本见 第 08 篇；Distributed 见 第 09 篇；监控见 第 14 篇；故障见 第 15 篇；配置见 第 16 篇。 实施任何 setting 变更前，在 staging 用 system.parts / query_log 建立 24h 基线，变更后再对比——避免无证据调参。

深度 20

第 14 章与系列其它篇章的交叉：读路径见 第 05 篇；merge 见 第 06 篇；索引见 第 07 篇；副本见 第 08 篇；Distributed 见 第 09 篇；监控见 第 14 篇；故障见 第 15 篇；配置见 第 16 篇。 实施任何 setting 变更前，在 staging 用 system.parts / query_log 建立 24h 基线，变更后再对比——避免无证据调参。

深度 21

第 14 章与系列其它篇章的交叉：读路径见 第 05 篇；merge 见 第 06 篇；索引见 第 07 篇；副本见 第 08 篇；Distributed 见 第 09 篇；监控见 第 14 篇；故障见 第 15 篇；配置见 第 16 篇。 实施任何 setting 变更前，在 staging 用 system.parts / query_log 建立 24h 基线，变更后再对比——避免无证据调参。

深度 22

第 14 章与系列其它篇章的交叉：读路径见 第 05 篇；merge 见 第 06 篇；索引见 第 07 篇；副本见 第 08 篇；Distributed 见 第 09 篇；监控见 第 14 篇；故障见 第 15 篇；配置见 第 16 篇。 实施任何 setting 变更前，在 staging 用 system.parts / query_log 建立 24h 基线，变更后再对比——避免无证据调参。

深度 23

第 14 章与系列其它篇章的交叉：读路径见 第 05 篇；merge 见 第 06 篇；索引见 第 07 篇；副本见 第 08 篇；Distributed 见 第 09 篇；监控见 第 14 篇；故障见 第 15 篇；配置见 第 16 篇。 实施任何 setting 变更前，在 staging 用 system.parts / query_log 建立 24h 基线，变更后再对比——避免无证据调参。

深度 24

第 14 章与系列其它篇章的交叉：读路径见 第 05 篇；merge 见 第 06 篇；索引见 第 07 篇；副本见 第 08 篇；Distributed 见 第 09 篇；监控见 第 14 篇；故障见 第 15 篇；配置见 第 16 篇。 实施任何 setting 变更前，在 staging 用 system.parts / query_log 建立 24h 基线，变更后再对比——避免无证据调参。

附录 · 工程深化索引

深化 1：system.parts 列含义

flowchart LR
  Q[查询/写入] --> P[parts 状态]
  P --> M[merge 后台]
  M --> MON[system.merges]
  MON --> CFG[配置调优]

深化 2：active vs outdated

flowchart LR
  Q[查询/写入] --> P[parts 状态]
  P --> M[merge 后台]
  M --> MON[system.merges]
  MON --> CFG[配置调优]

深化 3：system.merges 进度

flowchart LR
  Q[查询/写入] --> P[parts 状态]
  P --> M[merge 后台]
  M --> MON[system.merges]
  MON --> CFG[配置调优]

深化 4：system.replication_queue

flowchart LR
  Q[查询/写入] --> P[parts 状态]
  P --> M[merge 后台]
  M --> MON[system.merges]
  MON --> CFG[配置调优]

深化 5：system.mutations

flowchart LR
  Q[查询/写入] --> P[parts 状态]
  P --> M[merge 后台]
  M --> MON[system.merges]
  MON --> CFG[配置调优]

深化 6：system.query_log

flowchart LR
  Q[查询/写入] --> P[parts 状态]
  P --> M[merge 后台]
  M --> MON[system.merges]
  MON --> CFG[配置调优]

深化 7：system.metrics 内存

flowchart LR
  Q[查询/写入] --> P[parts 状态]
  P --> M[merge 后台]
  M --> MON[system.merges]
  MON --> CFG[配置调优]

深化 8：system.asynchronous_metrics

flowchart LR
  Q[查询/写入] --> P[parts 状态]
  P --> M[merge 后台]
  M --> MON[system.merges]
  MON --> CFG[配置调优]

深化 9：system.events 计数

flowchart LR
  Q[查询/写入] --> P[parts 状态]
  P --> M[merge 后台]
  M --> MON[system.merges]
  MON --> CFG[配置调优]

深化 10：ProfileEvents 解读

flowchart LR
  Q[查询/写入] --> P[parts 状态]
  P --> M[merge 后台]
  M --> MON[system.merges]
  MON --> CFG[配置调优]

深化 11：max_memory_usage 跟踪

flowchart LR
  Q[查询/写入] --> P[parts 状态]
  P --> M[merge 后台]
  M --> MON[system.merges]
  MON --> CFG[配置调优]

深化 12：merge 延迟 SLA

flowchart LR
  Q[查询/写入] --> P[parts 状态]
  P --> M[merge 后台]
  M --> MON[system.merges]
  MON --> CFG[配置调优]

深化 13：副本 lag 告警

flowchart LR
  Q[查询/写入] --> P[parts 状态]
  P --> M[merge 后台]
  M --> MON[system.merges]
  MON --> CFG[配置调优]

深化 14：parts 数阈值

flowchart LR
  Q[查询/写入] --> P[parts 状态]
  P --> M[merge 后台]
  M --> MON[system.merges]
  MON --> CFG[配置调优]

深化 15：insert 延迟与 delay

flowchart LR
  Q[查询/写入] --> P[parts 状态]
  P --> M[merge 后台]
  M --> MON[system.merges]
  MON --> CFG[配置调优]

深化 16：磁盘剩余预警

flowchart LR
  Q[查询/写入] --> P[parts 状态]
  P --> M[merge 后台]
  M --> MON[system.merges]
  MON --> CFG[配置调优]

深化 17：ZooKeeper/Keeper 会话

flowchart LR
  Q[查询/写入] --> P[parts 状态]
  P --> M[merge 后台]
  M --> MON[system.merges]
  MON --> CFG[配置调优]

深化 18：分布式查询慢

flowchart LR
  Q[查询/写入] --> P[parts 状态]
  P --> M[merge 后台]
  M --> MON[system.merges]
  MON --> CFG[配置调优]

深化 19：mutation 堆积

flowchart LR
  Q[查询/写入] --> P[parts 状态]
  P --> M[merge 后台]
  M --> MON[system.merges]
  MON --> CFG[配置调优]

深化 20：Prometheus exporter

flowchart LR
  Q[查询/写入] --> P[parts 状态]
  P --> M[merge 后台]
  M --> MON[system.merges]
  MON --> CFG[配置调优]

深化 21：Grafana 面板模板

flowchart LR
  Q[查询/写入] --> P[parts 状态]
  P --> M[merge 后台]
  M --> MON[system.merges]
  MON --> CFG[配置调优]

深化 22：on-call runbook

flowchart LR
  Q[查询/写入] --> P[parts 状态]
  P --> M[merge 后台]
  M --> MON[system.merges]
  MON --> CFG[配置调优]

深化 23：基线对比方法

flowchart LR
  Q[查询/写入] --> P[parts 状态]
  P --> M[merge 后台]
  M --> MON[system.merges]
  MON --> CFG[配置调优]

深化 24：24h 滚动窗口

flowchart LR
  Q[查询/写入] --> P[parts 状态]
  P --> M[merge 后台]
  M --> MON[system.merges]
  MON --> CFG[配置调优]

深化 25：变更前后对照

flowchart LR
  Q[查询/写入] --> P[parts 状态]
  P --> M[merge 后台]
  M --> MON[system.merges]
  MON --> CFG[配置调优]

深化 26：system.parts 列含义

flowchart LR
  Q[查询/写入] --> P[parts 状态]
  P --> M[merge 后台]
  M --> MON[system.merges]
  MON --> CFG[配置调优]

深化 27：active vs outdated

flowchart LR
  Q[查询/写入] --> P[parts 状态]
  P --> M[merge 后台]
  M --> MON[system.merges]
  MON --> CFG[配置调优]

深化 28：system.merges 进度

flowchart LR
  Q[查询/写入] --> P[parts 状态]
  P --> M[merge 后台]
  M --> MON[system.merges]
  MON --> CFG[配置调优]

上一篇：选型对照

下一篇：经典故障模式

参考资料

1. ClickHouse Documentation, System tables, 24.x
2. ClickHouse Documentation, Monitoring
3. Altinity Knowledge Base — 运维查询（B 级，版本标注）