altinity-expert-clickhouse-memory

メモリ使用量と OOM 診断

system.asynchronous_metrics、system.metrics、system.dictionaries、system.parts、system.server_settings、system.query_log から、「RAM はどこに使われているのか、次に何が OOM になるのか」に答えます。 接続モード、クラスター、時間範囲がまだ確定していない場合は、先に altinity-expert-clickhouse-connection を実行してください。

クエリパック

• checks.sql — 15 個のチェック：RAM 合計と ClickHouse の常駐メモリの比較、コンポーネント別内訳（辞書、Memory／Set／Join テーブル、主キー、キャッシュ）、割り当ての監査、クエリ、辞書、Memory エンジンテーブル、主キーのメモリ消費量上位、時間経過に伴うメモリ使用量、MEMORY_LIMIT_EXCEEDED 例外、クエリと part_log のメモリ推移、サーバーのメモリ設定、ClickHouse 以外のプロセスが使用するメモリ、高メモリ使用量となる GROUP BY および JOIN クエリの形状。memory-08 には system.asynchronous_metric_log が、memory-11 には 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 カラムはその行の判定です。そのまま転記してください。再判定してはいけません。

解釈ルール

• memory-01 は ClickHouse の常駐メモリを RAM 合計に対して評価します（90 パーセント超で Critical、80 パーセント超で Major）。クエリのせいだと判断する前に、memory-13 と比較してください。
• MemoryTracking と MemoryResident の差が大きい場合は、追跡されていない割り当てが存在します。キャッシュ、アロケーターの断片化、または jemalloc が OS に返していないメモリが原因の可能性があります。クエリごとの上限を調整しても、この差は解消しません。キャッシュサイズを確認し、再起動または SYSTEM JEMALLOC PURGE を検討してください。
• memory-13 が Critical の場合、他のプロセスが max_server_memory_usage_to_ram_ratio によって確保された RAM を占有しています。同居するプロセスの配置を見直すか、比率を下げてください。ClickHouse の上限を引き上げると、OOM キラーが実行される可能性は低くなるのではなく、高くなります。
• memory-10 の行は例外コード 241（MEMORY_LIMIT_EXCEEDED）です。メッセージに記載された上限を確認してください。クエリごとの上限であればクエリが原因であり、サーバー全体の上限であれば、同時実行数または memory-02 の常駐メモリのベースラインが原因です。
• 集約によるメモリ使用量が多い場合（memory-14）：ディスクにスピルするよう max_bytes_before_external_group_by を設定し、スレッドごとのハッシュテーブルを減らすために max_threads を下げ、GROUP BY のカーディナリティを下げてください。
• JOIN によるメモリ使用量が多い場合（memory-15）：max_bytes_in_join を設定し、join_algorithm を partial_merge または auto に変更して、小さいテーブルを JOIN の右側に置いてください。
• primary_key_bytes_in_memory（memory-02、memory-07）が大きい場合、スキーマに問題があります。ORDER BY のカラムが多すぎるか、index_granularity が小さすぎる可能性があります。このメモリはアクティブなパーツごとに読み込まれ、解放されません。
• 辞書の割り当て（memory-02、memory-05）が大きい場合、RAM を恒常的に消費しています。complex_key_hashed と flat レイアウトが主な要因です。cache または direct レイアウトにすると、RAM と引き換えにレイテンシーが増加します。
• Memory エンジンテーブル（memory-06）と大きな Set／Join テーブルは、スピルできず、すべてを RAM に保持します。ここに複数 GiB のエントリーがある場合は、設計上の問題として扱ってください。

詳細分析用のクエリ

クエリごとの実行中メモリをリアルタイムで確認し、処理中のコンシューマーを捉えます：

SELECT query_id, user, round(elapsed, 1) AS elapsed_s, formatReadableSize(memory_usage) AS memory, substring(query, 1, 120) AS query_preview FROM system.processes ORDER BY memory_usage DESC LIMIT 10;

memory-07 で指定した 1 つのテーブルの主キー RAM とマーク数：

SELECT database, table, formatReadableSize(sum(primary_key_bytes_in_memory)) AS pk_ram, sum(marks) AS marks, count() AS parts FROM system.parts WHERE active AND database = '{database}' AND table = '{table}' GROUP BY database, table;

レポート形式

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

次のスキル

• マージまたはミューテーションのメモリ使用量がタイムラインの大半を占める → スキル altinity-expert-clickhouse-merges を読み込みます
• ディクショナリーが RAM の大きな割合を占める、または読み込みに失敗する → スキル altinity-expert-clickhouse-dictionaries を読み込みます
• マークキャッシュまたは非圧縮キャッシュが常駐メモリの大きな割合を占める → スキル altinity-expert-clickhouse-caches を読み込みます
• 主キーの RAM 使用量が多い、または ORDER BY と粒度の見直しが必要 → スキル altinity-expert-clickhouse-schema を読み込みます
• 個々のクエリで OOM が発生し、書き換えや制限の設定が必要 → スキル altinity-expert-clickhouse-reporting を読み込みます
• メモリの継続的な飽和、ロードアベレージまたはプールの飽和 → スキル altinity-expert-clickhouse-metrics を読み込みます