altinity-expert-clickhouse-overview

健康概览与路由

回答“此服务是否健康，以及哪个方面需要进一步检查？”，依据 system.metrics、system.asynchronous_metrics、system.parts、system.disks、system.tables、system.query_log、system.errors 和 system.text_log。此技能专为单主机设计；副本间的差异应交由专门技能处理。 如果尚未确定连接模式、集群和时间窗口，请先运行 altinity-expert-clickhouse-connection。

查询包

• checks.sql — 14 项检查：对象数量、内存与 RAM 对比、主键和字典的 RAM 占用、磁盘使用情况、复制摘要、系统日志 TTL 和大小、每小时查询错误率、part_log 错误、system.errors 错误代码排行、分离的分区、text_log 中的近期警告、后台线程池利用率。
• metrics.sql — 13 项警报检查（ID 为 A3.0.x），仅在超过阈值时返回行；结果为空表示正常。检查 A3.0.4 和 A3.0.5 各有两个特定版本的备选项（@requires version<26.8 / version>=26.8）：运行与服务版本匹配的那一个。
• ddl_queue.sql — 1 项 ON CLUSTER DDL 队列检查；需要 keeper。

如何运行查询包

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 列是该行的判定结果。照原样复制；不要重新评级。

解读规则

• metrics.sql 中未返回行的检查表示正常；在正常项一行中列出这些 ID。Minor 行仅供参考，不属于问题。
• 没有 TTL 的系统日志表（overview-07）属于问题；在其旁边引用 overview-08 中的大小。只有当最大的未设置 TTL 的表超过数 GiB，或磁盘使用率超过 70％ 时，才转交日志技能。
• 错误率（overview-09）：说明故障是持续发生还是突然激增，并列出 overview-11 中排名靠前的错误代码。忽略由本次诊断会话自身引发的错误代码（UNKNOWN_IDENTIFIER、UNKNOWN_TABLE、SYNTAX_ERROR）。
• 对象数量（overview-01）和分区数量是整个服务范围的数据。如果最大的分区数量或大小来自 system.* 表，应明确说明，而不是归咎于用户表。
• 原因是 broken*、unexpected*、ignored* 的分离分区（overview-12）表明存在复制或磁盘问题；clone 和 covered-by-broken 通常可以安全删除。
• 如果 MergesAndMutations 的后台线程池利用率（overview-14）超过 90％，说明合并受容量限制，不一定是数据量所致。
• 如果 has_keeper = 0，应将复制和 DDL 队列检查标记为不适用，而非正常。

报告格式

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

后续技能

• 只读副本、副本延迟、复制队列增长、text_log 中的 Keeper 错误 → 加载技能 altinity-expert-clickhouse-replication
• 内存使用量超过 RAM 的 80%、主键或字典占用大量 RAM、出现 MEMORY_LIMIT_EXCEEDED 错误 → 加载技能 altinity-expert-clickhouse-memory
• 磁盘使用量超过 80% 或系统日志表过大 → 加载技能 altinity-expert-clickhouse-storage（磁盘）或 altinity-expert-clickhouse-logs（日志 TTL）
• 每个分区包含大量 part、出现 TOO_MANY_PARTS、MergesAndMutations 池已饱和、part_log 中出现合并错误 → 加载技能 altinity-expert-clickhouse-merges
• 查询错误率高或 SELECT 执行缓慢 → 加载技能 altinity-expert-clickhouse-reporting
• INSERT 执行缓慢或失败、NewPart 速率高 → 加载技能 altinity-expert-clickhouse-ingestion
• Kafka 消费者数量超过池大小，或 text_log 中出现 Kafka 警告 → 加载技能 altinity-expert-clickhouse-kafka
• 字典加载失败或字典占用大量 RAM → 加载技能 altinity-expert-clickhouse-dictionaries
• part_log 错误中出现卡住或失败的变更 → 加载技能 altinity-expert-clickhouse-mutations
• system.errors 中出现 ACCESS_DENIED 或身份验证错误 → 加载技能 altinity-expert-clickhouse-grants
• 随时间推移出现负载、连接或连接池饱和 → 加载技能 altinity-expert-clickhouse-metrics
• 怀疑存在架构反模式（分区、ORDER BY、物化视图）→ 加载技能 altinity-expert-clickhouse-schema