Huawei Cloud DWS I/O 과부하 진단 스킬
개요
이 스킬은 DWS 클러스터 I/O 과부하 근본 원인 진단에 특화되어 있습니다. 클러스터에서 I/O 사용률 과다 알람이 트리거되면 자동으로 메트릭 데이터를 수집하고, 3단계 의사 결정 트리를 통해 원인(고객 측/시스템 측)을 분석하여 표준화된 진단 보고서를 출력합니다.
아키텍처: 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이 가득 찼습니다. 원인을 확인해 주세요"
스킬 범위 및 제한 사항:
- 서비스 범위: 이 스킬은 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 핵심 메트릭 임계값, 세 가지 주요 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 폴백 제외). 호출이 실패하면 한 번 재시도합니다(최대 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": "오류 설명"}. 실패 시 한 번 재시도합니다. 여전히 실패하면 저하 경로를 사용하고 보고서에 "사용 불가"로 표시합니다.
메트릭별 주요 필드:
- 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 → 대기 이벤트(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 사용):
페이지 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 서버 구성 파일 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 부하가 가장 높은 두 노드를 찾습니다.
현상 분포 확인: 노드에 단일 디스크 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 → {ho