huawei-cloud-mrs-host-fault-diagnose

Huawei Cloud MRS ホスト障害診断スキル

概要

このスキルは Huawei Cloud MRS（MapReduce Service）クラスターの障害を診断します。サービス名やノード名を指定すると、根本原因を段階的に特定します。まずログを簡易スキャンし、ホストの問題が見つかった場合はホストのトラブルシューティングを行い、結論に至らない場合は詳細な調査を実施します。

アーキテクチャ：呼び出し元（エージェント） -> 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 モードでは fault_layer/ + scenarios/ + propagation.md、Manager モードでは fault_layer_manager/ + scenarios_manager/ + propagation_manager.md）が診断フローを制御します。コンポーネントごとの設定（components/）は両モードで共有されます。3 つの障害レイヤー（ホスト -> インスタンス -> サービス）と伝播チェーンの追跡に対応しています。

言語に関する注意：この SKILL.md と references/ 配下のドキュメントは、リポジトリの仕様に従って英語で記述されています。fault_layer/、fault_layer_manager/、scenarios/、scenarios_manager/、components/、propagation.md、propagation_manager.md 配下のナレッジベースドキュメントも英語です。コマンドとコードブロックもすべて英語です。

対象となるシナリオ：

• サービスに異常が報告され、根本原因の特定が必要な場合
• 特定のノード上のインスタンスに障害が報告された場合
• ホストに到達できない、または異常が報告された場合
• 簡易スキャンから詳細調査まで段階的に障害を切り分ける場合

一般的なユースケース：

• 「KrbServerに問題が発生しました。診断してください」（サービス障害、ノード指定なし）
• 「8-5-225-6上のKrbServerが停止しました」（インスタンス障害、サービスとノードを指定）
• 「8-5-225-6に問題が発生しました」（ホスト障害、ノードのみ）
• 「MRSクラスターのKrbServerが起動に失敗しました。クラスター ID は xxx です」
• 「DBServiceが異常停止しました。ノードは8-5-225-6です」

重要な制約

重要な制約：

1. 読み取り専用：このスキルは情報収集コマンド（ログの表示、ステータスの照会、リソースデータの収集）のみを実行します。起動、停止、変更、削除の操作は絶対に実行してはなりません。
2. 修復にはユーザーの確認が必要：このスキルは実行可能な修復案を提示するのみで、修復操作を直接実行してはなりません。すべての修復操作にはユーザーの確認が必要です。
3. 厳密な実行：このスキルディレクトリ内のナレッジベースの内容に厳密に従って診断してください。ナレッジベースにない診断コマンドを捏造することは禁止されています。

前提条件

1. Python の要件

• Python >= 3.7
• 依存関係：pyyaml（YAML 解析）、cryptography（Windows での AES パスワード暗号化のみ）
• Linux ではパスワード暗号化に CryptoAPI を使用するため、cryptography の依存関係はありません
• インストールの確認：python3 --version（Linux）／python --version（Windows）

このスキルでは KooCLI（hcloud）は必要ありません。LakeWatch モードでは scripts/lakewatch_api_client.py を通じて LakeWatch API を呼び出し、Manager モードでは scripts/manager_api_client.py を通じて MRS Manager REST API を呼び出します。クライアントのセットアップについては、CLI インストールガイドを参照してください。

2. LakeWatch 認証情報の設定

• 有効な LakeWatch サービスアカウント（ユーザー名 + パスワード）
• パスワードは --encrypt-password で暗号化し、scripts/lakewatch_api_config.yaml の auth.encrypted_password に保存する必要があります。平文のパスワードは保存しないでください。
• セキュリティルール：
  • LakeWatch のパスワードを会話やコマンド出力に表示しないでください
  • 会話中にユーザーに平文のパスワードを入力するよう求めないでください。対話型の --encrypt-password フローを使用してください
  • トークンは、所有者のみがアクセスできるファイル権限でローカルにキャッシュされます（Windows：%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 ポリシーを参照してください

5. 依存スキル：huawei-cloud-mrs-host-alarm-diagnose

このスキルは、huawei-cloud-mrs-host-alarm-diagnose スキル（skills/bigdata/mrs/ 配下の兄弟ディレクトリ）にある、アラームごとの診断ナレッジベースを参照します。障害診断フローで既知のアラーム（12006/12007/25000/25500/27001）が検出されると、Lakewatch モードでは ../huawei-cloud-mrs-host-alarm-diagnose/alarms/<alarm_id>.md、Manager モードでは ../huawei-cloud-mrs-host-alarm-diagnose/alarm_manager/<alarm_id>.md の対応するドキュメントを読み込みます。

