altinity-expert-clickhouse-part-log

パーツライフサイクル診断

system.part_log から、パーツで何が起きているか、どのくらいの速さで進んでいるか、障害が発生しているかを、レート（1 分あたりのイベント数）、量（行数とバイト数）、エラーに基づいて回答します。 接続モード、クラスター、時間範囲がまだ確定していない場合は、最初に 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 が有効になっていないことを報告してください。part_log がなければ、パーツのライフサイクルに関する結論を導き出せません。
• reference.md — 背景情報（イベントタイプ、パーツのライフサイクル、設定）。推奨事項の説明が必要な場合にのみ読み取ってください。

クエリパックの実行方法

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 カラムはその行の判定です。その値をそのまま使用し、再評価しないでください。

解釈ルール

• このパックはseverityを算出しません。以下のルールに従って自分で検出結果を評価し、どのルールを適用したかを明記してください。
• まずpart-log-01を確認します。最も古いイベントが指定した時間範囲より新しい場合、part_logが最近有効化されたか、TTLが短いことを意味します。その旨を記載し、以下のすべてのレートがより短い時間範囲を対象としているものとして扱ってください。
• マイクロバッチ処理：1つのテーブルで1分あたりのNewPartイベントが60件を超える（1秒あたり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以上として扱ってください。

詳細確認用ステートメント

前のチェックで指定された1つのテーブルについて、イベントを完全に内訳表示します。

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;

マイクロバッチ処理を確認するため、1つのテーブルの挿入バッチサイズの分布を表示します。

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の列を含むテーブル。検出結果ごとに1行とし、Criticalを先頭にします。Evidenceには結果行の数値を引用します。
3. 問題のないチェック：問題行が返されなかったチェックIDを1行で列挙します。
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を読み込みます