華為雲 DWS I/O 過載診斷技能
概述
此技能專門用於 DWS 叢集 I/O 過載的根因診斷。當叢集觸發 I/O 使用率過高告警時，它會自動收集指標資料，透過三階段決策樹分析根因（客戶端 / 系統端），並輸出標準化診斷報告。
架構：KooCLI (hcloud) → DWS Autopilot API → 叢集監控指標；MCP Server (dws_autopilot) → 相同 API 的備援通道
適用場景：
- DWS 叢集 I/O 使用率過高告警
- 磁碟 I/O 負載異常排查
- 使用者主動發起的 I/O 診斷請求
典型使用案例：
- 「我的 DWS 叢集 I/O 使用率非常高，幫我診斷一下」
- 「收到 I/O 告警，叢集 ID 是 xxx，幫忙分析原因」
- 「DWS 叢集磁碟 util 被打滿了，看看是什麼原因」
技能範圍與邊界：
- 服務邊界：此技能僅支援華為雲 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 關鍵指標閾值、三大 I/O 場景指標特徵及重要原則，記載於 I/O 背景知識。診斷前必須閱讀。
先決條件
1. CLI 需求
- KooCLI (hcloud) >= 3.2.0
- 驗證安裝：
hcloud version - 若未安裝或版本過低，請參閱 CLI 安裝指南
2. MCP Server 配置（備援）
- 當 KooCLI 不可用時，使用 MCP Server 作為替代方案
- 請參閱 MCP 安裝指南
3. 認證配置
- 有效的華為雲憑證（AK/SK 模式或 IAM Token）
- 安全規則：
- 絕不在對話或命令中暴露 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 Server 之間進行選擇，優先使用 KooCLI。步驟 0 檢查 hcloud 可用性：
- hcloud 可用（版本 >= 3.2.0）→ 後續步驟使用 KooCLI 命令列呼叫
- hcloud 不可用（未安裝或版本 < 3.2.0）→ 後續步驟使用 MCP Server 工具呼叫
備援與終止策略：
- 選擇 hcloud 後，若首次呼叫回傳
NETWORK_ERROR（連線逾時、網路不可達等），自動備援至 MCP Server，並在後續所有步驟中使用 MCP 模式 - 若 hcloud 回傳 NETWORK_ERROR 且 MCP Server 亦不可用（未配置或回傳認證/連線錯誤），則終止此技能並輸出：
KooCLI 網路不可用且 MCP Server 連線失敗。請檢查 KooCLI 網路配置或 DWS Autopilot MCP Server 配置後重試 - 選擇 MCP Server 後，若首次呼叫回傳認證錯誤（例如 401 Unauthorized），不備援至 hcloud。直接終止此技能並輸出：
MCP Server 認證失敗。請檢查 DWS Autopilot MCP Server 認證配置後重試 - 非 NETWORK_ERROR 的 hcloud 呼叫失敗（例如參數錯誤、權限不足）不觸發備援；遵循現有重試邏輯
一旦選定工具，全程使用（除了 NETWORK_ERROR 備援）。若呼叫失敗，重試一次（最多 2 次嘗試）。若仍失敗，將該指標標記為「不可用」並繼續下一步。當所有指標查詢都失敗時，直接生成診斷報告。
參數對應表
| 常用參數 | hcloud 參數 | MCP 參數 |
|---|---|---|
| 區域 (Region) | --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": "error description"}。失敗時重試一次；若仍失敗，使用降級路徑並在報告中標記為「不可用」。
各指標關鍵欄位：
- 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）必須使用分頁查詢，以防止單次回應過大而超過 Token 限制。
分頁規則：
- 統一使用
limit=200（請勿使用大於 200 的值，除非是下面聲明的例外情況） - 明確例外：
cpu_io_diagnose_detail使用limit=800分頁（因其資料量最大，多節點 × 多實例 × 多時間點 × 多查詢）；單頁 200 可能不足 - 第一頁
offset=0；若回傳資料數量 = limit，則offset+=limit並繼續查詢 - 重複直到回傳資料數量 < limit，然後合併所有分頁資料
- 合併時，將所有頁面的資料陣列串接成一個完整的資料集
MCP 呼叫範例（使用 IOStat）：
第 1 頁：dws_autopilot_get_metric(project_id, cluster_id, metric_name="IOStat", from_ts, to_ts, limit=200, offset=0)
若回傳資料長度 = 200：
第 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）：
第 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：
第 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 其中之一（兩者皆可提供，但至少一個為必填）。若兩者皆缺失，提示使用者提供有效的 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 Server 設定檔 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 Server 配置
步驟 1：查詢 IOStat
調用指標查詢，metric_name="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 或 throughput/IOPS 達到上限。
I/O 不均衡判定：節點間 util 或 await 的偏差 > 20%。
TOP 節點過濾：找出 I/O 負載最高的兩個節點。
現象分佈判定：節點屬於單磁碟 I/O 高還是所有磁碟 I/O 高（用於步驟 4 場景路由）。
高 I/O 時間點：從 IOStat 時間序列資料中，找出 TOP 2 I/O 節點上任一磁碟 util > 90% 的所有 ctime 時間點。將這些 ctime 值收集為 high_io_ctimes（毫秒時間戳列表）。同時記錄 util 最高的 ctime 作為 peak_io_ctime。若無 ctime 的 util > 90%，則 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 → 主機名稱的對應。
步驟 3：查詢 CpuStat
調用指標查詢，metric_name="CpuStat"，時間視窗：from_ts=first_alarm_time - 300000，to_ts=first_alarm_time。MCP 模式使用 limit=200 分頁。
解析：按 host_id 分組，提取每個節點的 cpu_data（usr、sys、idle、iowait）。
iowait 判定：分析 TOP 2 I/O 節點的 iowait 趨勢：
- 若 io_wait > 30% 持續超過 1 分鐘 → 判定為 iowait 偏高
高 I/O 時間點 CPU 相關性：檢查 high_io_ctimes 中是否存在 iowait > 30% 的 ctime。記錄爲 high_io_cpu_ctimes（既在 high_io_ctimes 中、又 iowait > 30% 的 ctime 列表）。
輸出：host_cpu_data、io_wait_high_hosts、iowait_high_nodes、high_io_cpu_ctimes
步驟 4：場景路由
基於步驟 1 的 IOStat 現象分佈判定結果進行路由：
- 所有磁碟 I/O 高 → 假設爲系統端問題（硬碟或 RAID 瓶頸），直接跳至步驟 6
- 單磁碟 I/O 高 → 假設有客戶端問題（特定 SQL 或進程導致），繼續步驟 5 以查詢活躍查詢詳情
所有診斷結論均爲假設，需要在步驟 6 藉由 cpu_io_diagnose_detail 進行驗證。
步驟 5：查詢業務指標
對於「單磁碟高」場景，查詢以下指標：
cpu_io_diagnose_detail：取得活躍查詢詳情（limit=800 分頁）business_concurrency：業務並發情況（limit=200 分頁）business_query_monitor：歷史即時查詢（limit=200 分頁）business_thread_wait：執行緒等待事件（limit=200 分頁）bussiness_conflict_lock：鎖衝突（limit=200 分頁）
時間視窗：from_ts=first_alarm_time - 300000，to_ts=first_alarm_time。所有指標均使用分頁查詢。
聚焦分析：時間範圍限定在 high_io_ctimes 內（若 high_io_ctimes 爲空，則使用整個時間視窗）。從 cpu_io_diagnose_detail 中提取 I/O 最高的頂部實例的 active_queries 列表。
輸出：
- 活躍查詢列表（按實例分組）
- 最耗 I/O 的查詢
- 並發連線數
- 等待事件統計
- 鎖衝突詳細資訊
步驟 6：查詢 cpu_io_diagnose_detail
調用指標查詢，metric_name="cpu_io_diagnose_detail"，時間視窗：from_ts=first_alarm_time - 300000，to_ts=first_alarm_time。MCP 模式使用 limit=800 分頁。
若高 I/O 時間點的 high_io_cpu_ctimes 非空：
- 對於每個 high_io_cpu_ctime 時間點，篩選出 cpu_io_diagnose_detail 中該時間點下的 active_queries
- 僅保留 TOP 2 I/O 節點的查詢
- 分析執行時間最長的查詢（duration_ms 最高）
- 檢查是否存在佔用 CPU 較高的查詢
若 high_io_cpu_ctimes 爲空：
- 對 peak_io_ctime 時間點進行上述分析
輸出：
- TOP 2 I/O 節點上最耗時的前 5 個查詢（按 duration_ms 排序）
- 最耗 I/O 的查詢（如果 active_queries 中提供了 IO 統計資料）
- 查詢狀態分佈（running、waiting 等）
步驟 7：生成診斷報告
將步驟 1-6 發現的結果整合成結構化報告。報告應包含以下章節：
叢集概覽
- 叢集 ID
- 叢集名稱
- 診斷時間範圍
I/O 負載分析
- 叢集平均 util
- 最高 util 節點及其值
- 最高 await 節點及其值
- 是否不均衡（偏差值）
根因分析
根據三階段決策樹邏輯：
第一階段：I/O 過載判定
- 基於 IOStat（步驟 1）判定是否過載
- 結果：過載 / 未過載
第二階段：現象分類
- 所有磁碟高 vs 單磁碟高
- 結果：系統端現象（所有磁碟高） / 客戶端現象（單磁碟高）
第三階段：根因驗證
- 使用 cpu_io_diagnose_detail（步驟 6）和 iowait（步驟 3）進行驗證
- 若爲「所有磁碟高」且 iowait > 30% → 根因：系統端（磁碟陣列瓶頸）
- 若爲「所有磁碟高」且 iowait <= 30% → 根因：系統端（硬體 I/O 上限）
- 若爲「單磁碟高」且發現耗 I/O 查詢 → 根因：客戶端（特定 SQL 導致）
- 若爲「單磁碟高」且未發現特定查詢 → 根因：客戶端（並發或鎖競爭導致）
關鍵指標摘要
- 按節點列出 util、await、iowait
- 等待事件摘要
- 鎖衝突摘要（若有）
發現的活躍查詢
- TOP 5 耗時查詢（若有）
- 每個查詢的執行時間和狀態
原始資料備註
- 任何不可用指標的列表
- 任何降級或失敗的查詢呼叫
輸出格式要求：使用純文字（無 Markdown 表格以外的渲染），無表情符號、無建議。