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 つのチェック：1 つのテーブルに対するコンシューマー例外の詳細調査（{db} と {kafka_table} が必要）、テーブルごとの合計ラグ、パーティションごとのラグ、ブローカー接続の健全性。最後の 3 つは rdkafka_stat を解析します。このファイルには @skip-matrix と記された、消費速度を調べる 3 ステートメントの手順も含まれています。この手順では一時テーブルを作成してからスリープし、その後スナップショットを比較するため、3 つのステートメントをすべて 1 つの 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. ステートメントは必ず 1 つずつ実行し、ファイル全体をまとめて実行しないでください。ステートメントは ; で終わり、-- @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 を超えて、コンシューマーがグループから除外されるおそれがあります。ビュー実行のエラーは通常、バッチ処理中にリバランスで中断されたことが原因であり、独立したバグではありません。
• Kafka テーブルのビューが遅くなる最も一般的な原因は、複数の JSONExtract 呼び出しで同じ JSON ブロブを再解析することです。JSONExtract(json, 'Tuple(...)') で一度に抽出し、tupleElement() を使う方法で対処できます。このディレクトリの troubleshooting.md を参照してください。
• 12 時間にわたるプール使用率（kafka-05）：プールサイズ近くで推移している場合は容量不足、ラグと同時に発生するスパイクは一時的な過負荷、ゼロのままの場合はコンシューマーがまったく実行されていないことを示します。これはラグとは別の所見です。
• Kafka エンジン設定で <statistics_interval_ms> が設定されていない場合、rdkafka_stat は空です。空の場合は、3 つのラグおよびブローカーのチェックを OK とせず、前提条件が不足しているためスキップしたと報告してください。
• client.rack を設定しただけでは何も変わりません。ブローカーで RackAwareReplicaSelector を実行する必要がありますが、これはデフォルトではありません。ラック設定を推奨する前に、ブローカー側のセレクターを確認してください。
• librdkafka のブローカーカウンターでは、tx と rx はリクエスト数とレスポンス数、txbytes と rxbytes はバイト数です。ブローカーごとおよび AZ 間のトラフィックは、バイトカウンターだけを使って特定してください。

レポート形式

1. ヘッダー：接続モード、クラスターまたは「単一ノード」、ClickHouse のバージョン、時間範囲。
2. 所見：列が check、severity、object、evidence、recommendation の表。所見ごとに 1 行とし、Critical を先頭にします。Evidence には結果行の数値を引用してください。
3. OK のチェック：問題のある行がなかったチェック ID を 1 行で列挙します。
4. スキップおよび失敗したチェック：ID と理由、またはエラーの最初の行。必ずこのセクションを含めてください。
5. 次の手順：次に読み込むスキルと、すぐに実行するアクション。

次のスキル

• マテリアライズドビューへの挿入がボトルネック、または挿入レイテンシーが支配的 → スキル altinity-expert-clickhouse-ingestion を読み込む
• 宛先テーブルでマージ時のメモリ使用量が多い、またはパーツが滞留している → スキル altinity-expert-clickhouse-merges を読み込む
• Kafka とは無関係にビューのクエリ自体が遅い → スキル altinity-expert-clickhouse-reporting を読み込む
• 宛先テーブルの設計またはビューの連鎖に問題がある → スキル altinity-expert-clickhouse-schema を読み込む
• Kafka のチェック後も AZ 間コストが残る、またはトラフィックが ClickHouse のインターサーバーポートを使用している → スキル altinity-expert-clickhouse-replication を読み込む
• メッセージブローカープールの飽和について 12 時間を超える傾向を確認する必要がある → スキル altinity-expert-clickhouse-metrics を読み込む