huaweicloud/huawei-cloud-dws-io-diag

Skill de Diagnóstico de Sobrecarga de I/O de DWS de Huawei Cloud

Descripción General

Esta skill está dedicada al diagnóstico de causa raíz de sobrecarga de I/O en clústeres DWS. Cuando un clúster activa una alarma de uso de I/O demasiado alto, recopila automáticamente datos de métricas, analiza las causas raíz (del lado del cliente / del lado del sistema) mediante un árbol de decisión de tres etapas y genera un informe de diagnóstico estandarizado.

Arquitectura: KooCLI (hcloud) → API de DWS Autopilot → Métricas de monitoreo del clúster; Servidor MCP (dws_autopilot) → Canal de respaldo para la misma API

Escenarios Aplicables:

• Alarma de uso de I/O demasiado alto en clúster DWS
• Investigación de anomalías de carga de I/O de disco
• Solicitud de diagnóstico de I/O iniciada por el usuario

Casos de Uso Típicos:

• "El uso de I/O de mi clúster DWS es muy alto, ayuda a diagnosticar"
• "Recibí una alarma de I/O, el ID del clúster es xxx, ayuda a analizar la causa"
• "El util del disco del clúster DWS está al máximo, mira qué lo está causando"

Alcance y Límites de la Skill:

• Límite de servicio: Esta skill solo admite el servicio de almacenamiento de datos DWS (GaussDB(DWS)) de Huawei Cloud. NO se aplica a servicios que no sean DWS como ECS, RDS, CCE u otros.
• Límite de tipo de problema: Esta skill solo diagnostica sobrecarga de I/O / uso de I/O demasiado alto / anomalía de carga de I/O de disco en clústeres DWS (sobrecarga de I/O, anomalía de I/O, await alto, util alto, etc.). NO maneja sobrecarga de CPU, memoria alta u otros problemas que no sean de I/O (consulte las skills de diagnóstico de CPU/memoria dedicadas).
• Límite de operación: Esta skill es de solo lectura para diagnóstico. NO ejecuta ninguna operación de gestión o mantenimiento como reinicio del clúster, escalado horizontal, reemplazo de nodos, finalización de SQL o modificación de parámetros.

Reglas Importantes: Todas las conclusiones de diagnóstico deben provenir de resultados reales de las herramientas. Está prohibido inventar o asumir valores. La salida solo debe contener el informe de diagnóstico; agregar sugerencias de corrección, generar sentencias de optimización SQL y usar emojis está prohibido.

Conocimientos Previos: La arquitectura RAID, los umbrales de métricas clave de I/O, las características de los indicadores de los tres grandes escenarios de I/O y los principios importantes están documentados en Conocimientos Previos de I/O. Debe leerse antes del diagnóstico.

Requisitos Previos

1. Requisitos de CLI

• KooCLI (hcloud) >= 3.2.0
• Verificar instalación: hcloud version
• Si no está instalado o la versión es demasiado baja, consulte Guía de Instalación de CLI

2. Configuración del Servidor MCP (Respaldo)

• Cuando KooCLI no esté disponible, use el Servidor MCP como alternativa
• Consulte Guía de Instalación de MCP

3. Configuración de Autenticación

• Credenciales válidas de Huawei Cloud (modo AK/SK o IAM Token)
• Reglas de Seguridad:
  • Nunca exponga los valores de AK/SK en conversaciones o comandos
  • Nunca pida a los usuarios que ingresen AK/SK directamente en la conversación
  • Solo use hcloud configure list para verificar el estado de las credenciales

4. Requisitos de Permisos IAM

• dws:clusters:get, dws:clusters:list
• dws:metricData:get, dws:hostOverview:get
• Consulte Políticas IAM

Estándar de Formato de Comandos KooCLI

Formato del Comando

# Consultar datos de métricas
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>

# Consultar información del host
hcloud DWS ListHostOverview --cli-region=<region> --project_id=<pid> --cluster_id=<cid> --offset=0 --limit=200

