huawei-cloud-dws-dymem-diag

华为云 DWS 内存使用率过高诊断技能

概述

此技能专用于 DWS 集群内存使用率过高的根因诊断。当集群触发内存使用率过高告警时，它会自动收集指标数据、分析根因（客户侧／系统侧），并输出标准化诊断报告。

架构：KooCLI (hcloud) → DWS Autopilot API → 集群监控指标；MCP Server (dws_autopilot) → 同一 API 的备用渠道

适用场景：

• DWS 集群内存使用率过高告警
• 内存不足／OOM 调查
• 用户主动发起内存诊断请求

典型用例：

• “我的 DWS 集群内存使用率很高，请帮忙诊断”
• “收到了内存告警，集群 ID 是 xxx，请帮忙分析原因”
• “DWS 集群发生了 OOM，看看是什么原因导致的”

重要规则：所有诊断结论都必须来自工具的实际返回结果。禁止编造或假设数值。输出内容只能包含诊断报告；禁止添加修复建议、输出 SQL 优化语句或使用表情符号。

背景知识：内存使用率公式、CN／DN 实例区别、memory_pool 分析、内存阈值和重要原则记录在内存背景知识中。诊断前必须阅读。

前置条件

1. CLI 要求

• KooCLI (hcloud) >= 3.2.0
• 验证安装：hcloud version
• 如果未安装或版本过低，请参阅 CLI 安装指南

2. MCP Server 配置（备用）

• KooCLI 不可用时，使用 MCP Server 作为替代方案
• 请参阅 MCP 安装指南

3. 身份验证配置

• 有效的华为云凭证（AK/SK 模式或 IAM Token）
• 安全规则：
  • 切勿在对话或命令中暴露 AK/SK 值
  • 切勿要求用户直接在对话中输入 AK/SK
  • 只能使用 hcloud configure list 检查凭证状态

4. IAM 权限要求

• dws:clusters:get、dws:clusters:list
• dws:metricData:get、dws:hostOverview:get
• 请参阅 IAM 策略

KooCLI 命令格式规范

命令格式

# Query metric data
hcloud DWS ListMetricsData --cli-region=<region> --cluster_id=<id> --metric_name=<name> --project_id=<pid> --offset=0 --limit=200 --from=<from_ts> --to=<to_ts>

# Query host information
hcloud DWS ListHostOverview --cli-region=<region> --project_id=<pid> --offset=0 --limit=200

工具选择策略

在 KooCLI 和 MCP Server 之间进行选择，优先使用 KooCLI。步骤 0 检查 hcloud 是否可用：

• hcloud 可用（版本 >= 3.2.0）→ 后续步骤使用 KooCLI 命令行调用
• hcloud 不可用（未安装或版本 < 3.2.0）→ 后续步骤使用 MCP Server 工具调用

回退与终止策略：

• 选择 hcloud 后，如果首次调用返回 NETWORK_ERROR（连接超时、网络不可达等），则自动回退到 MCP Server，后续步骤全部使用 MCP 模式
• 如果 hcloud 返回 NETWORK_ERROR 且 MCP Server 也不可用（未配置或返回身份验证／连接错误），则终止此技能并输出：KooCLI network unavailable and MCP Server connection failed. Please check KooCLI network configuration or DWS Autopilot MCP Server configuration and retry
• 选择 MCP Server 后，如果首次调用返回身份验证错误（例如 401 Unauthorized），不要回退到 hcloud。直接终止此技能并输出：MCP Server authentication failed. Please check DWS Autopilot MCP Server authentication configuration and retry
• 非 NETWORK_ERROR 的 hcloud 调用失败（例如参数错误、权限不足）不会触发回退；请遵循现有重试逻辑

选择工具后，除 NETWORK_ERROR 回退外，整个过程中都必须使用该工具，不得切换。如果调用失败，重试一次（最多尝试 2 次）。如果仍然失败，则将该指标标记为“不可用”并继续下一步。当所有指标查询都失败时，直接生成诊断报告。

参数映射

