altinity-expert-clickhouse-ingestion

INSERT と取り込みのパフォーマンス

system.query_log、system.part_log、system.query_views_log、system.kafka_consumers、system.processes、system.text_logを使って、「INSERT が遅い、失敗する、またはパーツが多く作成されすぎるのはなぜか」に答えます。 接続モード、クラスター、時間範囲がまだ確定していない場合は、最初にaltinity-expert-clickhouse-connectionを実行してください。

クエリパック

• checks.sql — 14 個のチェック：Kafka コンシューマーの健全性とスケジューリング容量、実行中および最近の INSERT アクティビティ、テーブルごとのパーツ作成率、INSERT とマージのバランス、遅い INSERT、INSERT に対するマテリアライズドビューのオーバーヘッド、失敗した INSERT、バッチサイズの分布、Kafka エンジンの取り込み、ログ内の Kafka メッセージ、Buffer テーブルのフラッシュパターン、現在の INSERT 関連設定。そのうち 2 つにはsystem.part_log、1 つにはsystem.query_views_log、1 つには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列がその行の判定です。値をそのままコピーし、再評価しないでください。

詳細調査用ステートメント

遅い INSERT のquery_idがわかっている場合は、マテリアライズドビューごとに所要時間を分解します。check ingestion-07 または ingestion-08 から取得した ID で{query_id}を置き換えてください。

SELECT
    view_name,
    view_duration_ms,
    read_rows,
    written_rows,
    status,
    exception
FROM system.query_views_log
WHERE query_id = '{query_id}'
ORDER BY view_duration_ms DESC;

解釈ルール

• INSERT あたりの平均written_rowsが 1000 未満の場合は、マイクロバッチ処理です。クライアントが行ごとにパーツ作成コストを負担しています。1 回の INSERT で 10k～1M 行をまとめるか、クライアント側でバッチ化できない場合はasync_insertを有効にすることを推奨してください。check ingestion-10 はseverityではなくbatch_statusを返します。「Seriously under-batched」は Major、「Could improve」は Moderate として扱ってください。
• 同じ時間範囲内でNewPartイベントが多く、MergePartsイベントが少ない場合（ingestion-06）、マージが取り込みに追いついていないことを意味し、INSERT が遅すぎるという意味ではありません。INSERT 側は正常であり、指摘すべきなのはマージ側です。
• system.query_views_logでビューの所要時間が INSERT の所要時間の大半を占めている場合（ingestion-08）、修正すべきなのは INSERT ではなくマテリアライズドビューのクエリです。最も遅いビューと、INSERT 時間に占める割合を示してください。
• Buffer テーブルには固有のフラッシュ遅延があります。行が表示されるのはフラッシュ後であり、大きな Buffer はメモリー使用量を増やし、再起動時のデータ損失の可能性も高めます。ingestion-13 のフラッシュパターンから、query_logだけではわからない INSERT から表示までの遅延を説明できます。
• @requires table:system.part_logと記されたチェックは、part_logが無効な場合にスキップされます。パーツ作成が正常だと結論付けるのではなく、その旨を明示してください。part_logがなければ、パーツ作成率と INSERT／マージのバランスは不明です。
• TOO_MANY_PARTS または「Too many parts」というテキストを含む失敗した INSERT（ingestion-09）は、マージのバックログを示すものであり、INSERT の不具合ではありません。INSERT での MEMORY_LIMIT_EXCEEDED は通常、マテリアライズドビューか、単一の非常に大きなバッチが原因です。
• Kafka のチェック（ingestion-01、-02、-11、-12）では、ここでは概要のみを確認します。ポーリングまたはコミットの経過時間の増加、あるいは空でない例外配列が見られた場合は、このスキルで詳しく調査するのではなく、Kafka スキルに移る判断基準となります。

レポート形式

1. ヘッダー：接続モード、クラスターまたは「単一ノード」、ClickHouse のバージョン、対象期間。
2. 検出事項：check、severity、object、evidence、recommendation の列を含む表。検出事項ごとに 1 行とし、Critical を先頭にします。Evidence には結果行の数値を引用します。
3. 問題のないチェック：問題のある行が返されなかったチェック ID を 1 行で列挙します。
4. スキップされたチェックと失敗したチェック：ID と理由、または最初のエラー行を記載します。このセクションは省略しないでください。
5. 次のステップ：次に読み込むスキルと、すぐに実施する対応。

次のスキル

• Kafka のコンシューマーラグ、コンシューマーの例外、リバランス、またはプールサイズを超えるコンシューマー → スキル altinity-expert-clickhouse-kafka を読み込みます
• パーツの作成がマージを上回る、TOO_MANY_PARTS、またはパーティションあたりのパーツ数が多い → スキル altinity-expert-clickhouse-merges を読み込みます
• マテリアライズドビューのクエリ自体が遅い、または読み取り量が多い → スキル altinity-expert-clickhouse-reporting を読み込みます
• MEMORY_LIMIT_EXCEEDED による挿入の失敗、またはピークメモリの使用量が多い → スキル altinity-expert-clickhouse-memory を読み込みます
• パーティションキーが細かすぎる、テーブルの幅が広い、またはマテリアライズドビューの設計に問題がある → スキル altinity-expert-clickhouse-schema を読み込みます
• ディスクまたは書き込みスループットが原因の挿入レイテンシ → スキル altinity-expert-clickhouse-storage を読み込みます
• レプリケートテーブルで挿入がブロックされる、または insert_quorum 待ちが発生する → スキル altinity-expert-clickhouse-replication を読み込みます