huawei-cloud-mrs-host-alarm-diagnose

华为云 MRS 告警诊断技能

概述

此技能用于诊断华为云 MRS（MapReduce Service）集群告警。提供告警信息（告警 ID、告警名称、发生时间、集群 ID、节点、相关服务/角色）后，它会定位根因，并输出修复步骤和验证方法。

架构：调用方（Agent）→ check_api_mode.py（Python，scripts/）确定 API 模式 → 根据模式调用 lakewatch_api_client.py → LakeWatch API → MRS 集群（节点资源数据、日志、MRS Manager 代理），或 manager_api_client.py → MRS Manager REST API（28443）。按告警划分的知识库（lakewatch 模式下的 alarms/<alarm_id>.md，manager 模式下的 alarm_manager/<alarm_id>.md）用于指导诊断流程。

语言说明：根据仓库规范，此 SKILL.md、references/ 下的文档，以及 alarms/ 和 alarm_manager/ 下按告警划分的知识库均以英文编写。命令和代码块始终使用英文。

适用场景：

• MRS 集群产生告警，需要定位根因
• 值班工程师需要针对特定告警获取引导式诊断步骤
• 已提供告警 ID 的告警分诊

典型用例：

• “MRS集群收到12089告警，帮忙诊断一下”
• “PMS进程异常告警，告警ID 12007，集群ID xxx，帮我定位原因”
• “审计日志转储失败告警 12001，诊断根因”
• “节点间网络互通异常，告警ID 12089，发生时间 2026/06/11 16:00:32 GMT+08:00”

关键限制

重要限制：

1. 只读：此技能仅运行信息收集命令（查看日志、查询状态）。绝不能运行任何启动、停止、修改或删除操作。
2. 修复需用户确认：此技能仅提供可执行的修复步骤；绝不能直接执行任何修复操作。所有修复操作都需要用户确认。
3. 严格执行：严格按照按告警划分的知识库内容进行诊断。禁止编造知识库之外的诊断命令。

前提条件

1. Python 要求

• Python >= 3.7
• 依赖项：pyyaml（YAML 解析）、cryptography（仅用于 Windows AES 密码加密）
• Linux 使用 CryptoAPI 加密密码（无需依赖 cryptography）
• 验证安装：python3 --version（Linux）/ python --version（Windows）

此技能不需要 KooCLI（hcloud）。它通过 scripts/lakewatch_api_client.py（lakewatch 模式）调用 LakeWatch API，或通过 scripts/manager_api_client.py（manager 模式）调用 MRS Manager REST API。客户端设置请参阅 CLI 安装指南。

2. LakeWatch 凭据配置

• 有效的 LakeWatch 服务账号（用户名 + 密码）
• 密码必须使用 --encrypt-password 加密，并存储在 scripts/lakewatch_api_config.yaml（auth.encrypted_password）中。切勿存储明文密码。
• 安全规则：
  • 切勿在对话或命令输出中泄露 LakeWatch 密码
  • 切勿要求用户在对话中输入明文密码；请使用交互式 --encrypt-password 流程
  • 令牌会以仅所有者可访问的文件权限缓存在本地（Win：%TEMP%\lakewatch_token\，Linux：/tmp/lakewatch_token/）

3. MRS Manager 凭据配置（Manager 模式）

当 scripts/manager_api_config.yaml 存在且设置了 auth.encrypted_password 时，即启用 Manager 模式。

• 有效的 MRS Manager 账号（用户名 + 密码）
• 在 server.host 中配置 Manager 浮动 IP（默认端口为 28443）。获取方式：在 OMS 节点上运行 grep float_ip /opt/huawei/Bigdata/om-server/OMS/workspace/conf/oms.ini，或咨询集群管理员。
• 密码必须使用 python3 scripts/manager_api_client.py --encrypt-password 加密，并存储在 scripts/manager_api_config.yaml（auth.encrypted_password）中。切勿存储明文密码。
• 安全规则：
  • 切勿在对话或命令输出中泄露 Manager 密码
  • 切勿要求用户在对话中输入明文密码；请使用交互式 --encrypt-password 流程
  • Windows AES 密文需要连同 .aes_key 文件一起迁移，才能在另一台机器上解密；Linux SCC 密文无法在不同集群间移植
• 完整的客户端用法请参阅 MRS Manager API 客户端。

4. 访问权限

