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. 一次运行一条语句，切勿运行整个文件。语句以 ; 结束，并以 -- @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 尚未归还给操作系统的内存。调整每查询限制无法弥合这一差距；请检查缓存大小，并考虑重启或执行 SYSTEM JEMALLOC PURGE。
• memory-13 的 Critical 表示其他进程占用了 max_server_memory_usage_to_ram_ratio 保留的 RAM。请解决共置问题或降低该比率；提高 ClickHouse 限制只会让 OOM killer 更可能触发，而不是更不可能。
• 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 指定的单个表的主键 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 列的表格；每项发现一行，按严重程度从 Critical 开始。证据引用结果行中的数字。
3. 正常检查：用一行列出未返回问题行的检查 ID。
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