Estrategia de Selección de Herramientas

Elija entre KooCLI y el Servidor MCP, prefiriendo KooCLI. El Paso 0 verifica la disponibilidad de hcloud:

• hcloud disponible (versión >= 3.2.0) → Use llamadas de línea de comandos de KooCLI para pasos posteriores
• hcloud no disponible (no instalado o versión < 3.2.0) → Use llamadas a herramientas del Servidor MCP para pasos posteriores

Estrategia de Respaldo y Terminación:

• Después de seleccionar hcloud, si la primera llamada devuelve NETWORK_ERROR (tiempo de espera de conexión, red inalcanzable, etc.), retroceda automáticamente al Servidor MCP y use el modo MCP para todos los pasos posteriores
• Si hcloud devuelve NETWORK_ERROR y el Servidor MCP tampoco está disponible (no configurado o devuelve error de autenticación/conexión), termine esta skill y genere: Red de KooCLI no disponible y conexión al Servidor MCP fallida. Verifique la configuración de red de KooCLI o la configuración del Servidor MCP de DWS Autopilot y vuelva a intentarlo
• Después de seleccionar el Servidor MCP, si la primera llamada devuelve un error de autenticación (por ejemplo, 401 No autorizado), no retroceda a hcloud. Termine esta skill directamente y genere: Autenticación del Servidor MCP fallida. Verifique la configuración de autenticación del Servidor MCP de DWS Autopilot y vuelva a intentarlo
• Las fallas de llamada a hcloud que no sean NETWORK_ERROR (por ejemplo, errores de parámetros, permisos insuficientes) no activan el respaldo; siga la lógica de reintento existente

Una vez seleccionada una herramienta, úsela durante todo el proceso sin cambiar (excepto para el respaldo por NETWORK_ERROR). Si una llamada falla, reintente una vez (máximo 2 intentos). Si sigue fallando, marque la métrica como "no disponible" y continúe con el siguiente paso. Cuando todas las consultas de métricas fallen, genere el informe de diagnóstico directamente.

Mapeo de Parámetros

Parámetro Común	Parámetro hcloud	Parámetro MCP
Región	--cli-region	(integrado en la conexión MCP)
ID del Proyecto	--project_id	project_id
ID del Clúster	--cluster_id	cluster_id
Nombre de la Métrica	--metric_name	metric_name
Hora de Inicio	--from	from_ts
Hora de Fin	--to	to_ts
Desplazamiento de Paginación	--offset	offset
Límite de Paginación	--limit	limit
Campo de Ordenación	(no compatible)	order_by
Dirección de Ordenación	(no compatible)	sort_by

Herramientas MCP

Nombre de la Herramienta	Propósito	Parámetros Clave
dws_autopilot_get_clusters	Consultar lista de clústeres	project_id, cluster_id, limit, offset
dws_autopilot_get_hosts	Consultar información del host	project_id, cluster_id, limit, offset
dws_autopilot_get_metric	Consultar datos de métricas	project_id, cluster_id, metric_name, from_ts, to_ts, limit, offset, order_by, sort_by

Notas sobre el Parámetro metric_data: metric_data no admite filtrado por instance_name (no existe tal parámetro); la consulta devuelve datos completos del clúster y debe filtrarse por el campo inst_name para las instancias de destino; metric_data no admite el parámetro period (el período de muestreo lo determina automáticamente la plataforma).

metric_name disponibles: IOStat, CpuStat, cpu_io_diagnose_detail, business_concurrency, business_query_monitor, business_thread_wait, bussiness_conflict_lock

Protocolo de Tiempo: from_ts/to_ts deben usar marcas de tiempo Unix en milisegundos; todas las horas están en la zona horaria UTC; ventana de tiempo recomendada: desde 5 minutos antes de la hora de la alarma hasta la hora de la alarma (from_ts = first_alarm_time - 300000).