常用参数	hcloud 参数	MCP 参数
区域	--cli-region	（内置于 MCP 连接）
项目 ID	--project_id	project_id
集群 ID	--cluster_id	cluster_id
指标名称	--metric_name	metric_name
开始时间	--from	from_ts
结束时间	--to	to_ts
分页偏移量	--offset	offset
分页上限	--limit	limit
排序字段	（不支持）	order_by
排序方向	（不支持）	sort_by

MCP 工具

工具名称	用途	关键参数
dws_autopilot_get_clusters	查询集群列表	project_id, cluster_id, limit, offset
dws_autopilot_get_hosts	查询主机信息	project_id, cluster_id, limit, offset
dws_autopilot_get_metric	查询指标数据	project_id, cluster_id, metric_name, from_ts, to_ts, limit, offset, order_by, sort_by

metric_data 参数说明：metric_data 不支持按 instance_name 筛选（没有此参数）；查询会返回完整的集群数据，必须根据 inst_name 字段筛选目标实例；metric_data 不支持 period 参数（采样周期由平台自动确定）。

可用的 metric_name：MemStat、InstanceMemory、memory_diagnose_detail

时间协议：from_ts/to_ts 必须使用 Unix 毫秒时间戳；所有时间均为 UTC 时区；建议时间窗口为报警时间前 20 分钟至报警时间（from_ts = first_alarm_time - 1200000）。

返回格式：成功时为 {"code": 0, "data": [...]}；失败时为 {"code": -1, "message": "error description"}。失败时重试一次；如果仍然失败，则使用降级路径，并在报告中标记为“不可用”。

各指标的关键字段：

• MemStat：ctime, host_id, mem_total, mem_free, mem_available, cached, buffers, swap_total, swap_free, watermark_high, watermark_min → 内存使用率 = (mem_total - mem_free - cached - buffers) / mem_total * 100%
• InstanceMemory：ctime, host_id, inst_name, dynamic_used_memory, max_dynamic_memory, dynamic_peak_memory, process_used_memory, max_process_memory, shared_used_memory, max_shared_memory, comm_used_memory, max_comm_memory, cstore_used_memory, max_cstore_memory, topsql_used_memory, max_topsql_memory, other_used_memory, udf_reserved_memory, mmap_used_memory, storage_compress_memory, pooler_conn_memory, pooler_freeconn_memory → 动态内存使用率 = (dynamic_used_memory / max_dynamic_memory) * 100%；进程内存使用率 = (process_used_memory / max_process_memory) * 100%
• memory_diagnose_detail：ctime, host_id, instance_name, active_sessions[{query, query_id, userName, mem_used, state, duration_ms, plan_type}], memory_pool{work_mem_used/total, shared_pool_used/total}

有关各步骤的查询差异，请参阅 指标参考。

分页规范

所有工具调用（MCP 和 hcloud）都必须使用分页查询，以避免单次响应过大并超出令牌限制。

分页规则：

• 统一使用 limit=200（不要使用 800 或其他较大的值）
• 首页使用 offset=0；如果返回的数据量 = 200，则将 offset+=200 并继续查询
• 重复查询，直到返回的数据量 < 200，然后合并所有分页数据
• 合并时，将所有页面的数据数组拼接成完整数据集

MCP 调用示例（使用 MemStat）：

Page 1: dws_autopilot_get_metric(project_id, cluster_id, metric_name="MemStat", from_ts, to_ts, limit=200, offset=0)
If returned data length = 200:
Page 2: dws_autopilot_get_metric(project_id, cluster_id, metric_name="MemStat", from_ts, to_ts, limit=200, offset=200)
If returned data length < 200: Stop pagination, merge page 1 + page 2 data

hcloud 调用示例（使用 MemStat）：

Page 1: hcloud DWS ListMetricsData --cli-region=<region> --cluster_id=<id> --metric_name=MemStat --project_id=<pid> --offset=0 --limit=200 --from=<from_ts> --to=<to_ts>
If returned data count = 200:
Page 2: hcloud DWS ListMetricsData --cli-region=<region> --cluster_id=<id> --metric_name=MemStat --project_id=<pid> --offset=200 --limit=200 --from=<from_ts> --to=<to_ts>
If returned data count < 200: Stop pagination, merge data

工作流

诊断前，根据步骤 0-7 制定执行计划，然后按顺序执行。工具选择策略请参阅“KooCLI 命令格式标准”部分；后续步骤不再重复说明。所有 MCP 工具调用均遵循“分页规范”部分；后续步骤不再重复分页细节。