• アラームスキルが存在する場合は、参照先のドキュメントを読み込み、その診断フローに従ってください
• 存在しない場合は、ユーザーに通知して一般的な障害診断フローを続行してください
• この依存関係はドキュメントレベルの参照のみ（相対パスで Markdown を読み込む）であり、スキルを直接呼び出すものではありません。両方のスキルは同じ LakeWatch／Manager API クライアントと設定形式を使用します。

コマンド形式の標準

このスキルでは 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 の値は必ずシングルクォートで囲みます	-p 'keywords=["ERROR"]'

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 を返す場合は、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=KrbServer'
--json	JSON 形式の出力	--json
--auth	認証モード：basic（デフォルト）または cookie	--auth cookie
引用符	LakeWatch クライアントと同じ引用符のルール（囲みには ' を使用。Windows では " → """）	-p 'keywords=["ERROR"]'

API カタログ、認証モード、メトリクス名、パスワード暗号化方式の詳細については、MRS Manager API クライアントを参照してください。

ワークフロー

ステップ 0：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

モードによって、ワークフロー全体で読み込むナレッジベースのディレクトリが決まります。

モード	コマンドスクリプト	障害レイヤー	シナリオ	伝播	アラームのドキュメント（関連スキル）
lakewatch	lakewatch_api_client.py	fault_layer/	scenarios/	propagation.md	../huawei-cloud-mrs-host-alarm-diagnose/alarms/
manager	manager_api_client.py	fault_layer_manager/	scenarios_manager/	propagation_manager.md	../huawei-cloud-mrs-host-alarm-diagnose/alarm_manager/

この SKILL.md の以降の部分では、<FAULT_LAYER> は fault_layer（lakewatch）または fault_layer_manager（manager）、<SCENARIOS> は scenarios（lakewatch）または scenarios_manager（manager）、<PROPAGATION> は propagation.md（lakewatch）または propagation_manager.md（manager）を表します。

ステップ 1：障害の入口を特定する

ユーザー入力から障害情報を抽出し、診断の入口を特定します。

ユーザーの説明	入口	ステップ 1 のアクション
service_name があり、node_name がない（例：「KrbServerに問題があります」）	サービス障害	すべてのインスタンスのステータスを確認し、障害のあるインスタンスを特定します
service_name と node_name がある（例：「8-5-225-6上のKrbServerが停止しました」）	インスタンス障害	該当インスタンスを直接確認します
node_name があり、service_name がない（例：「8-5-225-6に問題があります」）	ホスト障害	ホストのステータスを確認してから、そのホスト上のインスタンスを確認します

ステップ 2：障害オブジェクトを特定する

モードに関する注意：以下のコマンドブロックには、lakewatch モードのコマンドが示されています。manager モードでは、対応する manager_api_client.py コマンドを使用してください。モードごとの対応コマンドについては、コアコマンド -> Manager モードのコマンドおよび <SCENARIOS>/data_collection.md を参照してください。

入口 A：サービス障害（service_name があり、node_name がない）

コンポーネント設定を読み込むために components/<service_name>.md を読み込みます。OMS のアクティブ／スタンバイノードを照会し、各ノードのプロセスを確認します。

# lakewatch mode
python3 lakewatch_api_client.py -a query-management-node-info \
  -p 'cluster_id=<cluster_id>'

# lakewatch mode
python3 lakewatch_api_client.py -a collect_alarm_node_res_data \
  -p 'cluster_id=<cluster_id>' \
  -p 'strategy_name=process-basic-info' \
  -p 'env={"process_name":"<process_name>"}' \
  -p 'node_name=<node_name>'

manager モードでの対応：get_oms_info（OMS のアクティブ／スタンバイノード）、get_host_process（プロセスのステータス）。

判定：

結果	次のステップ
すべてのノードのプロセスが正常	ステップ 4：詳細調査
一部のノードでプロセスが見つからない	ステップ 3：ログのクイックスキャン（障害のあるノードが対象）
API 呼び出しに失敗（ノードに到達できない）	ステップ 4：ホストのトラブルシューティング

エントリー B：インスタンス障害（service_name と node_name がある場合）

components/<service_name>.md を読み込みます。そのノード上のプロセスを直接確認します。

