altinity-expert-clickhouse-storage

ストレージとディスク使用量の分析

system.disks、system.parts、system.columns、system.detached_parts、system.storage_policies、system.asynchronous_metrics、system.query_log、system.part_log を使って、「ディスク容量はどこで使われているか、データは適切に圧縮されているか、ディスクは処理に追いついているか」に答えます。接続モード、クラスター、時間範囲がまだ確定していない場合は、最初に altinity-expert-clickhouse-connection を実行してください。

クエリパック

• checks.sql — 19 件のチェック：重大度付きのディスク空き容量、データベース別およびテーブル別のサイズ、パス別の使用量、全体およびテーブル別の圧縮率、圧縮率が 2 倍未満のカラム、パーツサイズの分布、小さなパーツの検出、Wide と Compact のパーツ構成、ディスク I/O メトリクス、クエリログから取得した最近の I/O、I/O 負荷が最も高いクエリ、システムログのディスク使用量、理由別のデタッチ済みパーツ、ストレージポリシーとそれらを使用するテーブル、直近 1 時間で増加したデータ、ディスク速度の代替指標としてのマージスループット。チェック storage-19 には system.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 カラムはその行の判定です。そのまま転記し、評価し直さないでください。

解釈ルール

• storage-01 は空き容量を評価します。使用率が 80 パーセントを超えると Moderate、85 パーセントを超えると Major、90 パーセントを超えると Critical です。Major は当日中に対応してください。MergeTree では、実行する最大のマージと同量以上の空き容量が必要なため、ディスク使用率が 90 パーセントになると、挿入を受け付けなくなるずっと前にマージが停止します。
• 圧縮率が 2 未満（storage-06、storage-07）の場合、データが圧縮できないのではなく、カラム型またはコーデックに問題があります。明示的なコーデックを追加してください。一般的なデータには ZSTD、連続する整数には Delta, ZSTD、タイムスタンプには DoubleDelta, ZSTD、繰り返しの多い文字列には LowCardinality(String) を使用します。圧縮率が 2～5 は正常で、5 を超えると良好です。
• storage-09 が返すのは、パーツの半分を超える数が 10 MB 未満で、かつパーツ数が 10 を超えるテーブルのみです。これはマージの滞留か、マイクロバッチ挿入のいずれかであり、それだけでストレージの問題とはいえません。
• storage-10 の Wide と Compact：min_bytes_for_wide_part（デフォルトでは 10 MiB）より小さいパーツは Compact 形式で保存され、すべてのカラムが 1 つのファイルに格納されます。小さな Wide パーツが多数ある場合、しきい値が引き下げられ、各パーツでカラムごとに 1 組のファイルが必要になっています。大きなテーブル全体が Compact 形式で保存されている場合、しきい値が引き上げられ、カラム単位の読み取り粒度が失われています。
• storage-15 のデタッチされたパーツ：理由が broken、unexpected、noquorum、ignored で始まる場合は、破損、操作の失敗、またはレプリケーションの問題を示しているため、削除前に調査が必要です。clone と covered-by-broken は残存物なので、ディスク容量が必要になった時点で安全に削除できます。
• storage-18 は直近 1 時間に増加したものを一覧表示します。storage-03 と比較してください。全体では小さいものの、この一覧の上位にあるテーブルが、ディスクをいっぱいにするテーブルです。
• storage-19 はマージのスループットを 1 秒あたりのバイト数で報告します。同じディスク上の他のテーブルと比べてスループットが継続的に大幅に低い場合、デバイスが低速か飽和状態であることを示します。オブジェクトストレージのディスクは正当に低速なため、相互にのみ比較してください。
• storage-14 の大きなシステムログテーブルは、容量ではなく保持期間の問題です。これらのためにディスクの追加を推奨しないでください。

詳細調査用クエリ

コーデックの変更対象を特定するための、1 つのテーブルのカラム別圧縮サイズとコーデック：

SELECT name AS column, type, compression_codec, formatReadableSize(sum(data_compressed_bytes)) AS compressed, formatReadableSize(sum(data_uncompressed_bytes)) AS uncompressed, round(sum(data_uncompressed_bytes) / nullIf(sum(data_compressed_bytes), 0), 2) AS ratio FROM system.columns WHERE database = '{database}' AND table = '{table}' GROUP BY column, type, compression_codec ORDER BY sum(data_compressed_bytes) DESC;

削除または移動するデータを判断するための、1 つのテーブルのパーティション別サイズ：

SELECT partition, count() AS parts, sum(rows) AS rows, formatReadableSize(sum(bytes_on_disk)) AS size, min(min_date) AS from_date, max(max_date) AS to_date FROM system.parts WHERE active AND database = '{database}' AND table = '{table}' GROUP BY partition ORDER BY partition;

レポート形式

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

次に使うスキル

• 圧縮率が低い、カラム型が不適切、または小さなパーツを生成するパーティショニング → スキル altinity-expert-clickhouse-schema を読み込む
• 小さなパーツが多い、マージの滞留、またはマージのスループットが低い → スキル altinity-expert-clickhouse-merges を読み込む
• 書き込み IO が多い、またはマイクロバッチ挿入 → スキル altinity-expert-clickhouse-ingestion を読み込む
• 最大サイズのオブジェクトにシステムログテーブルが含まれる → スキル altinity-expert-clickhouse-logs を読み込む
• 理由が broken または noquorum のデタッチされたパーツ → スキル altinity-expert-clickhouse-replication を読み込む
• 時間経過に伴うパーツの作成、マージ、削除のレート → スキル altinity-expert-clickhouse-part-log を読み込む
• 同じホスト上でキャッシュまたはプライマリーキーが RAM を奪い合っている → スキル altinity-expert-clickhouse-memory を読み込む