步骤 0：环境检测

执行 hcloud version；版本 >= 3.2.0 → tool_mode=hcloud，否则 tool_mode=mcp。

hcloud 网络可用性探测：如果 tool_mode=hcloud，执行轻量级 API 调用（例如，hcloud DWS ListClusters --cli-region=<region> --project_id=<project_id> --offset=0 --limit=1）以验证网络连接：

• 返回正常结果或业务错误（例如，权限不足、参数错误）→ 网络可用，保留 tool_mode=hcloud
• 返回 NETWORK_ERROR → 网络不可用，回退到 tool_mode=mcp
• 回退后，如果 MCP 也不可用 → 终止执行，提示用户检查 KooCLI 网络配置或 MCP 服务配置

步骤 1：查询 MemStat

调用指标查询，metric_name="MemStat"，时间范围：from_ts=first_alarm_time - 1200000，to_ts=first_alarm_time。在 MCP 模式下，使用 limit=200 分页查询。

Autopilot 不可用判定：返回 50201/RDS.9999 错误 → 跳过步骤 1-6，将所有指标标记为“不可用”，直接进入步骤 7。

解析：按 host_id 分组，查找每个节点最新的内存数据。内存使用率 = (mem_total - mem_free - cached - buffers) / mem_total * 100%。判断是否过高（> 80%）、整体偏高（全部 > 70%）、是否不均衡（偏差 > 30%）。找出内存最高的两个节点和 TOP3。

节点范围分类（基于 high_mem_nodes 数量）：

• 所有节点内存偏高：大多数节点内存偏高（参考：高内存节点占比 >= 80%）→ 倾向于业务侧原因（高并发、复杂 SQL）
• 单个节点内存偏高：高内存节点数 = 1 → 倾向于数据倾斜、连接倾斜、进程异常
• 部分节点内存偏高：1 < 高内存节点数 < 大多数节点 → 倾向于新旧节点差异、主 DN 倾斜、局部数据倾斜

输出：mem_by_host、max_mem_hosts、problem_host_id、problem_host_mem_usage、problem_host_used、problem_host_total、problem_host_available、top3_mem_nodes、cluster_avg_mem、is_imbalanced、is_global_high、mem_deviation、high_mem_nodes、mem_scope

步骤 2：获取主机名称

调用主机信息查询（MCP 模式下使用 limit=200 分页查询），构建 host_id → {host_name, ip} 映射表。仅查询步骤 1 输出的 max_mem_hosts 中所涉及节点的主机信息。

输出：host_id_to_info_map、problem_host_ip、node_name

步骤 3：查询 InstanceMemory

调用指标查询，metric_name="InstanceMemory"，时间范围与步骤 1 相同。在 MCP 模式下，使用 limit=200 分页查询。注意：metric_data 不支持按 instance_name 筛选；查询会返回整个集群的数据，必须通过 inst_name 字段筛选目标实例。

解析：提取每个实例（CN/DN）的内存使用情况。动态内存使用率 = (dynamic_used_memory / max_dynamic_memory) * 100%；进程内存使用率 = (process_used_memory / max_process_memory) * 100%。找出内存使用率最高的实例。

CN/DN 实例区分（基于 inst_name 字段，InstanceMemory 没有 instance_type 字段）：

• inst_name 包含 "cn" 或 "coordinator" → CN 实例
• inst_name 包含 "dn" 或 "datanode" → DN 实例
• CN 实例内存偏高 → 重点关注连接倾斜、未下推 SQL、解析压力
• DN 实例内存偏高 → 重点关注数据倾斜、计算倾斜、排序/哈希溢写

内存类型判定（基于 InstanceMemory 动态内存与进程内存的比例）：

• 动态内存占比较高 → 动态内存偏高，重点关注业务 SQL、work_mem 配置
• 进程内存占比较高 → 进程内存偏高，重点关注连接过多、进程泄漏

输出：instance_memory_data、high_memory_instances、instance_type_distribution、top3_dynamic_instances、inst_type、mem_type

第 4 步：查询内存诊断详情