# lakewatch mode
python3 lakewatch_api_client.py -a collect_alarm_node_res_data \
  -p 'cluster_id=<cluster_id>' \
  -p 'strategy_name=process-basic-info' \
  -p 'env={"process_name":"<process_name>"}' \
  -p 'node_name=<node_name>'

Manager モードでの同等機能：get_host_process（プロセスの状態）。

判断：

結果	次のステップ
プロセスは正常	ステップ 4 の詳細調査
プロセスが見つからない	ステップ 3 のログの簡易確認
API 呼び出しに失敗（ノードに到達できない）	ステップ 4 のホストのトラブルシューティング

エントリー C：ホスト障害（node_name があり、service_name がない場合）

OMS のプライマリ／スタンバイノードを照会し、ノード IP を取得して、OMS のアクティブノードから障害ノードに ping を実行します。

# lakewatch mode
python3 lakewatch_api_client.py -a query-management-node-info \
  -p 'cluster_id=<cluster_id>'

# lakewatch mode
python3 lakewatch_api_client.py -a query-node-ip \
  -p 'cluster_id=<cluster_id>' \
  -p 'node_name=<node_name>'

# lakewatch mode
python3 lakewatch_api_client.py -a collect_alarm_node_res_data \
  -p 'cluster_id=<cluster_id>' \
  -p 'strategy_name=ping-check' \
  -p 'env={"TARGET_IP":"<target_ip>"}' \
  -p 'node_name=<oms_active_node>'

Manager モードでの同等機能：get_oms_info（OMS のプライマリ／スタンバイ）；get_hosts -p 'hostname=<node_name>'（ノード IP）；check_remote（リモート接続性。ping 専用の確認 API はありません）。

判断：

結果	次のステップ
ping に失敗	ステップ 4 のホストのトラブルシューティング（ネットワーク／ハードウェア）
ping に成功	ホスト上のすべてのコンポーネントプロセスを確認し、障害インスタンスを特定します -> ステップ 3 のログの簡易確認

ステップ 3：ログの簡易確認

障害ノードで、3 層のログ（Controller -> NodeAgent -> コンポーネント）をすばやく確認し、明確な ERROR を探します。

# lakewatch mode - Controller log
python3 lakewatch_api_client.py -a collect_alarm_log_data \
  -p 'cluster_id=<cluster_id>' \
  -p 'alarm_time=<alarm_time>' \
  -p 'log_directory=/var/log/Bigdata/controller' \
  -p 'log_file_name=exe.log*' \
  -p 'keywords=["<service_name>","ERROR","fail","timeout","Exception"]' \
  -p 'log_type=local' \
  -p 'node_name=<oms_active_node>'

# lakewatch mode - NodeAgent script log
python3 lakewatch_api_client.py -a collect_alarm_log_data \
  -p 'cluster_id=<cluster_id>' \
  -p 'alarm_time=<alarm_time>' \
  -p 'log_directory=/var/log/Bigdata/nodeagent/scriptlog' \
  -p 'log_file_name=*.log*' \
  -p 'keywords=["<service_name>","ERROR","fail","exit"]' \
  -p 'log_type=local' \
  -p 'node_name=<node_name>'

Manager モードでの同等機能（<SCENARIOS>/data_collection.md を参照）：browse_log（Controller の exe.log、NodeAgent の script.log）；start_log_search + get_log_search_progress（キーワード検索）。

service_name がわかっている場合は、コンポーネント独自のログも確認します（パスは components/<service_name>.md を参照）。

# lakewatch mode
python3 lakewatch_api_client.py -a collect_alarm_log_data \
  -p 'cluster_id=<cluster_id>' \
  -p 'alarm_time=<alarm_time>' \
  -p 'log_directory=<log_directory>' \
  -p 'log_file_name=<log_file_name>' \
  -p 'keywords=["ERROR","Exception","FATAL","fail","OOM"]' \
  -p 'log_type=local' \
  -p 'node_name=<node_name>'

判断：

ログの結果	次のステップ
明確な ERROR（例：OOM／権限／ポートの競合／設定の欠落）	根本原因を出力
ログにノードへ到達できない、または Agent のタイムアウトが示されている	ステップ 4 のホストのトラブルシューティング
同一ホスト上に複数の障害ノードがある	ステップ 4 のホストのトラブルシューティング
明確な結論が得られない	ステップ 4 の詳細調査

ステップ 4：詳細調査