Formato de Retorno: Éxito {"code": 0, "data": [...]}; Fracaso {"code": -1, "message": "descripción del error"}. En caso de fracaso, reintente una vez; si sigue fallando, use la ruta de degradación y marque como "no disponible" en el informe.

Campos Clave por Métrica:

• 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} → métricas principales de I/O
• CpuStat: ctime, host_id, cpu_data{usr, sys, idle, iowait} → iowait > 30% indica presión de I/O significativa
• 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} → detalles de diagnóstico de I/O + consultas activas
• business_concurrency: ctime, concurrency_value, active_connections → concurrencia empresarial
• business_query_monitor: ctime, query, query_id, username, duration_ms, host_id → consultas históricas en tiempo real
• business_thread_wait: ctime, wait_event, count, username, host_id → eventos de espera (wait wal sync, WALWriteLock, etc.)
• bussiness_conflict_lock: ctime, lock_type, blocker, waiter, username, host_id → conflictos de bloqueo

Para diferencias de consulta por paso, consulte Referencia de Métricas.

Especificación de Paginación

Todas las llamadas a herramientas (MCP y hcloud) deben usar consultas paginadas para evitar que las respuestas individuales sean demasiado grandes y excedan los límites de tokens.

Reglas de Paginación:

• Use limit=200 de manera uniforme (no use valores mayores a 200, excepto la excepción declarada a continuación)
• Excepción explícita: cpu_io_diagnose_detail usa paginación con limit=800 (debido a su volumen de datos más grande, múltiples nodos × múltiples instancias × múltiples puntos de tiempo × múltiples consultas); una página única de 200 puede no ser suficiente
• Primera página offset=0; si el número de datos devueltos = limit, entonces offset+=limit y continúe consultando
• Repita hasta que el número de datos devueltos < limit, luego combine todos los datos paginados
• Al combinar, concatene todos los arreglos de datos de todas las páginas en un conjunto de datos completo

Ejemplo de Llamada MCP (usando IOStat):

Página 1: dws_autopilot_get_metric(project_id, cluster_id, metric_name="IOStat", from_ts, to_ts, limit=200, offset=0)
Si la longitud de los datos devueltos = 200:
Página 2: dws_autopilot_get_metric(project_id, cluster_id, metric_name="IOStat", from_ts, to_ts, limit=200, offset=200)
Si la longitud de los datos devueltos < 200: Detenga la paginación, combine los datos de la página 1 + página 2

Ejemplo de Llamada hcloud (usando IOStat):

Página 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>
Si el número de datos devueltos = 200:
Página 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>
Si el número de datos devueltos < 200: Detenga la paginación, combine los datos

Flujo de Trabajo

Antes del diagnóstico, cree un plan de ejecución basado en los Pasos 0-7, luego ejecute secuencialmente. Para la estrategia de selección de herramientas, consulte la sección "Estándar de Formato de Comandos KooCLI"; los pasos posteriores no repetirán esto. Todas las llamadas a herramientas MCP siguen la "Especificación de Paginación"; los pasos posteriores no repetirán los detalles de paginación.

Paso 0: Detección del Entorno y Resolución de Parámetros

Validación de Parámetros Requeridos: Antes de continuar, verifique que al menos uno de cluster_id o cluster_name esté proporcionado (ambos pueden ser proporcionados, pero al menos uno es obligatorio). Si faltan ambos, solicite al usuario que proporcione un cluster_id o cluster_name válido y termine el diagnóstico hasta que se proporcione.

Validación de Existencia del Clúster: Use la consulta de lista de clústeres (hcloud DWS ListClusters en modo hcloud, o dws_autopilot_get_clusters en modo MCP) para confirmar que el clúster de destino existe:

• Si la consulta devuelve los códigos de error DWS.13026 o DWS.13032 (clúster no encontrado), o la lista de clústeres devuelta no contiene el cluster_id/cluster_name especificado → el clúster no existe. Termine el diagnóstico y solicite: El clúster DWS especificado no existe. Verifique el cluster_id/cluster_name y vuelva a intentarlo.
• Si la consulta tiene éxito y el clúster existe → continúe con los siguientes pasos.