调用指标查询，metric_name="memory_diagnose_detail"，时间窗口与第 1 步相同。注意：metric_data 不支持按 instance_name 过滤；查询会返回整个集群的数据，必须根据第 1 步输出中的 max_mem_hosts 进行过滤。 MCP 模式必须使用 limit=200 进行分页查询（此指标的数据量最大），直到返回数量小于 200，再合并所有分页数据后进行过滤。

解析：提取活跃查询语句、执行用户（userName）、内存使用量、会话信息、SQL 级内存统计数据。

时间标注规则：memory_diagnose_detail 中的 ctime 是 Autopilot 采集快照的时间，而不是实际 SQL 开始时间。如果 active_sessions 包含 duration_ms 字段，则 SQL 开始时间 = ctime - duration_ms，标注为“开始时间”；如果没有 duration_ms，则直接使用 ctime，标注为“采集时间”（不要将采集时间标注为“开始时间”）。

活跃用户统计规则：仅统计 state=active 的用户和连接；不统计 idle 状态。按 userName 分组并汇总内存使用量，以识别内存使用量最高的用户。

输出：user_memory_top5、session_memory_top5、sql_memory_top5、total_memory_by_users、total_memory_by_sqls、high_memory_sql_detected、high_memory_sql_info、high_freq_queries、heavy_queries、memory_pool_data、idle_session_with_high_mem

第 5 步：分析诊断结果

根据第 1 至第 4 步收集的数据，结合用户身份分析内存占用高的原因。

诊断优先级：先看影响范围，再查找原因；优先排查业务异常，最后检查配置和系统。

时间格式：所有 Unix 毫秒时间戳（first_alarm_time、ctime 等）均为 UTC 时区。在报告中，必须将其转换为北京时间（UTC+8）字符串 YYYY-MM-DD HH:MM:SS。可使用 python -c "from datetime import datetime,timezone,timedelta; print(datetime.fromtimestamp({ms}/1000,tz=timezone(timedelta(hours=8))).strftime('%Y-%m-%d %H:%M:%S'))"。不要凭心算计算时间戳值。

用户身份判断（依据数据库用户，即 memory_diagnose_detail active_sessions 中的 userName）：

• 数据库用户为 "omm" 或 "Ruby" → 系统原因
• 数据库用户既不是 "omm" 也不是 "Ruby" → 客户侧原因

memory_pool 分析（来自第 4 步的 memory_pool_data）：

• work_mem 使用率 = (work_mem_used / work_mem_total) * 100%，work_mem 使用率高表示 SQL 排序/哈希操作消耗大量内存
• shared_pool 使用率 = (shared_pool_used / shared_pool_total) * 100%，shared_pool 使用率高表示共享缓存压力大
• work_mem 使用率 > 80% → 重点关注 SQL 排序/哈希溢出、work_mem 配置过大
• shared_pool 使用率 > 80% → 重点关注共享表/索引缓存压力、连接过多

客户侧原因

1. 单条 SQL 导致内存占用高：单条 SQL 的内存占比突出（参考：占比 > 20%），是节点内存占用高的重要原因。plan_type 辅助判断：如果 plan_type 为 HashJoin/HashAggregate，则哈希操作是内存消耗的主要原因
2. 多用户并发导致内存占用高：多个用户同时消耗大量内存
   • concurrent_mode 判定规则：multi_user（多个不同数据库用户有活跃查询，活跃用户数 >= 2）；single_user（只有一个数据库用户，但有许多并行查询，活跃用户数 = 1 且查询数量大）；none（非高并发场景）
3. 会话泄漏或长事务：会话状态为 idle，但仍占用大量内存（来自第 4 步的 idle_session_with_high_mem）；或者会话运行时间过长（duration_ms 超过参考值 30 分钟）且未释放内存
4. 数据倾斜导致内存不均衡：节点间偏差 > 30%

注意：单条 SQL 和多用户并发可能同时符合条件，应分别列为独立异常项，二者并不互斥。

系统原因

1. 系统内部任务导致内存占用高：omm/Ruby 用户消耗大量内存
2. 实例内存配置不合理：实例内存使用率持续接近上限（动态内存使用率持续 > 80%），结合 memory_pool 数据判断 work_mem/shared_pool 配置
3. 内存泄漏：MemStat 或 InstanceMemory 时序数据显示内存使用量持续单调递增（比较多个 ctime 数据点，呈现持续上升且无回落的趋势），没有明显的外部查询，但内存仍持续增长