• Lakewatch 模式：能够访问 LakeWatch 服务端点（在 scripts/lakewatch_api_config.yaml 的 server.host/port 中配置）；LakeWatch 账号必须有权限调用 MRS Manager 代理，并在目标集群上收集节点资源和日志数据
• Manager 模式：脚本运行环境必须能够访问 Manager 端口 28443；Manager 账号需要对告警、主机、实例和日志 API 具有读取权限
• 访问模型和所需角色请参阅 IAM 策略

命令格式规范

此技能使用 LakeWatch API 客户端，而非 KooCLI。统一命令格式如下：

# Linux
python3 <skill_dir>/scripts/lakewatch_api_client.py -a <api_name> -p 'key1=value1' -p 'key2=value2'

# Windows
python <skill_dir>/scripts/lakewatch_api_client.py -a <api_name> -p 'key1=value1' -p 'key2=value2'

元素	规则	示例
python3 / python	Linux 使用 python3，Windows 使用 python	python3 lakewatch_api_client.py
-a, --api	要调用的 API 名称（在 lakewatch_api_config.yaml 中定义）	-a collect_alarm_node_res_data
-p, --param	API 参数，采用 key=value 格式，可重复	-p 'cluster_id=xxx'
引号	每个 -p 值都必须用单引号括起，以防 shell 解析 `[] {}	()`

Windows（PowerShell）引号规则：值中的每个 " 都必须替换为 """（包括 [] 和 {} 中的 "），否则服务端会返回 {"message":"Unknown exception","success":false,"code":"500"}：

# Correct on Windows
-p 'keywords=["""ERROR"""]'
-p 'env={"""PID""":"""123"""}'

# Wrong on Windows (will fail)
-p 'keywords=["ERROR"]'

Linux（bash）引号规则：值中的 " 保持原样，并用单引号括起整个值：

# Correct on Linux
-p 'keywords=["ERROR","Exception"]'
-p 'env={"PID":"123"}'

完整的 API 目录、参数及令牌/加密机制，请参阅 LakeWatch API 客户端。

MRS Manager API 客户端（Manager 模式）

当 check_api_mode.py 报告 manager 时，请使用 manager_api_client.py，而非 LakeWatch 客户端。统一命令格式如下：

# Linux
python3 <skill_dir>/scripts/manager_api_client.py -a <api_name> -p 'key1=value1' -p 'key2=value2' --json

# Windows
python <skill_dir>/scripts/manager_api_client.py -a <api_name> -p 'key1=value1' -p 'key2=value2' --json

元素	规则	示例
python3 / python	Linux 使用 python3，Windows 使用 python	python3 manager_api_client.py
-a, --api	要调用的 API 名称（在 manager_api_apis/ 中定义）	-a get_instances
-p, --param	API 参数，采用 key=value 格式，可重复	-p 'service_name=DBService'
--json	JSON 格式输出	--json
--auth	认证模式：basic（默认）或 cookie	--auth cookie
引号	引号规则与 LakeWatch 客户端相同（用 ' 括起；Windows 中 " → """）	-p 'keywords=["ERROR"]'

完整的 API 目录、认证模式、指标名称和密码加密机制，请参阅 MRS Manager API 客户端。

工作流

步骤 1：确定告警信息

从用户输入中提取以下告警信息：

字段	参数	必填	描述	示例
告警 ID	alarm_id	可选	告警唯一 ID，例如 12089	12007
告警名称	alarm_name	必填	告警中文名称	PMS进程异常
发生时间	alarm_time	必填	告警发生时间	2026/06/11 16:00:32 GMT+08:00
集群 ID	cluster_id	可选	MRS 集群 ID	fd04c789-39d4-4847-8fc9-4572fec9414f
主机名	node_name	可选	告警发生的主机（来自告警定位信息）	8-5-225-6
服务名称	server_name	可选	触发告警的服务（来自告警定位信息）	Manager
角色名称	role_name	可选	触发告警的角色（来自告警定位信息）	pms
附加信息	additional_info	可选	告警附加信息，通常包含关键诊断线索

注意：

• 包含 . 的节点值是节点 IP；否则是主机名。
• 如果用户未提供告警 ID 或集群 ID，请询问用户提供相关信息并停止执行。

步骤 2：确定 API 模式并定位单个告警知识库

步骤 2-1：确定 API 模式

运行模式检查脚本，以确定诊断基于 MRS Manager 还是 LakeWatch：

• Windows：python scripts/check_api_mode.py
• Linux：python3 scripts/check_api_mode.py

该脚本会检查 scripts/manager_api_config.yaml 是否存在，以及是否填写了 encrypted_password，并返回 JSON 结果：

