altinity-expert-clickhouse-metrics

实时指标与饱和度

从 system.metrics、system.events、system.asynchronous_metrics、system.metric_log 和 system.asynchronous_metric_log 获取“当前哪个资源已饱和？一小时前是否也已饱和？”的答案。 如果尚未确定连接模式、集群和时间范围，请先运行 altinity-expert-clickhouse-connection。

查询包

• checks.sql — 14 条语句，包含 12 项检查（ID 为 metrics-01 至 metrics-12）：内存、运行中的查询和连接的饱和度摘要；负载平均值与 CPU 核数的对比；复制指标；每个分区的最大分区片段数与插入阈值的对比；后台线程池利用率；自启动以来的失败和限流计数器；最近 6 小时的内存和负载平均值；最近一小时的查询速率；块设备队列深度；运行时长和版本；Prometheus 端点配置。检查 metrics-02 和 metrics-10 各有两个版本，分别带有互补的 @requires version<26.8 和 @requires version>=26.8 标头：只运行与服务器版本匹配的版本。检查 metrics-07 和 metrics-08 需要 system.asynchronous_metric_log，检查 metrics-09 需要 system.metric_log。
• reference.md — 背景信息（设置、容量规划、反模式）；仅在需要解释建议时阅读。

如何运行查询包

1. 从此技能的目录中读取每个包文件（技能加载器会打印目录路径）。
2. 一次运行一条语句，绝不要运行整个文件。语句以 ; 结尾，并以 -- @check <id> <title> 标头开头；保留 ID 并与结果对应。
3. 遵循 -- @requires：当指定表不存在、需要 keeper 但服务器没有 Keeper/ZooKeeper，或版本条件不满足时，跳过该语句。列出跳过的 ID 及原因。
4. 如果存在集群宏，按原样保留 {cluster}；否则应用连接技能的改写规则。其他任何 {placeholder} 都是模板变量：先替换为实际值，否则跳过该语句。
5. 出错时，记录检查 ID 和错误的第一行，然后继续。仅当出现 UNKNOWN_IDENTIFIER 时，运行 DESCRIBE TABLE system.<table> 并移除缺失的列。
6. severity 列是该行的判定结果。照原样复制；不要重新评定。

解读规则

• 饱和百分比及其严重程度由 SQL 计算。请照原样复制。以下规则说明资源饱和意味着什么。
• 15 分钟内持续高于 CPU 核心数的平均负载意味着主机受 CPU 限制，而不只是繁忙。1 分钟负载高但 15 分钟负载正常，说明出现了尖峰，通常无需处理。
• 运行中的查询数接近 max_concurrent_queries，意味着新查询将排队，随后因 TOO_MANY_SIMULTANEOUS_QUERIES 而失败。先修复慢查询；提高此限制只会将拒绝转换为内存压力。
• 连接数接近 max_connections 时，客户端会出现连接超时，而不是 ClickHouse 错误。提高限制前，请先检查连接池是否泄漏。
• 块设备的进行中操作数超过 128，意味着磁盘队列已饱和，每次读取都必须排队等待。超过 200 时，无论 ClickHouse 正在做什么，该设备都是瓶颈。
• 每个分区的最大 part 数超过 parts_to_delay_insert 时，插入已经变慢；超过 parts_to_throw_insert 时，插入会因 TOO_MANY_PARTS 而失败。这两种情况都是合并问题，而不是插入问题。
• metrics-06 中的 RejectedInserts 或 DelayedInserts 非零，证实 part 数量导致了插入限流。
• ZooKeeperHardwareExceptions 非零意味着 Keeper 会话丢失，这会阻塞复制和 ON CLUSTER DDL。ZooKeeperUserExceptions 大多无害（节点已存在、节点缺失）。
• metrics-06 计数器是自服务器启动以来的累计值，因此应结合 metrics-11 中的运行时间一起查看。运行数月的主机上较大的计数器可能是历史遗留值。
• 运行时间不足一小时意味着服务器在观测窗口内重启过。信任本报告中的任何计数器或速率前，请先检查 system.crash_log 和 system.text_log，查明原因。
• metrics-12 报告没有 Prometheus 端点，这是监控缺口，而非服务器故障。应报告为 Minor。

深入查询语句

当检查指向工具包未涵盖的内容时，查找名称匹配某个模式的所有指标、异步指标和事件：

SELECT 'metrics' AS source, metric AS name, toString(value) AS value, description FROM system.metrics WHERE metric ILIKE '%{pattern}%' UNION ALL SELECT 'asynchronous_metrics', metric, toString(value), description FROM system.asynchronous_metrics WHERE metric ILIKE '%{pattern}%' UNION ALL SELECT 'events', event, toString(value), description FROM system.events WHERE event ILIKE '%{pattern}%' ORDER BY source, name;

以 15 分钟为间隔，绘制过去 6 小时内某个异步指标的图表：

SELECT toStartOfFifteenMinutes(event_time) AS ts, round(avg(value), 2) AS avg_value, round(max(value), 2) AS max_value FROM system.asynchronous_metric_log WHERE event_time > now() - INTERVAL 6 HOUR AND metric = '{metric}' GROUP BY ts ORDER BY ts;

报告格式

1. 标头：连接模式、集群或“单节点”、ClickHouse 版本、时间窗口。
2. 发现：包含 check、severity、object、evidence、recommendation 列的表格；每项发现占一行，按 Critical 优先排序。证据应引用结果行中的数值。
3. 正常检查：用一行列出未返回问题行的检查 ID。
4. 已跳过和失败的检查：列出 ID 和原因或首行错误。绝不省略此部分。
5. 后续步骤：接下来要加载的技能和立即采取的措施。

后续技能

• 内存饱和，或计数器中出现 MEMORY_LIMIT_EXCEEDED → 加载技能 altinity-expert-clickhouse-memory
• 只读副本、副本延迟、队列增长或 Keeper 硬件异常 → 加载技能 altinity-expert-clickhouse-replication
• 每个分区的 part 数接近延迟或抛出阈值，或 MergesAndMutations 池饱和 → 加载技能 altinity-expert-clickhouse-merges
• 插入被拒绝或延迟 → 加载技能 altinity-expert-clickhouse-ingestion
• 平均负载高，或许多运行中的查询可追溯到特定查询 → 加载技能 altinity-expert-clickhouse-reporting
• 磁盘队列饱和或设备速度慢 → 加载技能 altinity-expert-clickhouse-storage
• 需要解释近期重启或崩溃 → 加载技能 altinity-expert-clickhouse-logs
• 根据计数器排查 part 创建、合并和移除速率 → 加载技能 altinity-expert-clickhouse-part-log