综合判断规则：

条件	标记
所有节点使用率 > 70%	集群内存整体偏高
节点间偏差 > 30%	集群内存负载不均衡，可能存在数据倾斜
单个实例动态内存使用率明显异常	单实例内存异常
high_memory_sql_detected = true	单条 SQL 导致内存占用高，已识别具体 SQL
user_memory_top5 中 omm/Ruby 占比 > 30%	系统内部任务消耗大量内存（系统侧）
MemStat/InstanceMemory 时序持续单调递增	可能存在内存泄漏
work_mem 使用率 > 80%	work_mem 配置过大，或 SQL 排序/哈希溢出
shared_pool 使用率 > 80%	共享缓存压力大，连接数过多

统计与聚合要求：

1. 内存占比 Top3 数据库用户：按 active_sessions 的 userName 分组并聚合 mem_used（仅数据库用户，不包括进程用户）。在“内存贡献 Top3 数据库用户” HTML 表格区域中使用 pct-bar 可视化展示。占比 = 用户 mem_used 总量 / 所有用户 mem_used 总量 × 100%。pct-bar 宽度计算：width = Math.round(ratio / max_ratio * 200)，其中 max_ratio 为排名第一用户的占比。仅统计 state=active 的数据库用户。如果数据点少于 3 个，则列出实际数量。
2. 内存占比 Top3 SQL：从 memory_diagnose_detail active_sessions 中按 mem_used 降序排序，并在“内存贡献 Top3 语句” HTML 表格区域中展示。每行代表一次查询执行；排序选取 Top 3 时，每行独立处理。QueryID 来自 query_id 字段（多个相似 SQL 以逗号分隔，并附带数量注释）。用户名来自 userName 字段（数据库用户）。内存占比来自 mem_used 字段，按节点总内存消耗计算百分比，保留 1 位小数。时间：存在 duration_ms 时，使用 ctime - duration_ms 转换为北京时间（列标题“启动时间”）；不存在 duration_ms 时，使用 ctime 转换为北京时间（列标题“采集时间”）。SQL 来自 query 字段，最多显示 1000 个字符，超出部分用“...”截断。gaussdb 进程不作为独立语句列入 Top3；其内存开销合并到相应的根因说明中。如果没有语句数据，则在表格中填入“无法获取”。
3. 占比 =（用户/SQL 内存消耗 / 节点总内存消耗）× 100%

输出：root_cause_category, mem_scope, inst_type, mem_type, summary, high_memory_sql_info, session_info, top3_memory_users, top3_memory_statements, high_freq_queries, heavy_queries, memory_pool_summary, concurrent_mode

步骤 6：获取集群名称

优先从输入参数 cluster_name 获取集群名称。如果为空，则调用 dws_autopilot_get_clusters，使用 project_id 和 cluster_id 获取 cluster_name。如果调用也失败，则使用 cluster_id 作为 resource_name。

输出：resource_name, resource_id

步骤 7：生成诊断报告

按照“输出格式”部分中的模板生成 HTML 报告。生成报告后，将 HTML 文件保存到当前工作目录（工作区根文件夹），文件名为 dws_mem_diagnosis_report_{timestamp}.html，其中 {timestamp} 是当前机器本地时间，格式为 yyyyMMdd_HHmmss（例如：dws_mem_diagnosis_report_20260623_150421.html）。

核心命令

查询集群列表

# hcloud
hcloud DWS ListClusters --cli-region=<region> --project_id=<pid> --offset=0 --limit=200
# MCP
dws_autopilot_get_clusters(project_id=<pid>)

查询主机信息

# hcloud
hcloud DWS ListHostOverview --cli-region=<region> --project_id=<pid> --offset=0 --limit=200
# MCP
dws_autopilot_get_hosts(project_id=<pid>, cluster_id=<cid>, limit=200, offset=0)

查询指标数据（通用格式）