Resolución de Parámetros: Si el usuario no proporciona project_id o region_id, lea del archivo de configuración del Servidor MCP conf/dws_config.yaml:

• Cuando falta project_id: Ejecute python -c "import yaml; c=yaml.safe_load(open('conf/dws_config.yaml')); print(c.get('project_id',''))" para obtenerlo
• Cuando falta region_id: Ejecute python -c "import yaml; c=yaml.safe_load(open('conf/dws_config.yaml')); print(c.get('region_id',''))" para obtenerlo
• Si el campo correspondiente en el archivo de configuración también está vacío, solicite al usuario que proporcione el parámetro

Ejecute hcloud version; versión >= 3.2.0 → tool_mode=hcloud, de lo contrario tool_mode=mcp.

Sonda de Disponibilidad de Red de hcloud: Si tool_mode=hcloud, ejecute una llamada API ligera (por ejemplo, hcloud DWS ListClusters --cli-region=<region> --project_id=<project_id>) para verificar la conectividad de red:

• Devuelve normal o error empresarial (por ejemplo, permisos insuficientes, error de parámetros) → Red disponible, mantenga tool_mode=hcloud
• Devuelve NETWORK_ERROR → Red no disponible, retroceda a tool_mode=mcp
• Después del respaldo, si MCP tampoco está disponible → Termine la ejecución, solicite al usuario que verifique la configuración de red de KooCLI o la configuración del Servidor MCP

Paso 1: Consultar IOStat

Llame a la consulta de métricas con metric_name="IOStat", ventana de tiempo: from_ts=first_alarm_time - 300000, to_ts=first_alarm_time. En modo MCP, use consulta paginada con limit=200.

Determinación de No Disponibilidad de Autopilot: Devuelve error 50201/RDS.9999 → Omita los Pasos 1-6, marque todas las métricas como "no disponible", proceda directamente al Paso 7.

Análisis: Agrupe por host_id y disk_name, encuentre los datos de I/O más recientes para cada disco en cada nodo. Extraiga 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 para cada disco.

Determinación de Sobrecarga de I/O: Si algún disco tiene util > 90% o await > 100 o rendimiento/IOPS alcanzando el límite superior.

Determinación de Desequilibrio de I/O: Si la desviación de util o await entre nodos > 20%.

Filtrado de Nodos TOP: Encuentre los dos nodos con la carga de I/O más alta.

Determinación de Distribución del Fenómeno: Si un nodo tiene I/O alto de un solo disco o I/O alto de todos los discos (utilizado para el enrutamiento de escenarios del Paso 4).

Puntos de Tiempo de I/O Alto: A partir de los datos de la serie temporal de IOStat, encuentre todos los puntos ctime donde cualquier disco tenga util > 90% en los 2 nodos principales de I/O. Recoja estos valores ctime como high_io_ctimes (lista de marcas de tiempo en milisegundos). También registre el ctime con el util más alto como peak_io_ctime. Si ningún ctime tiene util > 90%, high_io_ctimes está vacío y peak_io_ctime es el ctime con el valor de util más alto.

Salida: 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

Paso 2: Obtener Nombres de Hosts

Llame a la consulta de información del host (modo MCP con limit=200 paginado), construya el mapeo host_id → {host_name, host_type, az_id, ip_address, cpu_cores, memory_mb}. Si algún host falla, devuelva el nombre del host como unknown_<host_id>.

Salida: host_id_to_info (diccionario, clave: host_id, valor: información detallada del host)

Paso 3: Consultar cpu_io_diagnose_detail

Para cada host en high_io_nodes (hasta 2 hosts), llame a la consulta de métricas con metric_name="cpu_io_diagnose_detail". Use limit=800 paginado. Ventana de tiempo: from_ts=peak_io_ctime - 10000, to_ts=peak_io_ctime + 10000 (10 segundos alrededor del pico).

