Hologres Diagnosis Memory

⚠️ 执行前就绪检查（所有诊断步骤之前完成）：

1. 已 pip install hologres-cli，且 hologres status 能连通目标实例（连接哪个实例 / 库由当前 profile 决定，可用 --profile <name> 切换）。
2. 云监控 AK/SK 已就绪（hologres metric config 专用配置，或 profile 通用 AK/SK，或默认凭证链）。
3. export HOLOGRES_SKILL=hologres-diagnosis-memory，便于事后审计。

完整就绪细节见 references/preconditions.md。

Hologres 内存使用率诊断

按「宏观水位形态 → 业务对齐 → 内存分类 → 四大主线归因」自动化定位 OOM / 持续高位 / 倾斜根因。仅做根因诊断：对于问题 Query 仅输出 ID 与资源指标，不输出 SQL 改写或优化建议。

输入参数

数据库由当前 profile 的 database 决定，无需也无法在命令上指定 --db-name；如需换库用 hologres config set database <db> 或 --profile <name>。

时间窗口约束

内存诊断只分析 最近 30 天内、且跨度不超过 7 天 的数据。校验规则（按顺序执行）：

1. 30 天有效期：start_time 必须满足 start_time >= current_time - 30d（hg_query_log 默认保留 30 天）。若早于 30 天前，拒绝执行并提示：

   ⚠️ 诊断时间范围超出 hg_query_log 保留期（30 天），请重新指定 start_time >= {30天前日期}。

2. 7 天跨度上限：若 end_time - start_time > 7天，使用 AskUserQuestion 工具引导用户收窄（选项：最近 7 天 / 3 天 / 1 天）。按选择重设 start_time = end_time - N天；"Other" 自填则校验跨度 ≤ 7 天且 ≥ 30 天前。

时间窗口长度决定分支阈值：<24h 短周期，>24h 长周期。

hologres-cli 约定

• 元仓 / PG 系统表查询统一用 hologres sql run --no-limit-check "<SQL>"。
• 云监控指标用 hologres metric query <metric> --instance-id <id> --start-time <s> --end-time <e> --period <p> / hologres metric latest <metric> --instance-id <id> --period <p>；instanceId 由 CLI 自动注入，无需手填 --dimensions。
• 指标名前缀（standard_ / warehouse_ / ...）需由「前置：实例类型判定」结果拼进 metric 名（见 preconditions §4）。
• 连接层已自动 SET hg_computing_resource = 'serverless'；来源标记由 export HOLOGRES_SKILL 注入，无需 手写 SET ... 前缀。
• 时间格式：hologres metric 接受 ISO-8601 或 epoch ms，无时区 ISO 串按 UTC 解析，北京时间显式带 epoch ms 或注意时区。
• 输出 digest / query_id / query 时必须保留完整内容，禁止 使用 left() / substr() / ::char(N) / ... 截断；长 SQL 换行展示。
• 独立的指标 / SQL 命令可在同一轮并行下发以加速。

诊断主流程

前置：实例类型探测 → 自动确定指标前缀 {prefix}
    └ hologres instance-manage get → data.Instance.InstanceType → {prefix}（详见 references/preconditions.md §4）

第一阶段：内存水位采集 + 形态分级
    └ 详见 references/water-level-staging.md
    ├ 全局高 / 局部倾斜 / 持续不回落 → 第二阶段
    └ 安全平稳                      → 直接出具「健康」报告

第二阶段：内存分类下钻
    ├ Q1 内存水位总览（形态判定）
    ├ Q2 业务指标对齐：CMS {prefix}query_qps / {prefix}dml_rps（排除正常增长）
    └ Q3 分类初筛：CMS {prefix}memory_usage_detail / {prefix}qe_memory_used_percentage
       详见 references/memory-classification.md

第三阶段：四大主线深挖
    ├ 主线 A — Query 侧（high-memory SQL / Plan 失真 / 访问不均）
    │           详见 references/query-attribution.md
    ├ 主线 B — 倾斜侧（Shard 物理分布 + Worker 热点 + 热点 Key）
    │           详见 references/shard-skew-analysis.md
    ├ 主线 C — Write/后台侧（DML RPS 冲击 + 后台 memType 占比）
    │           详见 references/system-metadata.md §C
    └ 主线 D — System/元数据侧（元数据膨胀 + 长事务 + 泄漏/Coredump）
                详见 references/system-metadata.md §D 与 references/internal-tools.md

第四阶段：综合输出诊断报告（Markdown）— 直接在对话中输出
    └ 模板详见 references/report-template.md
    └ ⚠️ 报告内容必须作为对话消息直接输出给用户，不要生成独立文档文件

Q2 / Q3 分流判断速查

References

注意事项

1. hologres.hg_query_log 默认保留约一个月，单次最多返回 10000 条；查询必须带 query_start 范围条件，且不要用 to_char(query_start,...) 包裹（无法走索引）。
2. CMS period 推荐 60（细粒度）或 300（长周期 / >6h 跨度）。
3. digest 字段从 V2.2 起支持，低版本实例为空，需降级为按 query 文本聚合。
4. memory_bytes 为各节点峰值内存的累加值，仅供相对排序参考；可能为 0（轻量查询取整为零或 GUC 关闭），此时降级使用 CMS {prefix}qe_memory_used_percentage + {prefix}memory_usage_detail（query memType）做 Query 内存归因。
5. 计算组（Warehouse）实例：若单组异常显著高于其他组 → 锁定该组后续所有诊断；全部组都高 → 视为全局高。
6. 本技能仅做根因诊断定位；问题 Query 只输出 ID 与资源指标快照，不包含 SQL 优化建议或改写指导。
7. 当 hologres metric / hologres sql run 返回空结果（无数据）时，禁止自行修改参数重试或变通获取数据；直接跳过该步骤，在输出结果中标注「无数据」。