{"mode": "manager", "reason": "..."}     // manager-based
{"mode": "lakewatch", "reason": "..."}   // lakewatch-based

规则：

• manager_api_config.yaml 不存在 → 默认使用 lakewatch
• 文件存在但 encrypted_password 为空 → 默认使用 lakewatch
• 文件存在且 encrypted_password 不为空 → 使用 manager

步骤 2-2：定位单个告警知识库

根据步骤 2-1 的结果：

• lakewatch 模式：读取此技能目录下的 alarms/<alarm_id>.md 获取诊断流程。同时阅读 LakeWatch API 客户端，了解 Python 脚本的用法。
• manager 模式：读取此技能目录下的 alarm_manager/<alarm_id>.md 获取诊断流程。同时阅读 MRS Manager API 客户端，了解 Python 脚本的用法。

如果不存在匹配的告警文档，请告知用户：暂不支持此告警的分析。（不支持分析此告警。）

步骤 3：执行告警诊断

按照步骤 2 中的单个告警知识库执行诊断。

诊断执行注意事项：

• 仅使用单个告警知识库中提供的具体命令；不要自行推断日志路径
• 变量占位符（例如 <alarm_time>、<alarm_node>）必须替换为实际值，切勿直接写入命令
• 必须使用摘要工具汇总命令执行结果
• 运行 lakewatch_api_client.py 或 manager_api_client.py 时，Windows 使用 python，Linux 使用 python3
• 使用与步骤 2-1 模式相匹配的客户端：lakewatch 模式使用 lakewatch_api_client.py，manager 模式使用 manager_api_client.py
• 所有 -p 参数值都必须用单引号括起来；在 Windows PowerShell 中，值里的每个 " 都必须替换为 """
• 重要：诊断完成后，结合诊断结果进行复核，确认告警诊断是否完整

命令失败处理：命令失败时，跳过当前检查项并继续执行其他检查。

步骤 4：输出诊断结论

按照以下模板输出：

## Diagnosis Result

| Item | Content |
|------|---------|
| Diagnosis time | [time] |
| Cluster ID | [cluster_id] |
| Alarm name | [alarm_name] |
| Alarm ID | [alarm_id] |
| Alarm node | [node info] |
| Alarm occurrence time | [occurrence time] |

### Root Cause

**Preliminary judgment**: [root cause type]

**Analysis basis**:

- [basis 1]
- [basis 2]

### Repair Suggestion

| Priority | Operation | Description | Needs user confirmation |
|----------|-----------|-------------|-------------------------|
| 1 | [operation 1] | [description] | Yes |
| 2 | [operation 2] | [description] | Yes |

核心命令

查询告警技能内容

# Query the alarm diagnosis skill content by alarm sequence ID
python3 lakewatch_api_client.py -a query_alarm_skill \
  -p 'cluster_id=<cluster_id>' \
  -p 'alarm_sequence_id=<alarm_serial_no>'

收集告警节点资源数据

# Collect node resource data for a given strategy (system-load, memory-usage, disk-space, etc.)
python3 lakewatch_api_client.py -a collect_alarm_node_res_data \
  -p 'cluster_id=<cluster_id>' \
  -p 'strategy_name=system-load' \
  -p 'node_name=<node_name>'

支持的 strategy_name 值包括：system-load、memory-usage、disk-space、disk-io、network-io、file-handle、port-check（需要 env={"PORT":"<port>"}）、high-cpu-processes、high-memory-process、zombie-process、dns-check、network-connectivity-test（需要 env={"TARGET_IP":"<ip>"}）、process-basic-info（需要 env={"process_name":"java"}）、process-file-descriptor（需要 env={"PID":"<pid>"}）、jstack-thread-dump（需要 env={"PID":"<pid>"}）、disk-health-check、disk-smart-info（需要 env={"DISK_DEVICE":"/dev/sda"}）、disk-raid-status、ha-resource-status 等。完整列表请参阅 LakeWatch API Client。

收集告警日志数据

# Collect alarm-related log data around the alarm time
python3 lakewatch_api_client.py -a collect_alarm_log_data \
  -p 'cluster_id=<cluster_id>' \
  -p 'alarm_time=2026/06/11 16:00:32 GMT+08:00' \
  -p 'log_directory=/var/log/hadoop/hdfs' \
  -p 'log_file_name=hadoop-hdfs-datanode.log' \
  -p 'keywords=["ERROR","Exception"]' \
  -p 'log_type=local'