Si high_io_ctimes no está vacío, para cada ctime en high_io_ctimes (hasta 2 puntos de tiempo, priorizando los que tengan util más alto), para cada host en high_io_nodes (hasta 2 hosts), llame a la consulta de métricas con metric_name="cpu_io_diagnose_detail". Use limit=800 paginado. Ventana de tiempo: from_ts=ctime - 10000, to_ts=ctime + 10000.

Análisis: Extraiga active_queries para cada instancia en cada host. Analice los campos de consulta como query, query_id, userName, cpu_rate, state, inst_name, duration_ms. Calcule el número de consultas activas, consultas clasificadas por estado, clasificación por userName.

Salida: active_queries_by_host_and_time. active_query_count, query_state_distribution, user_query_count_map

Paso 4: Consultar business_concurrency

Para peak_io_ctime, llame a la consulta de métricas con metric_name="business_concurrency", ventana de tiempo: from_ts=peak_io_ctime - 120000, to_ts=peak_io_ctime + 60000. Use limit=200 paginado.

Análisis: Extraiga la tendencia de concurrency_value y active_connections. Calcule la concurrencia máxima, la concurrencia promedio y active_connections correspondientes. Los datos históricos de business_concurrency se pueden usar para verificar si el pico actual es normal.

Salida: max_concurrency, avg_concurrency, avg_active_connections

Paso 5: Consultar business_query_monitor

Para peak_io_ctime, llame a la consulta de métricas con metric_name="business_query_monitor", ventana de tiempo: from_ts=peak_io_ctime - 120000, to_ts=peak_io_ctime + 60000. Use limit=200 paginado.

Análisis: Extraiga la lista de consultas activas en el momento pico. Cuente top 10 por duración, top 10 por número de ocurrencias.

Salida: top_queries_by_duration (top 10), top_queries_by_frequency (top 10), total_query_count

Paso 6: Consultar business_thread_wait y bussiness_conflict_lock

Determine el escenario de carga empresarial basado en single_disk_high y all_disk_high:

Enrutamiento de Escenario:

• Escenario A: Todos los discos altos: Salte esta métrica directamente. Para el diagnóstico, vaya directamente al Escenario A (los altos de todos los discos generalmente son causados por el lado del sistema, como problemas de caché de página del sistema operativo, etc., que pueden tener métricas relacionadas con I/O del sistema operativo) → salte al paso 7
• Escenario B: Disco único alto y puede tener un problema de carga empresarial: Consulte business_thread_wait y bussiness_conflict_lock

Para el Escenario B:

1. Llame a la consulta de métricas con metric_name="business_thread_wait", ventana de tiempo: from_ts=peak_io_ctime - 120000, to_ts=peak_io_ctime + 60000. Use limit=200 paginado. Extraiga wait_event, count, username, host_id. Ordene por count descendente, tome top 10.

2. Llame a la consulta de métricas con metric_name="bussiness_conflict_lock", ventana de tiempo: from_ts=peak_io_ctime - 120000, to_ts=peak_io_ctime + 60000. Use limit=200 paginado. Extraiga lock_type, blocker, waiter, username, host_id.

Determinación de Tormenta de Consultas: Active_queries_count en el nodo problemático excede el umbral (por ejemplo, > 50 consultas activas simultáneas, esto debe ajustarse según el número de núcleos de CPU del host; se recomienda referirse a core_count * 3), y la mayoría de las consultas están en estado 'running' o 'active'. Si se cumplen estas condiciones, se considera una Tormenta de Consultas.

Determinación de Contención de Bloqueos: Si el recuento de wait_event relacionado con bloqueos (por ejemplo, WALWriteLock, RelationLock) en business_thread_wait supera un cierto umbral (por ejemplo, > 30% del total de eventos de espera), o los registros de bussiness_conflict_lock tienen un número significativo de conflictos de bloqueo, se considera Contención de Bloqueos.

Salida: thread_wait_top10, lock_conflicts, is_query_storm, is_lock_contention

