huaweicloud/huawei-cloud-dws-io-diag

Compétence de Diagnostic de Surcharge I/O du Cluster DWS Huawei Cloud

Présentation

Cette compétence est dédiée au diagnostic des causes racines d'une surcharge I/O du cluster DWS. Lorsqu'un cluster déclenche une alerte d'utilisation I/O trop élevée, elle collecte automatiquement les données métriques, analyse les causes racines (côté client / côté système) via un arbre de décision en trois étapes, et produit un rapport de diagnostic standardisé.

Architecture : KooCLI (hcloud) → API DWS Autopilot → Métriques de supervision du cluster ; Serveur MCP (dws_autopilot) → Canal de repli pour la même API

Scénarios Applicables :

• Alerte d'utilisation I/O trop élevée du cluster DWS
• Investigation de charge anormale du disque I/O
• Demande de diagnostic I/O initiée par l'utilisateur

Cas d'Utilisation Typiques :

• « L'utilisation I/O de mon cluster DWS est très élevée, aidez-moi à diagnostiquer »
• « J'ai reçu une alerte I/O, l'ID du cluster est xxx, aidez-moi à analyser la cause »
• « L'util du disque du cluster DWS est saturé, voyez ce qui la cause »

Périmètre et Limites de la Compétence :

• Périmètre du service : Cette compétence ne prend en charge que le service d'entrepôt de données DWS (GaussDB(DWS)) de Huawei Cloud. Elle NE s'applique PAS aux services non-DWS tels que ECS, RDS, CCE, ou autres.
• Périmètre du type de problème : Cette compétence diagnostique uniquement la surcharge I/O / l'utilisation I/O trop élevée / la charge anormale du disque I/O du cluster DWS (surcharge I/O, anomalie I/O, await élevé, util élevé, etc.). Elle ne traite PAS les problèmes de surcharge CPU, de mémoire élevée ou autres problèmes non I/O (voir les compétences dédiées de diagnostic CPU/mémoire).
• Périmètre des opérations : Cette compétence est un diagnostic en lecture seule. Elle n'exécute AUCUNE opération de gestion ou de maintenance telle que redémarrage de cluster, augmentation/réduction de capacité, remplacement de nœud, arrêt de requête SQL ou modification de paramètre.

Règles Importantes : Toutes les conclusions du diagnostic doivent provenir des résultats réels des outils. Il est interdit d'inventer ou de supposer des valeurs. La sortie ne doit contenir que le rapport de diagnostic ; l'ajout de suggestions de correction, la sortie d'instructions d'optimisation SQL et l'utilisation d'émojis sont interdits.

Connaissances de Base : L'architecture RAID, les seuils clés des métriques I/O, les caractéristiques des indicateurs des trois principaux scénarios I/O et les principes importants sont documentés dans Connaissances de Base I/O. Doit être lu avant le diagnostic.

Prérequis

1. Exigences CLI

• KooCLI (hcloud) >= 3.2.0
• Vérifier l'installation : hcloud version
• Si non installé ou version trop ancienne, voir Guide d'Installation CLI

2. Configuration du Serveur MCP (Repli)

• Lorsque KooCLI n'est pas disponible, utiliser le serveur MCP comme alternative
• Voir Guide d'Installation MCP

3. Configuration d'Authentification

• Identifiants Huawei Cloud valides (mode AK/SK ou jeton IAM)
• Règles de Sécurité :
  • Ne jamais exposer les valeurs AK/SK dans les conversations ou les commandes
  • Ne jamais demander aux utilisateurs de saisir AK/SK directement dans la conversation
  • Utiliser uniquement hcloud configure list pour vérifier l'état des identifiants

4. Exigences de Permission IAM

• dws:clusters:get, dws:clusters:list
• dws:metricData:get, dws:hostOverview:get
• Voir Politiques IAM

Format Standard des Commandes KooCLI

Format de Commande

# Interroger les données métriques
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>

# Interroger les informations d'hôte
hcloud DWS ListHostOverview --cli-region=<region> --project_id=<pid> --cluster_id=<cid> --offset=0 --limit=200

Stratégie de Sélection d'Outil

Choisir entre KooCLI et le serveur MCP, en privilégiant KooCLI. L'étape 0 vérifie la disponibilité de hcloud :

• hcloud disponible (version >= 3.2.0) → Utiliser les appels en ligne de commande KooCLI pour les étapes suivantes
• hcloud indisponible (non installé ou version < 3.2.0) → Utiliser les appels d'outil du serveur MCP pour les étapes suivantes