ログの簡易確認で結論が得られない場合は、完全なデータを収集します。

1. [データ収集](/data_collection.md) を読み込み、プロセス／ポート／HA／リソース／アラーム／フレームワークのログを収集します
2. [インスタンス障害の診断](<FAULT_LAYER>/instance_fault.md) を読み込み、インスタンスレベルの診断を行います（シナリオの特定を含みます）
3. 必要に応じて、[サービス障害の診断](<FAULT_LAYER>/service_fault.md) を読み込み、サービスレベルの診断を行います
4. ホストの問題が見つかった場合は、[ホスト障害の診断](<FAULT_LAYER>/host_fault.md) を読み込み、ホストレベルの診断を行います

ステップ 5：伝播チェーンの追跡

伝播チェーン を読み込み、根本原因の伝播経路と影響範囲を追跡します。

ステップ 6：診断結果の出力

## Diagnosis Result

| Item | Content |
|------|---------|
| Diagnosis time | [time] |
| Cluster ID | [cluster_id] |
| Faulty component | [service_name] |
| Faulty node | [node_name] |

### Diagnosis Process

| Step | Result |
|------|--------|
| Instance status | [which nodes normal/abnormal] |
| Quick log scan | [found/not found clear ERROR] |
| Host troubleshooting | [normal/abnormal: ...] |
| Detailed investigation | [process/port/HA/resource results] |

### Propagation Path

[root cause] -> [propagation] -> [symptom] (single-layer root cause if no propagation)

### Root Cause Analysis

**Root cause layer**: [host/instance/service]
**Root cause type**: [specific reason]

### Repair Suggestion

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

主なコマンド

OMS のプライマリ／スタンバイノードの照会

python3 lakewatch_api_client.py -a query-management-node-info \
  -p 'cluster_id=<cluster_id>'

ノード IP の照会

python3 lakewatch_api_client.py -a query-node-ip \
  -p 'cluster_id=<cluster_id>' \
  -p 'node_name=<node_name>'

ノードのリソースデータの収集

# Process basic info
python3 lakewatch_api_client.py -a collect_alarm_node_res_data \
  -p 'cluster_id=<cluster_id>' \
  -p 'strategy_name=process-basic-info' \
  -p 'env={"process_name":"<process_name>"}' \
  -p 'node_name=<node_name>'

# Port check
python3 lakewatch_api_client.py -a collect_alarm_node_res_data \
  -p 'cluster_id=<cluster_id>' \
  -p 'strategy_name=port-check' \
  -p 'env={"PORT":"<port>"}' \
  -p 'node_name=<node_name>'

# HA resource status
python3 lakewatch_api_client.py -a collect_alarm_node_res_data \
  -p 'cluster_id=<cluster_id>' \
  -p 'strategy_name=ha-resource-status' \
  -p 'node_name=<node_name>'

# Disk space / Memory / CPU load
python3 lakewatch_api_client.py -a collect_alarm_node_res_data \
  -p 'cluster_id=<cluster_id>' \
  -p 'strategy_name=disk-space' \
  -p 'node_name=<node_name>'

サポートされている strategy_name の値には、system-load、memory-usage、disk-space、disk-io、network-io、file-handle、port-check、high-cpu-processes、high-memory-process、zombie-process、dns-check、network-connectivity-test、process-basic-info、process-file-descriptor、jstack-thread-dump、disk-health-check、disk-smart-info、ha-resource-status、omm-process-tree などがあります。全リストについては、LakeWatch API クライアント を参照してください。

アラームログデータの収集

python3 lakewatch_api_client.py -a collect_alarm_log_data \
  -p 'cluster_id=<cluster_id>' \
  -p 'alarm_time=<alarm_time>' \
  -p 'log_directory=<log_directory>' \
  -p 'log_file_name=<log_file_name>' \
  -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 cluster services
python3 lakewatch_api_client.py -a access_manager_get \
  -p 'cluster_id=<cluster_id>' \
  -p 'target_url=api/v2/clusters/<cluster_id>/services'

# Query host processes
python3 lakewatch_api_client.py -a access_manager_get \
  -p 'cluster_id=<cluster_id>' \
  -p 'target_url=api/v2/clusters/<cluster_id>/hosts/<node_name>/processes'

# Query active alarms
python3 lakewatch_api_client.py -a access_manager_get \
  -p 'cluster_id=<cluster_id>' \
  -p 'target_url=api/v2/clusters/<cluster_id>/alarms'