Paso 7: Generación del Informe de Diagnóstico

Reglas de Generación del Informe:

• Genere el informe estrictamente de acuerdo con la plantilla a continuación
• Cuando un campo de diagnóstico no tenga datos, márquelo como "N/A"
• Si anomalías de datos o fallas de herramientas hacen que los juicios de diagnóstico no puedan completarse, indíquelo claramente en el informe
• Cualquier mención de valores o rangos anormales debe citar el valor medido real, el valor umbral y el sesgo
• Prohibición del informe: no incluya contenido como sugerencias de optimización, medidas de mitigación o soluciones. Si necesita sugerencias, primero genere y genere el informe de diagnóstico, luego genere una referencia cruzada de las reglas de sugerencias de optimización
• Sin emojis

Plantilla del Informe de Diagnóstico:

=== Informe de Diagnóstico de I/O de Clúster DWS ===

[Tiempo de Diagnóstico]: <marca de tiempo actual>
[ID del Clúster]: <ID del clúster>
[Nombre del Clúster]: <nombre del clúster | N/A>
[Región]: <región>
[ID del Proyecto]: <ID del proyecto>

--- 1. Resumen General del Clúster ---

[Tamaño del Clúster]: <número de nodos> nodos
[Util promedio del clúster]: <valor>
[Await promedio del clúster]: <valor>
[Desequilibrio de I/O]: <Sí/No>, desviación máxima: <valor>%
[Nodos con carga de I/O más alta]: <host_id> (util: <valor>%), <host_id> (util: <valor>%)

--- 2. Métricas de I/O ---

[Indicador de Sobrecarga]: <Sobrecargado / Normal>
- util máx: <valor>% (umbral: 90%)
- await máx: <valor> ms (umbral: 100ms)
- Rendimiento máx de lectura: <valor> MB/s
- Rendimiento máx de escritura: <valor> MB/s
- IOPS máx de lectura: <valor>
- IOPS máx de escritura: <valor>

[Fenómeno de I/O]: <Disco único alto / Todos los discos altos>
[Lista de Discos por Nodo]: <host_id> -> <disk_name>: util=<valor>%, await=<valor>ms, avgrq_sz=<valor>, avgqu_sz=<valor>; ...

--- 3. Carga de Consultas ---

[Número de Consultas Activas]: <valor>
[Distribución de Estados de Consultas]: running=<valor>, active=<valor>, waiting=<valor> ...
[Consultas de Mayor Duración (Top 5)]:
  <query_id> | <userName> | <duration_ms>ms | <query (truncado, primeros 200 caracteres)>
  ...
[Consultas Más Frecuentes (Top 5)]:
  <query_id> | <userName> | <recuento de ocurrencias> | <query (truncado, primeros 200 caracteres)>
  ...

--- 4. Concurrencia Empresarial ---

[Concurrencia Máxima]: <valor>
[Concurrencia Promedio]: <valor>
[Conexiones Activas Promedio]: <valor>

--- 5. Espera y Bloqueo ---

[Eventos de Espera (Top 10)]:
  <wait_event> | <recuento> | <username> | <host_id>
  ...
[Conflictos de Bloqueo]: <Sí/No>, <lock_type>, blocker=<bloqueador>, waiter=<esperador>
  ...

--- 6. Diagnóstico de Causa Raíz ---

[Escenario de Diagnóstico]: <Tormenta de Consultas / Contención de Bloqueos / Incierto>
[Descripción de la Causa Raíz]:
  <Según los hallazgos reales, descripción resumida. Ejemplo: "Se detectó que el nodo xxx tiene una gran cantidad de consultas activas (xxx), que están mayoritariamente en estado de ejecución, lo que resulta en una carga elevada de I/O; la causa raíz es una tormenta de consultas">

[Diagnóstico Adicional]:
  <Campos de extensión como metadatos de tabla caliente, puede mostrar lo que indica la métrica>

--- Fin del Informe ---