huawei-cloud-mrs-host-alarm-diagnose

Huawei Cloud MRS アラーム診断スキル

概要

このスキルは、Huawei Cloud MRS（MapReduce Service）クラスターのアラームを診断します。アラーム情報（アラーム ID、アラーム名、発生時刻、クラスター ID、ノード、関連するサービス／ロール）を受け取ると、根本原因を特定し、修復手順と検証方法を出力します。

アーキテクチャ：呼び出し元（エージェント）→ 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 アカウント（ユーザー名＋パスワード）
• Manager のフローティング IP を server.host に設定します（デフォルトポートは 28443）。IP を取得するには、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 Client を参照してください。

4. アクセス権限

• Lakewatch モード：LakeWatch サービスエンドポイント（scripts/lakewatch_api_config.yaml の server.host／port で設定）への到達性が必要です。また、LakeWatch アカウントには、対象クラスタで MRS Manager プロキシを呼び出し、ノードのリソース／ログデータを収集する権限が必要です
• Manager モード：スクリプトの実行環境から Manager ポート 28443 に到達できる必要があります。また、Manager アカウントにはアラーム、ホスト、インスタンス、ログの各 API に対する読み取り権限が必要です
• アクセスモデルと必要なロールについては、IAM Policies を参照してください

コマンド形式の標準

このスキルでは、KooCLI の代わりに LakeWatch API クライアントを使用します。統一コマンド形式は次のとおりです。

# 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	key=value 形式の API パラメーター。繰り返し指定できます	-p 'cluster_id=xxx'
引用符	シェルによる `[] {}	()の解析を防ぐため、すべての-p` の値をシングルクォートで囲む必要があります

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 Client を参照してください。

MRS Manager API クライアント（Manager モード）

check_api_mode.py が manager を報告した場合は、LakeWatch クライアントの代わりに manager_api_client.py を使用します。統一コマンド形式は次のとおりです。

# 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	key=value 形式の API パラメーター。繰り返し指定できます	-p 'service_name=DBService'
--json	JSON 形式の出力	--json
--auth	認証モード：basic（デフォルト）または cookie	--auth cookie
引用符	LakeWatch クライアントと同じ引用符ルール（' で囲む。Windows では " → """）	-p 'keywords=["ERROR"]'

API カタログ、認証モード、メトリック名、パスワード暗号化の仕組みについて詳しくは、MRS Manager API Client を参照してください。

ワークフロー

ステップ 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 を読み取り、診断フローを確認します。また、Python スクリプトの使用方法については LakeWatch API Client を読みます。
• manager モード：このスキルディレクトリ内の alarm_manager/<alarm_id>.md を読み取り、診断フローを確認します。また、Python スクリプトの使用方法については MRS Manager API Client を読みます。

該当するアラームドキュメントがない場合は、ユーザーに 暂不支持此告警的分析。（このアラームの分析は現在サポートされていません。）と伝えます。

ステップ 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 で暗号化され、対応する config 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 の形式にする必要があります。