huaweicloud/huawei-cloud-dws-io-diag

Huawei Cloud DWS I/O過負荷診断スキル

概要

このスキルは、DWSクラスターのI/O過負荷根本原因診断に特化しています。クラスターがI/O使用率過高アラームをトリガーすると、メトリクスデータを自動収集し、三段階の決定木を介して根本原因（顧客側/システム側）を分析し、標準化された診断レポートを出力します。

アーキテクチャ: KooCLI (hcloud) → DWS Autopilot API → クラスター監視メトリクス; MCPサーバー (dws_autopilot) → 同じAPIのフォールバックチャネル

適用シナリオ:

• DWSクラスターI/O使用率過高アラーム
• ディスクI/O負荷異常調査
• ユーザー発行のI/O診断リクエスト

典型的なユースケース:

• "DWSクラスターのI/O使用率が非常に高いので、診断してほしい"
• "I/Oアラームを受信した。クラスターIDはxxxです。原因を分析してほしい"
• "DWSクラスターのディスクutilが最大になっているので、原因を調べてほしい"

スキルの範囲と境界:

• サービス境界: このスキルはHuawei Cloud DWS（GaussDB(DWS)）データウェアハウスサービスのみをサポートします。ECS、RDS、CCEなどのDWS以外のサービスには適用されません。
• 問題タイプの境界: このスキルはDWSクラスターのI/O過負荷/I/O使用率過高/ディスクI/O負荷異常（I/O過負荷、I/O異常、高await、高utilなど）のみを診断します。CPU過負荷、メモリ高、その他のI/O以外の問題は処理しません（専用のCPU/メモリ診断スキルを参照）。
• 操作境界: このスキルは読み取り専用の診断です。クラスターの再起動、スケールアウト/イン、ノード交換、SQLの強制終了、パラメータ変更などの管理操作やメンテナンス操作は一切実行しません。

重要なルール: すべての診断結論は実際のツールの戻り結果に基づく必要があります。値を捏造したり推測したりすることは禁止されています。出力は診断レポートのみを含みます。改善提案の追加、SQL最適化ステートメントの出力、絵文字の使用は禁止されています。

背景知識: RAIDアーキテクチャ、I/O主要メトリクスのしきい値、3つの主要なI/Oシナリオ指標の特徴、および重要な原則は、I/O背景知識に文書化されています。診断前に必ず読んでください。

前提条件

1. CLI要件

• KooCLI (hcloud) >= 3.2.0
• インストールの確認: hcloud version
• インストールされていない場合やバージョンが低すぎる場合は、CLIインストールガイドを参照

2. MCPサーバー設定 (フォールバック)

• KooCLIが利用できない場合、代替手段としてMCPサーバーを使用
• MCPインストールガイドを参照

3. 認証設定

• 有効なHuawei Cloud認証情報（AK/SKモードまたはIAMトークン）
• セキュリティルール:
  • 会話やコマンドでAK/SKの値を公開しないでください
  • 会話内でユーザーにAK/SKを直接入力するように求めないでください
  • 認証情報の状態を確認するには、hcloud configure listのみを使用してください

4. IAM権限要件

• dws:clusters:get, dws:clusters:list
• dws:metricData:get, dws:hostOverview:get
• IAMポリシーを参照

KooCLIコマンド形式標準

コマンド形式

# メトリクスデータのクエリ
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>

# ホスト情報のクエリ
hcloud DWS ListHostOverview --cli-region=<region> --project_id=<pid> --cluster_id=<cid> --offset=0 --limit=200

ツール選択戦略

KooCLIとMCPサーバーから、KooCLIを優先して選択します。ステップ0でhcloudの可用性を確認します:

• hcloudが利用可能（バージョン >= 3.2.0）→ 以降のステップでKooCLIコマンドライン呼び出しを使用
• hcloudが利用不可（インストールされていないかバージョン < 3.2.0）→ 以降のステップでMCPサーバーツール呼び出しを使用

フォールバックと終了戦略:

• hcloudを選択後、最初の呼び出しがNETWORK_ERROR（接続タイムアウト、ネットワーク到達不能など）を返した場合、自動的にMCPサーバーにフォールバックし、以降のすべてのステップでMCPモードを使用
• hcloudがNETWORK_ERRORを返し、MCPサーバーも利用不可（設定されていないか、認証/接続エラーを返す）の場合、このスキルを終了し、KooCLIネットワークが利用不可で、MCPサーバー接続に失敗しました。KooCLIのネットワーク設定またはDWS Autopilot MCPサーバーの設定を確認して、再試行してくださいと出力
• MCPサーバーを選択後、最初の呼び出しが認証エラー（例: 401 Unauthorized）を返した場合、hcloudにフォールバックしないでください。このスキルを直接終了し、MCPサーバーの認証に失敗しました。DWS Autopilot MCPサーバーの認証設定を確認して、再試行してくださいと出力
• NETWORK_ERROR以外のhcloud呼び出し失敗（例: パラメータエラー、権限不足）はフォールバックをトリガーしません。既存の再試行ロジックに従います