Stratégie de Repli et d'Arrêt :

• Après avoir sélectionné hcloud, si le premier appel retourne NETWORK_ERROR (délai de connexion expiré, réseau inaccessible, etc.), basculer automatiquement vers le serveur MCP et utiliser le mode MCP pour toutes les étapes suivantes
• Si hcloud retourne NETWORK_ERROR et que le serveur MCP est également indisponible (non configuré ou retourne une erreur d'authentification/connexion), terminer cette compétence et afficher : Réseau KooCLI indisponible et connexion au serveur MCP échouée. Veuillez vérifier la configuration réseau de KooCLI ou la configuration du serveur MCP DWS Autopilot et réessayer
• Après avoir sélectionné le serveur MCP, si le premier appel retourne une erreur d'authentification (par exemple, 401 Non autorisé), ne pas basculer vers hcloud. Terminer directement cette compétence et afficher : L'authentification du serveur MCP a échoué. Veuillez vérifier la configuration d'authentification du serveur MCP DWS Autopilot et réessayer
• Les échecs d'appel hcloud qui ne sont pas NETWORK_ERROR (par exemple, erreurs de paramètres, permissions insuffisantes) ne déclenchent pas de repli ; suivre la logique de nouvelle tentative existante

Une fois un outil sélectionné, l'utiliser tout au long du processus sans basculer (sauf pour le repli NETWORK_ERROR). Si un appel échoue, réessayer une fois (maximum 2 tentatives). Si l'échec persiste, marquer la métrique comme « indisponible » et passer à l'étape suivante. Lorsque toutes les requêtes métriques échouent, générer le rapport de diagnostic directement.

Mapping des Paramètres

Paramètre Commun	Paramètre hcloud	Paramètre MCP
Région	--cli-region	(intégré à la connexion MCP)
ID du Projet	--project_id	project_id
ID du Cluster	--cluster_id	cluster_id
Nom de la Métrique	--metric_name	metric_name
Heure de Début	--from	from_ts
Heure de Fin	--to	to_ts
Décalage de Pagination	--offset	offset
Limite de Pagination	--limit	limit
Champ de Tri	(non pris en charge)	order_by
Direction de Tri	(non pris en charge)	sort_by

Outils MCP

Nom de l'Outil	Objectif	Paramètres Clés
dws_autopilot_get_clusters	Interroger la liste des clusters	project_id, cluster_id, limit, offset
dws_autopilot_get_hosts	Interroger les informations d'hôte	project_id, cluster_id, limit, offset
dws_autopilot_get_metric	Interroger les données métriques	project_id, cluster_id, metric_name, from_ts, to_ts, limit, offset, order_by, sort_by

Remarques sur les Paramètres metric_data : metric_data ne prend pas en charge le filtrage par instance_name (aucun paramètre de ce type) ; la requête renvoie les données complètes du cluster et doit être filtrée par le champ inst_name pour les instances cibles ; metric_data ne prend pas en charge le paramètre period (la période d'échantillonnage est déterminée automatiquement par la plateforme).

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

Protocole Temporel : from_ts/to_ts doivent utiliser des timestamps Unix en millisecondes ; tous les temps sont dans le fuseau horaire UTC ; fenêtre temporelle recommandée : de 5 minutes avant l'heure de l'alarme à l'heure de l'alarme (from_ts = first_alarm_time - 300000).

Format de Retour : Succès {"code": 0, "data": [...]} ; Échec {"code": -1, "message": "description de l'erreur"}. En cas d'échec, réessayer une fois ; si l'échec persiste, utiliser le chemin de dégradation et marquer comme « indisponible » dans le rapport.

Champs Clés par Métrique :

• 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étriques I/O de base
• CpuStat : ctime, host_id, cpu_data{usr, sys, idle, iowait} → iowait > 30 % indique une pression I/O significative
• 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} → détails du diagnostic I/O + requêtes actives
• business_concurrency : ctime, concurrency_value, active_connections → concurrence métier
• business_query_monitor : ctime, query, query_id, username, duration_ms, host_id → requêtes historiques en temps réel
• business_thread_wait : ctime, wait_event, count, username, host_id → événements d'attente (wait wal sync, WALWriteLock, etc.)
• bussiness_conflict_lock : ctime, lock_type, blocker, waiter, username, host_id → conflits de verrous

Pour les différences de requêtes par étape, voir Référence Métrique.

Spécification de Pagination

Tous les appels d'outil (MCP et hcloud) doivent utiliser des requêtes paginées pour éviter que les réponses uniques ne soient trop volumineuses et ne dépassent les limites de tokens.

Règles de Pagination :

• Utiliser limit=200 uniformément (ne pas utiliser de valeurs supérieures à 200, sauf pour l'exception déclarée ci-dessous)
• Exception explicite : cpu_io_diagnose_detail utilise une pagination avec limit=800 (en raison de son volume de données le plus important, multi-nœuds × multi-instances × multi-timestamps × multi-requêtes) ; une seule page de 200 peut ne pas suffire
• Première page offset=0 ; si le nombre de données retournées = limit, alors offset+=limit et continuer la requête
• Répéter jusqu'à ce que le nombre de données retournées < limit, puis fusionner toutes les données paginées
• Lors de la fusion, concaténer tous les tableaux de données de page en un ensemble de données complet

Exemple d'Appel MCP (en utilisant IOStat) :

Page 1 : dws_autopilot_get_metric(project_id, cluster_id, metric_name="IOStat", from_ts, to_ts, limit=200, offset=0)
Si la longueur des données retournées = 200 :
Page 2 : dws_autopilot_get_metric(project_id, cluster_id, metric_name="IOStat", from_ts, to_ts, limit=200, offset=200)
Si la longueur des données retournées < 200 : Arrêter la pagination, fusionner les données de la page 1 + page 2

Exemple d'Appel hcloud (en utilisant 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>
Si le nombre de données retournées = 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>
Si le nombre de données retournées < 200 : Arrêter la pagination, fusionner les données

Workflow

Avant le diagnostic, créer un plan d'exécution basé sur les étapes 0 à 7, puis exécuter séquentiellement. Pour la stratégie de sélection d'outil, voir la section « Format Standard des Commandes KooCLI » ; les étapes suivantes ne la répéteront pas. Tous les appels d'outil MCP suivent la section « Spécification de Pagination » ; les étapes suivantes ne répéteront pas les détails de pagination.

Étape 0 : Détection de l'Environnement et Résolution des Paramètres

Validation des Paramètres Requis : Avant de continuer, vérifier qu'au moins un des paramètres cluster_id ou cluster_name est fourni (les deux peuvent être fournis, mais au moins l'un est obligatoire). Si les deux sont manquants, inviter l'utilisateur à fournir un cluster_id ou cluster_name valide et terminer le diagnostic jusqu'à ce qu'il soit fourni.

Validation de l'Existence du Cluster : Utiliser la requête de liste des clusters (hcloud DWS ListClusters en mode hcloud, ou dws_autopilot_get_clusters en mode MCP) pour confirmer que le cluster cible existe :

• Si la requête renvoie les codes d'erreur DWS.13026 ou DWS.13032 (cluster non trouvé), ou que la liste des clusters retournée ne contient pas le cluster_id/cluster_name spécifié → le cluster n'existe pas. Terminer le diagnostic et inviter : Le cluster DWS spécifié n'existe pas. Veuillez vérifier le cluster_id/cluster_name et réessayer.
• Si la requête réussit et que le cluster existe → continuer avec les étapes suivantes.

Résolution des Paramètres : Si project_id ou region_id n'est pas fourni par l'utilisateur, lire à partir du fichier de configuration du serveur MCP conf/dws_config.yaml :

• Lorsque project_id est manquant : Exécuter python -c "import yaml; c=yaml.safe_load(open('conf/dws_config.yaml')); print(c.get('project_id',''))" pour l'obtenir
• Lorsque region_id est manquant : Exécuter python -c "import yaml; c=yaml.safe_load(open('conf/dws_config.yaml')); print(c.get('region_id',''))" pour l'obtenir
• Si le champ correspondant dans le fichier de configuration est également vide, inviter l'utilisateur à fournir le paramètre

Exécuter hcloud version ; version >= 3.2.0 → tool_mode=hcloud, sinon tool_mode=mcp.

Test de Disponibilité Réseau hcloud : Si tool_mode=hcloud, exécuter un appel API léger (par exemple, hcloud DWS ListClusters --cli-region=<region> --project_id=<project_id>) pour vérifier la connectivité réseau :

• Retourne normal ou une erreur métier (par exemple, permissions insuffisantes, erreur de paramètre) → Réseau disponible, conserver tool_mode=hcloud
• Retourne NETWORK_ERROR → Réseau indisponible, basculer vers tool_mode=mcp
• Après le repli, si MCP est également indisponible → Terminer l'exécution, inviter l'utilisateur à vérifier la configuration réseau de KooCLI ou la configuration du serveur MCP

Étape 1 : Interroger IOStat

Appeler la requête métrique avec metric_name="IOStat", fenêtre temporelle : from_ts=first_alarm_time - 300000, to_ts=first_alarm_time. En mode MCP, utiliser la requête paginée avec limit=200.

Détermination d'Indisponibilité Autopilot : Retourne une erreur 50201/RDS.9999 → Ignorer les étapes 1 à 6, marquer toutes les métriques comme « indisponibles », passer directement à l'étape 7.

Analyse : Grouper par host_id et disk_name, trouver les données I/O les plus récentes pour chaque disque sur chaque nœud. Extraire 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 pour chaque disque.

Détermination de Surcharge I/O : Si un disque a util > 90 % ou await > 100 ou que le débit/les IOPS atteignent la limite supérieure.

Détermination de Déséquilibre I/O : Si l'écart de util ou await entre les nœuds > 20 %.

Filtrage des Nœuds TOP : Trouver les deux nœuds avec la charge I/O la plus élevée.

Détermination de la Distribution du Phénomène : Déterminer si un nœud a des I/O élevées sur un seul disque ou sur tous les disques (utilisé pour l'orientation du scénario à l'étape 4).

Points Temporels I/O Élevés : À partir des données de séries temporelles IOStat, trouver tous les points ctime où un disque a util > 90 % sur les 2 premiers nœuds I/O. Collecter ces valeurs ctime en tant que high_io_ctimes (liste de timestamps en millisecondes). Enregistrer également le ctime avec le util le plus élevé en tant que peak_io_ctime. Si aucun ctime n'a util > 90 %, high_io_ctimes est vide et peak_io_ctime est le ctime avec la valeur util la plus élevée.

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

Étape 2 : Obtenir les Noms d'Hôte

Appeler la requête d'informations d'hôte (MCP mode limit=200 paginé), construire un mappage host_id → {host_name, host_type}.

Sortie : host_list (liste de chaînes de noms d'hôte, utilisée pour les présentations dans le rapport de diagnostic)

Étape 3 : Interroger CpuStat

Appeler la requête métrique avec metric_name="CpuStat", fenêtre temporelle : from_ts=peak_io_ctime - 60000, to_ts=peak_io_ctime + 60000. En mode MCP, utiliser la requête paginée avec limit=200.

Analyse : Grouper par host_id, trouver les données de pointe iowait pour chaque nœud.

Détermination de Pression I/O : iowait > 30 % indique une pression I/O sévère.

Sortie : io_wait_by_host (format : {node_name: {max_iowait: %, avg_iowait: %}})

Étape 4 : Scène de Tri Aiguillage

Détermination de la Scène :

• Si single_disk_high_nodes n'est pas vide → Scène "single_disk_high"
• Si all_disk_high_nodes n'est pas vide → Scène "all_disk_high"
• Sinon → Ignorer les étapes 5-6, passer directement à l'étape 7

Étape 5 : Interroger les Détails du Diagnostic I/O

Pour la scène "single_disk_high" ou "all_disk_high", appeler la requête métrique avec metric_name="cpu_io_diagnose_detail", fenêtre temporelle : from_ts=peak_io_ctime, to_ts=peak_io_ctime. En mode MCP, utiliser la requête paginée avec limit=800.

Analyse des Requêtes Actives : Trouver les informations des requêtes en cours d'exécution sur les nœuds problématiques.

Analyse des Verrous de Conflit : Vérifier bussiness_conflict_lock pour détecter des conflits de verrous.

Utilisation du Disque : Analyser la distribution des opérations de lecture/écriture.

Étape 6 : Interroger les Verrous et l'État de Concurrence

Basé sur les résultats de l'étape 5, appeler les requêtes métriques suivantes en tant que requête métrique unique (toutes les 4 métriques dans le même intervalle de requête) :

1. business_concurrency : Voir si la concurrence des connexions atteint la limite du cluster

2. business_query_monitor : Voir s'il y a des requêtes longue durée (durée > 60 secondes) ou des opérations d'import/export de masse

3. business_thread_wait : Voir s'il y a des conflits d'écriture WAL ou des goulots d'étranglement de téléchargement de paquet

4. bussiness_conflict_lock : Voir s'il y a des verrous de niveau table/ligne

Fenêtre temporelle : from_ts=peak_io_ctime - 60000, to_ts=peak_io_ctime + 60000

Analyse :

• Concurrence → Si la concurrence dépasse le seuil (par défaut : value > 30)
• Requêtes longue durée → marquage des requêtes dont la durée dépasse 60 s
• Événements d'attente → Grouper par nœud, marquer les types d'événements d'attente à haute fréquence
• Verrous de conflit → Grouper par nœud, compter les conflits de différents types de verrous

Sortie : High concurrency, long_running_queries, wait_events, lock_conflicts

Étape 7 : Génération du Rapport de Diagnostic et Analyse de la Cause Racine

Arbre de Décision en Trois Étapes :

Étape Un : Phénomène de Surcharge et Déséquilibre

• Analyser le déséquilibre I/O (l'écart de util/débit entre les nœuds)
• La charge I/O est-elle concentrée sur des disques uniques ?
• Le temps d'attente I/O (iowait) est-il élevé ?
• Phase de sortie de cette étape : Description du phénomène -> Conclusion A

Étape Deux : Scène de la Cause Racine (Division Côté Client / Côté Système)

• Côté Client : La charge I/O est-elle causée par des requêtes de l'utilisateur ? (requêtes longue durée, importation de données, conflit de verrous, concurrence élevée)
• Côté Système : La charge I/O est-elle causée par des défaillances matérielles/stockage ? (panne de disque RAID, nœud dégradé)
• Phase de sortie de cette étape : Attribution de la cause racine -> Conclusion B

Étape Trois : Résumé du Diagnostic

• Combiner les conclusions des étapes un et deux
• Sortir dans le format de rapport standardisé suivant

Format du Rapport de Diagnostic :

## Rapport de Diagnostic I/O du Cluster DWS

### Informations de Base
- ID du Cluster : {cluster_id}
- Nom du Cluster : {cluster_name}
- Version : {version}
- Nœuds du Cluster (total/indisponibles) : {total_nodes}/{down_nodes}
- Période d'Analyse : {from_ts} ~ {to_ts}

### Résumé du Diagnostic

### I. Analyse du Phénomène de Surcharge I/O

- **I/O du Nœud Problème** :
  - Nœud : {node_name}, Util Disque : {disk_util}%, Await : {await}ms, Débit en Lecture : {r_MB/s}, Débit en Écriture : {w_MB/s}, IOPS en Lecture : {r_iops}, IOPS en Écriture : {w_iops} (tilisation des valeurs du nœud le plus élevé)
- **Déséquilibre I/O Entre Nœuds** : {Déséquilibre / Normal}, avec {io_deviation}%
- **Pression I/O Système** : {iowait_max}% (si > 30 %, marquer comme pression I/O sévère, ou normal)

**Détermination** : 
Le cluster a une surcharge I/O. /  Le cluster a un déséquilibre I/O /  Le cluster a une pression I/O sévère.

### II. Analyse de la Cause Racine

**Type de Cause Racine** : {Côté Client / Côté Système}

- **Cause Racine Côté Client** :
  - Concurrence des Requêtes : (si > 30 → La concurrence des requêtes est élevée (concurrence actuelle : {n}), qui peut consommer beaucoup d'I/O du disque)
  - Requêtes Longue Durée : (si > 60 s → Détection de requêtes longue durée ({durée} secondes), qui peuvent causer une surcharge I/O)
  - Conflit de Verrous : (si conflit de verrous → Détection de conflits de verrous ({type de verrou}), qui peuvent causer une attente I/O)
  - Conflit d'Écriture WAL : (si conflit d'écriture WAL → Détection de conflits d'écriture WAL, qui peuvent causer une attente I/O)
  - Import/Export de Données : (détection d'opérations COPY/INSERT massives)

- **Cause Racine Côté Système** :
  - Panne de Disque RAID : (alerte de panne de disque RAID détectée)
  - Nœud Dégradé : (nœud dégradé détecté)

- **Autres Observations** :
  - (Autres informations observées, par exemple, I/O en lecture/écriture importante, taille de requête unique grande, etc.)

### III. Conclusion du Diagnostic

La cause racine actuelle est {côté client / côté système} : {description concise de la cause racine}

---
*Ce rapport est généré par le service de diagnostic DWS sur la base des données métriques collectées automatiquement.*

Format de Sortie :

• Sortir le contenu ci-dessus dans un bloc de code markdown
• Ne pas inclure de contenu en dehors du bloc de code
• Ne pas ajouter de lignes vides avant la sortie