如果日志时间格式不是标准 ISO 格式（例如 [2026-07-07 20:54:25,171]），请传入 time_pattern：

python3 lakewatch_api_client.py -a collect_alarm_log_data \
  -p 'cluster_id=<cluster_id>' \
  -p 'alarm_time=2026/07/07 20:54:00 GMT+08:00' \
  -p 'log_directory=/var/log/Bigdata/omm/oms/pms' \
  -p 'log_file_name=pms*.log' \
  -p 'keywords=["ERROR","Exception"]' \
  -p 'log_type=local' \
  -p 'time_pattern=^\[([0-9]{4})-([0-9]{2})-([0-9]{2}) ([0-9]{2}):([0-9]{2}):([0-9]{2})||ymdHMS'

代理 MRS Manager GET API

# Query audit dump config via the LakeWatch manager-access proxy
python3 lakewatch_api_client.py -a access_manager_get \
  -p 'cluster_id=<cluster_id>' \
  -p 'target_url=api/v2/audits/config'

# Query audit logs (returns totalCount)
python3 lakewatch_api_client.py -a access_manager_get \
  -p 'cluster_id=<cluster_id>' \
  -p 'target_url=api/v2/audits?limit=1'

target_url 不能以 / 开头。代理要求 Agent >= 1.0.5，且已上报 OMS 节点信息。目前仅支持 GET。

MRS Manager API 命令（Manager 模式）

处于 Manager 模式时，使用 manager_api_client.py 执行等效查询：

# Query current alarms (with status=1 for active alarms)
python3 manager_api_client.py -a get_alarms -p 'status=1' --json

# Query instance running status of a service
python3 manager_api_client.py -a get_instances \
  -p 'cluster_id=<cluster_id>' \
  -p 'service_name=DBService' \
  --json

# Query host process status
python3 manager_api_client.py -a get_host_process \
  -p 'hostname=<node_name>' \
  --json

# Query host monitor metrics (dev_ prefix)
python3 manager_api_client.py -a get_host_metrics \
  -p 'hostname=<node_name>' \
  -p 'metric_names=dev_cpu_surp_avg,dev_load_one_min' \
  --json

# Query host resource usage
python3 manager_api_client.py -a get_host_resource \
  -p 'hostname=<node_name>' \
  --json

# Search logs by keyword (returns task_id, then poll progress)
python3 manager_api_client.py -a start_log_search \
  -p 'cluster_id=<cluster_id>' \
  -p 'key_word=ERROR' \
  -p 'start_time=<alarm_time>' \
  -p 'end_time=<current_time>' \
  -p 'services=Manager:Manager:Agent' \
  -p 'min_log_level=ERROR' \
  --json

python3 manager_api_client.py -a get_log_search_progress \
  -p 'search_id=<task_id>' \
  --json

# Browse a log file directly (file_name must be a full path)
python3 manager_api_client.py -a browse_log \
  -p 'hostname=<node_name>' \
  -p 'file_name=/var/log/Bigdata/controller/acs/acs.log' \
  -p 'start_line=1' \
  -p 'end_line=200' \
  --json

start_log_search 的 services 格式为 component:service:role（例如 HDFS:HDFS:NameNode），多个值以 ; 分隔；start_time/end_time 格式为 yyyy-MM-ddTHH:mm:ss。有关指标名称和完整参数规则，请参阅 MRS Manager API Client。

参数确认