# hcloud
hcloud DWS ListMetricsData --cli-region=<region> --cluster_id=<cid> --metric_name=<name> --project_id=<pid> --offset=0 --limit=200 --from=<from_ts> --to=<to_ts>
# MCP
dws_autopilot_get_metric(project_id=<pid>, cluster_id=<cid>, metric_name=<name>, from_ts=<from>, to_ts=<to>, limit=200, offset=0, order_by="ctime", sort_by="desc")

参数确认

参数	必填/可选	描述	默认值
alarm_serial_number	必填	告警序列号	N/A
project_id	必填	项目 ID	N/A
cluster_id	必填	集群 ID	N/A
first_alarm_time	必填	首次告警时间（毫秒时间戳）	N/A
alarm_name	必填	告警名称	N/A
region_id	可选	区域标识符	N/A
node_name	可选	告警节点名称	空（集群级告警）
instance_name	可选	实例名称	空
cluster_name	可选	集群名称	使用 cluster_id
alarm_severity	可选	告警严重程度	N/A

输出格式

严格按照 输出格式 中的模板进行输出和返回。不要分析或总结模板内容，不要遗漏任何部分，也不要修改模板结构。输出必须与模板一致。

最佳实践

1. 时间戳处理：first_alarm_time 已经是毫秒时间戳；直接将其用于工具参数。不要先转换为时间字符串，再转回时间戳（以避免 8 小时时差）
2. 工具选择：在 KooCLI 和 MCP 之间进行选择，优先选择 KooCLI；选定后，全程使用该方法
3. 分页查询：所有工具调用统一使用 limit=200 进行分页，直到返回数量 < 200，然后合并所有分页数据。memory_diagnose_detail 的数据量最大，必须分页
4. 报告时间：所有时间戳都必须转换为北京时间（UTC+8）。可使用 python -c "from datetime import datetime,timezone,timedelta; print(datetime.fromtimestamp({ms}/1000,tz=timezone(timedelta(hours=8))).strftime('%Y-%m-%d %H:%M:%S'))"
5. SQL 显示：内存贡献 Top3 语句展示最多 1000 个字符的具体 SQL；超出时用 "..." 截断
6. 内存使用率计算：内存使用率 = (mem_total - mem_free - cached - buffers) / mem_total * 100%；动态内存使用率 = (dynamic_used_memory / max_dynamic_memory) * 100%；进程内存使用率 = (process_used_memory / max_process_memory) * 100%
7. CN/DN 实例区分：inst_name 包含 "cn"/"coordinator" → CN；包含 "dn"/"datanode" → DN；CN 内存高时重点关注连接/解析，DN 内存高时重点关注数据/计算
8. 会话泄漏检测：空闲状态但占用大量内存 → 会话泄漏；duration_ms > 30 分钟且未释放内存 → 长事务

参考资料

文档	描述
CLI 安装指南	KooCLI 安装与配置
MCP 安装指南	DWS Autopilot MCP Server 安装与配置
IAM 策略	所需权限和策略 JSON
指标参考	指标键字段和查询差异
内存背景知识	内存公式、CN/DN 区分、memory_pool 分析、阈值
输出格式	HTML 模板和填写规则

注意事项

• 安全性：切勿在对话或命令中暴露 AK/SK 值；切勿要求用户直接在对话中输入 AK/SK
• 时间协议：from_ts/to_ts 必须使用毫秒时间戳；报告显示北京时间；将北京时间转换为时间戳时，必须添加 +08:00 时区后缀；切勿凭心算计算时间戳值；切勿将现有的毫秒时间戳转换为时间字符串后再转回
• 输出限制：严格按照「输出格式」部分的模板输出诊断报告；不得修改模板结构、遗漏任何部分、添加修复建议、输出 SQL 优化语句、使用表情符号或自定义格式标签
• 数据真实性：所有诊断结论都必须来自工具的实际返回结果；工具返回为空或调用失败时，标记为“不可用”；禁止编造值
• 已知限制：hcloud 不支持 --order_by 和 --sort_by 参数；查询后在本地按 ctime 降序排序；memory_diagnose_detail 不支持按 host_id 筛选；查询整个集群后在本地筛选；memory_diagnose_detail 的 ctime 是采集时间，不是 SQL 开始时间；InstanceMemory 没有 instance_type 字段，必须通过 inst_name 确定 CN/DN