target_url は / で始めてはなりません。プロキシには Agent >= 1.0.5 および報告済みの OMS ノード情報が必要です。現在サポートされているのは GET のみです。

Manager Mode コマンド（Manager Mode）

check_api_mode.py が manager を報告した場合は、同等のクエリに manager_api_client.py を使用します。

# Query OMS primary/standby nodes
python3 manager_api_client.py -a get_oms_info --json

# Query cluster services
python3 manager_api_client.py -a get_cluster_services \
  -p 'cluster_id=<cluster_id>' --json

# Query host detail (disk/memory/CPU usage)
python3 manager_api_client.py -a get_host_detail \
  -p 'hostname=<node_name>' --json

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

# Query service instances (HA status)
python3 manager_api_client.py -a get_instances \
  -p 'cluster_id=<cluster_id>' \
  -p 'service_name=<service_name>' \
  -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

# Check remote node connectivity (replaces ping-check/network-connectivity-test)
python3 manager_api_client.py -a check_remote \
  -p 'remote_ip=<target_ip>' \
  -p 'remote_port=22' \
  -p 'remote_user_name=omm' \
  -p 'remote_client_path=/opt/huawei/Bigdata/nodeagent' --json

# Browse a log file (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/exe.log' \
  -p 'start_line=1' \
  -p 'end_line=500' \
  -p 'search=<service_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=<component>:<service_name>:<role_name>' \
  -p 'min_log_level=WARN' --json

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

start_log_search の services 形式：component:service:role（例：HDFS:HDFS:NameNode）。start_time／end_time 形式：yyyy-MM-ddTHH:mm:ss。メトリック名とパラメーターの完全なルールについては、MRS Manager API Client を参照してください。

パラメーターの確認

パラメーター	必須／任意	説明	デフォルト
cluster_id	必須	MRS クラスター ID	N/A
service_name	条件付きで必須	障害のあるコンポーネント（サービス／インスタンスの障害エントリーで必須）	N/A
node_name	条件付きで必須	障害のあるノード（インスタンス／ホストの障害エントリーで必須）	N/A
alarm_time	任意	障害発生時刻。形式は yyyy/MM/dd HH:mm:ss GMT+X:XX	現在時刻
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||format（lakewatch モード）	N/A
target_url	access_manager_get で必須	MRS Manager API パス。/ で始めてはいけません（lakewatch モード）	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
file_name	browse_log で必須	ログファイルの完全なパス（manager モード）	N/A

出力形式

診断レポートは Markdown 形式で出力され、以下を含みます。

• 診断結果テーブル：診断時刻、クラスター ID、障害のあるコンポーネント、障害のあるノード
• 診断プロセス：各手順の結果（インスタンスのステータス、ログの簡易スキャン、ホストのトラブルシューティング、詳細調査）
• 伝播経路：根本原因 -> 伝播 -> 症状（伝播がない場合は単一レイヤー）
• 根本原因分析：根本原因のレイヤー（ホスト／インスタンス／サービス）＋根本原因の種類
• 修復提案テーブル：優先度、操作、説明、ユーザー確認の要否（すべての修復操作にユーザーの確認が必要です）

テンプレートについては、Workflow -> Step 6 セクションを参照してください。

検証方法

インストール、設定、機能の検証手順については、Verification Method を参照してください。

ベストプラクティス

1. 最初にエントリを特定する：ユーザーから提供された情報（service_name、node_name）に基づき、診断を開始する前に、対象がサービス障害、インスタンス障害、ホスト障害のいずれかを特定します。
2. 段階的に調査する：まずクイックログスキャン（ステップ 3）を必ず実施します。明確な結論に至らない場合にのみ、詳細調査（ステップ 4）に進みます。
3. プレースホルダーを置き換える：<cluster_id>、<alarm_time>、<node_name>、<target_ip>、<process_name> などは、ユーザーから提供された実際の値に置き換えます。値をハードコードしないでください。
4. パラメーターを引用符で囲む：-p の値は必ずシングルクォートで囲みます。Windows PowerShell では、code:500 エラーを避けるため、" を """ にエスケープします。
5. 時刻形式：alarm_time は yyyy/MM/dd HH:mm:ss GMT+X:XX の形式にする必要があります。標準以外のログ時刻形式の場合は、time_pattern を渡します。
6. 結果を要約する：分析前に要約ツールを使ってコマンド出力を簡潔にまとめます。大量の未加工の出力をそのまま分析しないでください。
7. 診断後に振り返る：チェックを完了したら、根本原因が確認できたかを振り返ります。確認できていない場合は、見落とした手順がないか再確認します。
8. 読み取り専用：すべてのコマンドは読み取り専用です。修復手順は提案に限り、実行前にユーザーの確認が必要です。
9. コマンド失敗時の処理：コマンドが失敗した場合は、現在のチェック項目をスキップし、他のチェックを続行します。診断全体を中断しないでください。

