altinity-expert-clickhouse-part-log

部件生命周期诊断

通过 system.part_log 回答“部件发生了什么、速度如何，以及是否有故障？”，从速率（每分钟事件数）、总量（行数和字节数）和错误情况进行分析。 如果尚未确定连接模式、集群和时间窗口，请先运行 altinity-expert-clickhouse-connection。

查询包

• checks.sql — 11 项检查：part_log 覆盖情况合理性检查、按分钟统计部件活动时间线、按表统计 NewPart 速率、新部件与合并的合并平衡情况、合并持续时间分布、MutatePart 速率、待处理变更积压、DownloadPart 激增、RemovePart 激增、MovePart 激增，以及错误非零的 part_log 记录。其中 11 项有 10 项需要 system.part_log；只有 part-log-07 会读取 system.mutations。如果 system.part_log 不存在，请跳过其他所有检查，并报告 part_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 列是该行的判定结果。照抄该值；不要重新评定。

解读规则

• 此数据包不会计算 severity。请根据以下规则自行判定问题等级，并说明应用了哪条规则。
• 优先检查 part-log-01：如果最早的事件晚于请求的时间窗口，说明 part_log 最近才启用，或其 TTL 较短。请说明这一点，并将以下所有速率视为覆盖较短时间窗口。
• 微批处理：单个表每分钟超过 60 个 NewPart 事件（超过每秒 1 个分区），或平均每个分区小于 1 MB 或小于 10,000 行，说明插入过于零散。每个分区都会产生合并、标记和文件句柄开销。
• NewPart 速率远高于 MergeParts 速率（part-log-04），意味着分区数量正在增加，合并跟不上。无论当前分区数量看起来如何，最终都会导致 TOO_MANY_PARTS。
• 合并耗时（part-log-05）：p95 远高于 p50，或 p95 在时间窗口内持续上升，意味着合并压力。根据合并字节数区分原因：p95 较高且合并字节数较大，属于正常的大型合并任务；p95 较高但合并字节数较小，说明磁盘或合并池是瓶颈。
• MutatePart 风暴（part-log-06）意味着 ALTER UPDATE 或 ALTER DELETE 正在重写许多分区。每次变更都会重写整个分区，因此频繁执行影响行数少的变更，所需 IO 远超其触及行数所应有的开销。反复发生的变更通常表明设计应改用 ReplacingMergeTree、CollapsingMergeTree 或轻量级删除。
• DownloadPart 激增（part-log-08）意味着副本获取了分区，而非在本地合并：可能是副本重启、追赶延迟、网络或磁盘故障，或分区丢失后重新获取。在健康副本上持续出现下载，通常指向复制问题，而非数据写入问题。
• RemovePart 激增（part-log-09）可能由 TTL 清理、DROP 或 DETACH PARTITION、变更清理，或合并后正常移除源分区导致。在判定为数据丢失之前，请核对同一分钟内的 MergeParts。
• MovePart 激增（part-log-10）意味着存储策略迁移、分层存储或手动移动。意外移动通常表示 TTL TO VOLUME 或 TTL TO DISK 规则已触发。
• part-log-11 中的行始终属于问题：非零 error 表示合并、变更或获取失败。请报告异常文本和次数；如果同一张表反复出现错误，应定为 Major 或更严重级别。

深入分析语句

针对前序检查中指定的单张表查看完整事件明细：

SELECT event_type, count() AS events, sum(rows) AS rows_sum, formatReadableSize(sum(size_in_bytes)) AS bytes_sum, round(avg(duration_ms)) AS avg_ms, countIf(error != 0) AS errors FROM system.part_log WHERE event_time > now() - INTERVAL 24 HOUR AND database = '{database}' AND table = '{table}' GROUP BY event_type ORDER BY events DESC;

查看单张表的插入批次大小分布，以确认是否存在微批处理：

SELECT count() AS new_parts, quantiles(0.5, 0.9, 0.99)(rows) AS rows_p50_p90_p99, quantiles(0.5, 0.9, 0.99)(size_in_bytes) AS bytes_p50_p90_p99 FROM system.part_log WHERE event_time > now() - INTERVAL 1 HOUR AND event_type = 'NewPart' AND database = '{database}' AND table = '{table}';

报告格式

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

后续技能

• NewPart 速率高或插入属于微批处理 → 加载技能 altinity-expert-clickhouse-ingestion
• 合并跟不上、合并缓慢或合并出错 → 加载技能 altinity-expert-clickhouse-merges
• MutatePart 速率高或变更积压未清 → 加载技能 altinity-expert-clickhouse-mutations
• DownloadPart 事件很多或获取出错 → 加载技能 altinity-expert-clickhouse-replication
• 合并缓慢且吞吐量低，或在不同卷之间出现 MovePart 活动 → 加载技能 altinity-expert-clickhouse-storage
• 表设计容易产生微小分区或频繁变更 → 加载技能 altinity-expert-clickhouse-schema
• part_log 缺失或保留时间过短 → 加载技能 altinity-expert-clickhouse-logs