altinity-expert-clickhouse-replication

レプリケーションと Keeper の健全性

system.zookeeper_connection、system.replicas、system.replication_queue、system.replicated_fetches、system.events、system.text_log を使って、「レプリカは接続され、同期され、キューを処理できているか」に答えます。 接続モード、クラスター、時間範囲がまだ確定していない場合は、最初に altinity-expert-clickhouse-connection を実行してください。

クエリパック

• triage.sql — 2 つのチェック：ホストごとの Keeper/ZooKeeper セッション状態（replication-triage-01、@requires keeper）と、system.replicas による評価付きレプリケーション概要（replication-triage-02）。ここから始めてください。
• queue.sql — 2 つのチェック：テーブルとホストごとの評価付きキューサイズ（replication-queue-01）と、例外または延期理由を含む個別のキュータスク（replication-queue-02）。
• fetches.sql — 2 つのチェック：経過時間と進捗を含む実行中のフェッチ（replication-fetches-01）と、最近の DownloadPart アクティビティ（replication-fetches-02、system.part_log が必要です）。
• keeper.sql — 2 つのチェック：ZooKeeperTransactions に対する ZooKeeperWaitMicroseconds から算出したホストごとの Keeper 平均ラウンドトリップ遅延（replication-keeper-01）と、過去 24 時間の Keeper エラーおよび警告（replication-keeper-02、system.text_log が必要です）。

クエリパックの実行方法

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 列は、その行の判定です。そのまま転記し、再評価しないでください。

解釈ルール

• 接続スキルの報告で has_keeper = 0 の場合、このスキル全体は適用されません。その旨を伝えて終了してください。Keeper がなければ、診断対象となるレプリケートテーブルはありません。
• is_readonly = 1 または is_session_expired = 1 は重大です。レプリカは Keeper セッションを失っており、書き込みを受け付けません。まず Keeper の接続状態を確認し、次にディスクの空き容量、その後にサーバーログを確認してください。
• active_replicas < total_replicas は、Keeper に登録されているレプリカが稼働していないことを意味します。見つからないホストを特定し、再起動、ネットワーク分断、またはサーバーの停止がないか確認してください。
• 遅延の評価は SQL の結果に基づきます。absolute_delay が 300 秒を超えるか、queue_size が 200 を超える場合は中程度です。3600 秒を超えるか、キューの件数が 1000 件を超える場合は重大です。両方の数値を併記してください。遅延がなくキューが大きい場合はレプリカが追いついている途中であり、キューが空なのに遅延が大きい場合は処理を受信していません。
• last_exception または postpone_reason が空でないキューエントリから、停止しているテーブルとタスクの種類を特定できます。振り分けには type を確認してください。GET_PART はフェッチ、MERGE_PARTS はマージ、MUTATE_PART はミューテーションを示します。
• num_tries または num_postponed が多く、last_exception_time が最近の場合、タスクはまだ再試行中です。同じ値でも例外時刻が古ければ、すでに復旧しています。
• 実行時間の長いフェッチが多数ある場合や、パーツログに DownloadPart エラーが繰り返し記録される場合、それ自体が遅延の原因であり、単なる症状ではありません。レプリケーション設定を変更する前に、ネットワークのスループットとソースレプリカを確認してください。
• replication-keeper-01 の avg_latency_us の上昇は、遅延や読み取り専用レプリカと相関します。すべてのホストで同時にレイテンシが高い場合は、Keeper の遅延を根本原因として扱ってください。1 台のホストだけが遅い場合は、ローカルの問題として扱ってください。
• Keeper のレイテンシはサーバー起動以降の累積カウンターから計算されるため、絶対的なしきい値ではなく、ホスト間で比較してください。

レポート形式

1. ヘッダー：接続モード、クラスターまたは「単一ノード」、ClickHouse のバージョン、時間範囲。
2. 調査結果：列 check、severity、object、evidence、recommendation の表。問題ごとに 1 行とし、重大度が高い順に並べます。Evidence には結果の行から数値を引用します。
3. 問題のないチェック：問題行がなかったチェック ID を 1 行で列挙します。
4. スキップしたチェックと失敗したチェック：ID と理由、または最初のエラー行を記載します。このセクションは必ず含めてください。
5. 次の手順：次に読み込むスキルと、直ちに行う対応。

次のスキル

• part_mutations_in_queue の値が高い、またはキュータスクが MUTATE_PART エラーで失敗する場合 → スキル altinity-expert-clickhouse-mutations を読み込みます
• merges_in_queue の値が高い、またはキュータスクが MERGE_PARTS エラーで失敗する場合 → スキル altinity-expert-clickhouse-merges を読み込みます
• 大量の DownloadPart の繰り返しやフェッチの失敗についてパーツ単位の履歴が必要な場合 → スキル altinity-expert-clickhouse-part-log を読み込みます
• Keeper のエラーについてサーバーログの全体的なコンテキストが必要な場合、または system.text_log がない場合 → スキル altinity-expert-clickhouse-logs を読み込みます
• ディスク容量不足が原因でレプリカが読み取り専用になる場合 → スキル altinity-expert-clickhouse-storage を読み込みます
• レプリケートテーブルへの挿入が失敗する、または停滞する場合 → スキル altinity-expert-clickhouse-ingestion を読み込みます