参考資料

ドキュメント	説明
CLI インストールガイド	Python の依存関係と LakeWatch／Manager クライアントのセットアップ
IAM ポリシー	LakeWatch／MRS Manager のアクセスモデルと必要なロール
検証方法	インストール、設定、関数の検証
受け入れ基準	スキルのテストにおける合格／不合格基準
障害診断ワークフロー	段階的な障害診断ワークフローの設計
LakeWatch API クライアント	LakeWatch API の全カタログ、パラメーター、トークンおよび暗号化の仕組み
MRS Manager API クライアント	MRS Manager API の全カタログ、認証モード、メトリクス名および暗号化の仕組み
関連コマンド	LakeWatch／Manager API の一般的なコマンドのクイックリファレンス
huawei-cloud-mrs-host-alarm-diagnose（関連スキル）	依存関係：アラームごとの診断ナレッジベース（lakewatch モードでは ../huawei-cloud-mrs-host-alarm-diagnose/alarms/<alarm_id>.md、manager モードでは alarm_manager/<alarm_id>.md）。詳細は「前提条件」セクション 5 を参照してください。
データ収集	データ収集の全フロー、lakewatch モード（ステップ 4）
データ収集（Manager）	データ収集の全フロー、manager モード（ステップ 4）
ホスト障害診断	ホストレイヤーの診断、lakewatch モード
インスタンス障害診断	インスタンスレイヤーの診断（シナリオの特定を含む）、lakewatch モード
サービス障害診断	サービスレイヤーの診断、lakewatch モード
ホスト障害診断（Manager）	ホストレイヤーの診断、manager モード
インスタンス障害診断（Manager）	インスタンスレイヤーの診断（シナリオの特定を含む）、manager モード
サービス障害診断（Manager）	サービスレイヤーの診断、manager モード
伝播チェーン	根本原因の伝播経路の追跡、lakewatch モード
伝播チェーン（Manager）	根本原因の伝播経路の追跡、manager モード
一般的なシナリオ	6 フェーズの一般的な診断フレームワーク、lakewatch モード
一般的なシナリオ（Manager）	6 フェーズの一般的な診断フレームワーク、manager モード
scenarios/<scenario>.md	シナリオ固有のチェック、lakewatch モード（install/start/stop/uninstall/reinstall/reinstall_host/scale_out/scale_in）
scenarios_manager/<scenario>.md	シナリオ固有のチェック、manager モード（install/start/stop/uninstall/reinstall/reinstall_host/scale_out/scale_in）
components/<service_name>.md	コンポーネントごとの設定（プロセス、ポート、ログパスなど）—両モードで共通
components/_template.md	新しいコンポーネント設定用のテンプレート

注意事項

• セキュリティ：このスキルは読み取り専用です。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（ステップ 0）を実行してモードを判定します。manager モードでは manager_api_client.py と fault_layer_manager/、scenarios_manager/、propagation_manager.md のナレッジベースを使用します。lakewatch モードでは lakewatch_api_client.py と fault_layer/、scenarios/、propagation.md を使用します。モード間でクライアントを混在させないでください。
• コマンドの失敗：コマンドが失敗した場合は、現在の確認項目をスキップして、ほかの確認を続行してください。診断全体を中止しないでください。
• 既知の制限事項：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 の形式に従う必要があります。また、一部の Manager バージョンでは get_alarms が 500 を返す場合があるため、その場合は Controller の exe.log の参照に切り替えてください。
• スキル間の依存関係：このスキルは、huawei-cloud-mrs-host-alarm-diagnose スキルのアラーム診断ドキュメント（lakewatch モードでは ../huawei-cloud-mrs-host-alarm-diagnose/alarms/<id>.md、manager モードでは alarm_manager/<id>.md）を参照します。依存関係の宣言と処理ルールについては、前提条件セクション 5 を参照してください。アラームスキルがインストールされていない場合は、その旨をユーザーに伝え、一般的な障害診断フローを続行してください。