altinity-expert-clickhouse-kafka

Kafka 引擎健康状况

根据 system.kafka_consumers、system.metric_log、system.query_views_log 和 system.text_log，回答“Kafka 消费者是否在轮询、提交并跟上进度？是否有任何因素导致它们资源不足？”。如果尚未确定连接模式、集群和时间范围，请先运行 altinity-expert-clickhouse-connection。

查询包

• checks.sql — 7 项检查：按消费者检查消费健康状况（kafka-01）、每次提交的平均行数（kafka-02）、重新均衡与分配（kafka-03）、消费者数量与消息代理池大小的对比（kafka-04）、12 小时内的池利用率（kafka-05，需要 system.metric_log）、Kafka 表上的慢速物化视图（kafka-06，需要 system.query_views_log）、日志中的 Kafka 消息（kafka-07，需要 system.text_log）。
• advanced_checks.sql — 4 项检查：针对单个表的消费者异常深入排查（需要 {db} 和 {kafka_table}）、每个表的总滞后、每个分区的滞后、消息代理连接健康状况。最后三项会解析 rdkafka_stat。该文件还包含一个标记为 @skip-matrix 的三语句消费速度方案：它会创建临时表、暂停一段时间，然后比较快照，因此三条语句必须在同一个 clickhouse-client 会话中运行。此方案无法通过 MCP 运行，也无法作为单独的 --query 调用运行。
• troubleshooting.md — 常见 Kafka 错误和配置修复方法（ACL 错误、轮询间隔、死信队列、偏移量回退、并行消费调优）。
• references/rack-awareness.md — 跨 AZ 和 client.rack 调查；如果问题涉及 AWS MSK、KAFKA_CLIENT_RACK、跨 AZ 成本、VPC 端点或 Kafka 集群迁移，请加载此文件。
• reference.md — 背景信息（Kafka 引擎和 librdkafka 设置）；仅在需要解释建议时阅读。

如何运行查询包

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 列是该行的判定结果。照录即可；不要重新评级。

解读规则

• 当 last_exception_time >= last_poll_time 或 last_exception_time >= last_commit_time 时，表示消费者卡住了：它在持续失败，而非取得进展。否则，即使存在延迟，也应视为健康。
• exceptions 是一个由数组组成的元组，各数组的索引相互对应。exceptions.time[-1] 和 exceptions.text[-1] 是最近一次错误；引用这两项。
• kafka_consumers > mb_pool_size（kafka-04）表示线程资源耗尽：消费者在等待空闲线程。解决方法是提高 background_message_broker_schedule_pool_size（默认值为 16）。设置值应为所有 Kafka、RabbitMQ 和 NATS 消费者数量之和再加 25%。
• 物化视图的平均执行时长超过 30 秒（kafka-06），存在超过 max.poll.interval.ms 的风险；一旦超过，消费者就会被移出组。视图执行报错通常是重新平衡在批次执行过程中打断了处理，而不是独立的 Bug。
• Kafka 表上的视图处理缓慢，最常见的原因是多个 JSONExtract 调用反复解析同一个 JSON 数据块。解决方法是使用一次性解析的 JSONExtract(json, 'Tuple(...)')，再调用 tupleElement()；参见本目录中的 troubleshooting.md。
• 过去 12 小时的连接池利用率（kafka-05）：如果数值持续接近连接池大小，表示容量承压；如果峰值与延迟同时出现，表示暂时过载；如果数值始终为零，表示消费者根本没有运行，这与存在延迟是不同的问题。
• 除非在 Kafka 引擎配置中设置了 <statistics_interval_ms>，否则 rdkafka_stat 为空。如果它为空，应将三项延迟和 Broker 检查报告为因缺少前置条件而跳过，而不是标记为正常。
• 仅设置 client.rack 不会产生任何影响：Broker 必须运行 RackAwareReplicaSelector，而它并非默认配置。建议设置任何机架参数前，先核实 Broker 端的选择器配置。
• 在 librdkafka Broker 计数器中，tx 和 rx 表示请求数和响应数，而 txbytes 和 rxbytes 表示字节数。只有根据字节计数器才能判定各 Broker 的流量和跨可用区流量。

报告格式

1. 标题：连接模式、集群或“单节点”、ClickHouse 版本、时间范围。
2. 发现：包含 check、severity、object、evidence、recommendation 列的表格；每项发现占一行，按严重程度排列，Critical 在前。evidence 应引用结果行中的数值。
3. 正常检查：用一行列出没有问题行的检查 ID。
4. 已跳过和失败的检查：列出 ID 和原因或首条错误信息。不得省略此部分。
5. 后续步骤：列出接下来要加载的技能和立即采取的行动。

后续技能

• 物化视图插入是瓶颈，或插入延迟占主导 → 加载技能 altinity-expert-clickhouse-ingestion
• 目标表的合并内存占用较高，或存在 part 堆积 → 加载技能 altinity-expert-clickhouse-merges
• 视图查询本身很慢，与 Kafka 无关 → 加载技能 altinity-expert-clickhouse-reporting
• 目标表设计或视图链看起来不合理 → 加载技能 altinity-expert-clickhouse-schema
• Kafka 检查后跨可用区成本仍然较高，或流量使用 ClickHouse interserver 端口 → 加载技能 altinity-expert-clickhouse-replication
• 消息 Broker 连接池饱和，需要查看超过 12 小时的趋势 → 加载技能 altinity-expert-clickhouse-metrics