参数	必填/可选	描述	默认值
alarm_id	可选	告警唯一 ID，用于定位 alarms/<alarm_id>.md（lakewatch 模式）或 alarm_manager/<alarm_id>.md（manager 模式）	N/A
alarm_name	必填	告警中文名称	N/A
alarm_time	必填	告警发生时间，格式为 yyyy/MM/dd HH:mm:ss GMT+X:XX	N/A
cluster_id	可选	MRS 集群 ID	N/A
node_name	可选	告警节点主机名或 IP	N/A
server_name	可选	触发告警的服务	N/A
role_name	可选	触发告警的角色	N/A
additional_info	可选	告警附加信息	N/A
strategy_name	collect_alarm_node_res_data 必填	资源收集策略（lakewatch 模式）	N/A
log_directory	collect_alarm_log_data 必填	日志目录，必须位于 /var/log/ 下（lakewatch 模式）	N/A
log_file_name	collect_alarm_log_data 必填	日志文件名，不得包含路径分隔符（lakewatch 模式）	N/A
keywords	collect_alarm_log_data 必填	日志关键词筛选条件，JSON 数组（lakewatch 模式）	N/A
log_type	collect_alarm_log_data 必填	local 或 hdfs（lakewatch 模式）	N/A
time_pattern	可选	非标准日志时间正则表达式，格式为 `regex
service_name	get_instances 必填	要查询实例的服务名称（manager 模式）	N/A
metric_names	get_host_metrics 必填	以逗号分隔的监控指标名称，需带 dev_ 前缀（manager 模式）	N/A
key_word	start_log_search 必填	要搜索的日志关键词（manager 模式）	N/A
current_time	start_log_search 必填	当前时间，格式为 yyyy-MM-ddTHH:mm:ss（manager 模式）	N/A

输出格式

诊断报告以 Markdown 格式输出，包含：

• 诊断结果表：诊断时间、集群 ID、告警名称、告警 ID、告警节点、告警发生时间
• 根因：初步判断 + 分析依据（每项依据均引用自实际命令输出）
• 修复建议表：优先级、操作、描述、是否需要用户确认（所有修复操作均需用户确认）

请参阅工作流 → 步骤 4中的模板。

验证方法

有关安装、配置和功能验证步骤，请参阅验证方法。

最佳实践

1. 先定位知识库：始终先确认告警 ID 并运行 check_api_mode.py，然后在运行任何命令前阅读 alarms/<alarm_id>.md（lakewatch 模式）或 alarm_manager/<alarm_id>.md（manager 模式）；不要自行推断诊断步骤。
2. 替换占位符：将 <cluster_id>、<alarm_time>、<node_name>、<target_ip>、<current_time> 等替换为用户提供的实际值；切勿将其硬编码。
3. 为参数加引号：始终为 -p 的值加上单引号；在 Windows PowerShell 中，将 " 转义为 """，以避免出现 code:500 错误。
4. 时间格式：alarm_time 必须遵循 yyyy/MM/dd HH:mm:ss GMT+X:XX（lakewatch 模式）或 yyyy-MM-ddTHH:mm:ss（manager 模式的 start_log_search）格式；在 lakewatch 模式下，对于非标准日志时间格式，请传入 time_pattern。
5. 总结结果：使用总结工具精简命令输出后再进行分析；不要直接分析大量原始输出。
6. 诊断后反思：完成检查后，反思是否已确认根本原因；如果尚未确认，请重新检查每项告警的处理流程，确认是否有遗漏步骤。
7. 只读：所有命令均为只读；修复步骤仅为建议，执行前需要用户确认。

参考资料

文档	说明
CLI 安装指南	Python 依赖项和 LakeWatch 客户端设置
IAM 策略	LakeWatch/MRS Manager 访问模型和所需角色
验证方法	安装、配置和功能验证
验收标准	技能测试的通过/失败标准
LakeWatch API 客户端	完整的 LakeWatch API 目录、参数、令牌和加密机制
MRS Manager API 客户端	完整的 MRS Manager API 目录、身份验证模式、指标名称和加密机制
相关命令	常用 LakeWatch/Manager API 命令速查
alarms/<alarm_id>.md	每项告警的诊断知识库（lakewatch 模式，与 MRS 产品告警目录一致）
alarm_manager/<alarm_id>.md	每项告警的诊断知识库（manager 模式，与 MRS 产品告警目录一致）

注意事项

• 安全性：此技能为只读。它不会泄露 LakeWatch 或 MRS Manager 密码；密码通过 --encrypt-password 加密，并存储在相应的配置 YAML 中。修复步骤仅为建议。
• 不使用 KooCLI：此技能不使用 hcloud；它通过 lakewatch_api_client.py 调用 LakeWatch API，或通过 manager_api_client.py 调用 MRS Manager REST API。不要混用 hcloud 命令。
• 模式切换：运行 check_api_mode.py 以确定模式。在 manager 模式下，使用 manager_api_client.py 和 alarm_manager/ 知识库；在 lakewatch 模式下，使用 lakewatch_api_client.py 和 alarms/ 知识库。不要跨模式混用客户端。
• 命令失败：命令失败时，跳过当前检查项并继续其他检查；不要中止整个诊断。
• 已知限制：access_manager_get 代理仅支持 GET 请求（Agent 端尚不支持 PUT）；collect_alarm_log_data 要求 log_directory 位于 /var/log/ 下；某些 strategy_name 值需要额外的 env 参数；在 manager 模式下，browse_log 要求提供完整的日志文件路径，且 start_log_search 的 services 必须遵循 component:service:role 格式。