ツールが選択されたら、切り替えずに全体を通して使用します（NETWORK_ERRORフォールバックを除く）。呼び出しが失敗した場合は、1回再試行します（最大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: IOStat, CpuStat, cpu_io_diagnose_detail, business_concurrency, business_query_monitor, business_thread_wait, bussiness_conflict_lock

時間プロトコル: from_ts/to_tsはUnixミリ秒のタイムスタンプを使用する必要があります。すべての時間はUTCタイムゾーンです。推奨時間枠: アラーム時間の5分前からアラーム時間まで（from_ts = first_alarm_time - 300000）。

戻り形式: 成功 {"code": 0, "data": [...]}; 失敗 {"code": -1, "message": "エラーの説明"}。失敗した場合は1回再試行します。それでも失敗する場合は、縮退パスを使用し、レポートで「利用不可」としてマークします。

メトリクスごとの主要フィールド:

• IOStat: ctime, host_id, disk_name, io_data{util, await, r_await, w_await, r_s, w_s, read_iops, write_iops, rMB_s, wMB_s, read_throughput, write_throughput, avgrq_sz, avgqu_sz} → コアI/Oメトリクス
• CpuStat: ctime, host_id, cpu_data{usr, sys, idle, iowait} → iowait > 30%は大きなI/Oプレッシャーを示す
• cpu_io_diagnose_detail: ctime, host_id, active_queries[{query, query_id, userName, cpu_rate, state, inst_name, duration_ms}], io_stats{read_iops, write_iops, read_throughput, write_throughput} → I/O診断詳細 + アクティブクエリ
• business_concurrency: ctime, concurrency_value, active_connections → ビジネス同時実行数
• business_query_monitor: ctime, query, query_id, username, duration_ms, host_id → 履歴リアルタイムクエリ
• business_thread_wait: ctime, wait_event, count, username, host_id → 待機イベント（wait wal sync、WALWriteLockなど）
• bussiness_conflict_lock: ctime, lock_type, blocker, waiter, username, host_id → ロック競合

各ステップのクエリの違いについては、メトリクスリファレンスを参照してください。

ページネーション仕様

すべてのツール呼び出し（MCPおよびhcloud）はページネーションクエリを使用する必要があります。これにより、単一の応答が大きくなりすぎてトークン制限を超えるのを防ぎます。

ページネーションルール:

• limit=200を一律で使用します（以下の宣言された例外を除き、200より大きい値は使用しないでください）
• 明示的な例外: cpu_io_diagnose_detailはlimit=800のページネーションを使用します（データ量が最も多く、マルチノード×マルチインスタンス×マルチタイムポイント×マルチクエリのため）; 200の単一ページでは不十分な場合があります
• 最初のページはoffset=0; 返されたデータ数 = limitの場合、offset+=limitしてクエリを続行
• 返されたデータ数 < limitになるまで繰り返し、すべてのページネーションデータをマージ
• マージする際は、すべてのページデータ配列を連結して完全なデータセットを作成

MCP呼び出し例 (IOStatを使用):

Page 1: dws_autopilot_get_metric(project_id, cluster_id, metric_name="IOStat", from_ts, to_ts, limit=200, offset=0)
返されたデータ長 = 200の場合:
Page 2: dws_autopilot_get_metric(project_id, cluster_id, metric_name="IOStat", from_ts, to_ts, limit=200, offset=200)
返されたデータ長 < 200の場合: ページネーションを停止し、ページ1 + ページ2のデータをマージ

hcloud呼び出し例 (IOStatを使用):

Page 1: hcloud DWS ListMetricsData --cli-region=<region> --cluster_id=<id> --metric_name=IOStat --project_id=<pid> --offset=0 --limit=200 --from=<from_ts> --to=<to_ts>
返されたデータ数 = 200の場合:
Page 2: hcloud DWS ListMetricsData --cli-region=<region> --cluster_id=<id> --metric_name=IOStat --project_id=<pid> --offset=200 --limit=200 --from=<from_ts> --to=<to_ts>
返されたデータ数 < 200の場合: ページネーションを停止し、データをマージ

ワークフロー

診断前に、ステップ0〜7に基づいて実行計画を作成し、順次実行します。ツール選択戦略については、「KooCLIコマンド形式標準」セクションを参照してください。以降のステップではこれを繰り返しません。すべてのMCPツール呼び出しは「ページネーション仕様」セクションに従います。以降のステップではページネーションの詳細を繰り返しません。

ステップ0: 環境検出とパラメータ解決

必須パラメータの検証: 続行する前に、cluster_idまたはcluster_nameの少なくとも1つが提供されていることを確認します（両方提供される場合もありますが、少なくとも1つは必須です）。両方とも欠落している場合は、ユーザーに有効なcluster_idまたはcluster_nameを提供するように促し、提供されるまで診断を終了します。

クラスター存在確認: クラスターリストクエリ（hcloudモードではhcloud DWS ListClusters、MCPモードではdws_autopilot_get_clusters）を使用して、ターゲットクラスターが存在することを確認します:

• クエリがエラーコードDWS.13026またはDWS.13032（クラスターが見つかりません）を返す場合、または返されたクラスターリストに指定されたcluster_id/cluster_nameが含まれていない場合 → クラスターは存在しません。診断を終了し、指定されたDWSクラスターは存在しません。cluster_id/cluster_nameを確認して再試行してくださいと促します。
• クエリが成功し、クラスターが存在する場合 → 次の手順に進みます。

パラメータ解決: project_idまたはregion_idがユーザーから提供されていない場合、MCPサーバー設定ファイルconf/dws_config.yamlから読み取ります:

• project_idがない場合: python -c "import yaml; c=yaml.safe_load(open('conf/dws_config.yaml')); print(c.get('project_id',''))"を実行して取得
• region_idがない場合: python -c "import yaml; c=yaml.safe_load(open('conf/dws_config.yaml')); print(c.get('region_id',''))"を実行して取得
• 設定ファイルの対応するフィールドも空の場合は、ユーザーにパラメータの提供を促します

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>）を実行してネットワーク接続を確認します:

• 正常に戻るか、ビジネスエラー（例: 権限不足、パラメータエラー）を返す → ネットワーク利用可能、tool_mode=hcloudを維持
• NETWORK_ERRORを返す → ネットワーク利用不可、tool_mode=mcpにフォールバック
• フォールバック後、MCPも利用不可の場合 → 実行を終了し、ユーザーにKooCLIネットワーク設定またはMCPサーバー設定を確認するように促します

ステップ1: IOStatのクエリ

メトリクス名="IOStat"、時間枠: from_ts=first_alarm_time - 300000、to_ts=first_alarm_timeでメトリクスクエリを呼び出します。MCPモードでは、limit=200のページネーションクエリを使用します。

Autopilot利用不可の判定: エラー50201/RDS.9999を返す場合 → ステップ1〜6をスキップし、すべてのメトリクスを「利用不可」としてマークし、直接ステップ7に進みます。

解析: host_idとdisk_nameでグループ化し、各ノードの各ディスクの最新のI/Oデータを見つけます。各ディスクのutil、await、r_await、w_await、r_s、w_s、read_iops、write_iops、rMB_s、wMB_s、read_throughput、write_throughput、avgrq_sz、avgqu_szを抽出します。

I/O過負荷の判定: いずれかのディスクでutil > 90%またはawait > 100、またはスループット/IOPSが上限に達しているかどうか。

I/O不均衡の判定: ノード間のutilまたはawaitの偏差が20%を超えているかどうか。

TOPノードのフィルタリング: I/O負荷が最も高い2つのノードを見つけます。

現象分布の判定: ノードに単一ディスクI/O高または全ディスクI/O高があるかどうか（ステップ4のシナリオルーティングに使用）。

高I/O時間ポイント: IOStat時系列データから、上位2つのI/Oノードでいずれかのディスクutil > 90%であるすべてのctimeポイントを見つけます。これらのctime値をhigh_io_ctimes（ミリ秒タイムスタンプのリスト）として収集します。また、utilが最も高いctimeをpeak_io_ctimeとして記録します。util > 90%のctimeがない場合、high_io_ctimesは空になり、peak_io_ctimeはutil値が最も高いctimeになります。

出力: io_by_host_disk、io_by_host、max_io_hosts、problem_host_id、problem_host_util、problem_host_await、problem_host_avgrq_sz、problem_host_avgqu_sz、cluster_avg_util、is_imbalanced、io_deviation、high_io_nodes、single_disk_high_nodes、all_disk_high_nodes、high_io_ctimes、peak_io_ctime

ステップ2: ホスト名の取得

ホスト情報クエリを呼び出し（MCPモードではlimit=200のページネーション）、host_id → {host_name, inst_num, inst_type}のマッピングを構築します。