huaweicloud/huawei-cloud-dws-io-diag

Huawei Cloud DWS I/O-Überlastungsdiagnose-Skill

Übersicht

Dieser Skill ist für die Grundursachendiagnose von DWS-Cluster-I/O-Überlastungen vorgesehen. Wenn ein Cluster einen Alarm wegen zu hoher I/O-Auslastung auslöst, sammelt er automatisch Metrikdaten, analysiert die Ursachen (kundenseitig / systemseitig) über einen dreistufigen Entscheidungsbaum und erstellt einen standardisierten Diagnosebericht.

Architektur: KooCLI (hcloud) → DWS Autopilot API → Cluster-Überwachungsmetriken; MCP Server (dws_autopilot) → Fallback-Kanal für dieselbe API

Anwendbare Szenarien:

• DWS-Cluster-Alarm wegen zu hoher I/O-Auslastung
• Untersuchung anormaler Festplatten-I/O-Last
• Benutzerinitiierte I/O-Diagnoseanfrage

Typische Anwendungsfälle:

• „Mein DWS-Cluster hat eine sehr hohe I/O-Auslastung, bitte helfen Sie bei der Diagnose“
• „Ich habe einen I/O-Alarm erhalten, die Cluster-ID ist xxx, bitte analysieren Sie die Ursache“
• „Die Festplattenauslastung (util) des DWS-Clusters ist auf Maximum, sehen Sie sich die Ursache an“

Skill-Umfang & Grenzen:

• Dienstgrenze: Dieser Skill unterstützt nur den Huawei Cloud DWS (GaussDB(DWS)) Data Warehouse Service. Er gilt NICHT für Nicht-DWS-Dienste wie ECS, RDS, CCE oder andere.
• Problemtyp-Grenze: Dieser Skill diagnostiziert nur DWS-Cluster-I/O-Überlastung / zu hohe I/O-Auslastung / anormale Festplatten-I/O-Last (I/O-Überlastung, I/O-Anomalie, hohe await, hohe util usw.). Er behandelt KEINE CPU-Überlastung, hohen Arbeitsspeicher oder andere Nicht-I/O-Probleme (siehe dedizierte CPU-/Arbeitsspeicher-Diagnose-Skills).
• Operationsgrenze: Dieser Skill ist eine reine Lese-Diagnose. Er führt KEINE Verwaltungs- oder Wartungsvorgänge wie Cluster-Neustart, Skalierung, Knotenaustausch, SQL-Killen oder Parameteränderungen aus.

Wichtige Regeln: Alle Diagnose-Schlussfolgerungen müssen aus tatsächlichen Tool-Rückgabeergebnissen stammen. Das Erfinden oder Annehmen von Werten ist verboten. Die Ausgabe enthält nur den Diagnosebericht. Das Hinzufügen von Behebungsvorschlägen, die Ausgabe von SQL-Optimierungsanweisungen und die Verwendung von Emojis sind verboten.

Hintergrundwissen: RAID-Architektur, Schwellenwerte für I/O-Schlüsselmetriken, Indikatormerkmale der drei wichtigsten I/O-Szenarien und wichtige Prinzipien sind in I/O-Hintergrundwissen dokumentiert. Vor der Diagnose muss dieses gelesen werden.

Voraussetzungen

1. CLI-Anforderungen

• KooCLI (hcloud) >= 3.2.0
• Installation überprüfen: hcloud version
• Wenn nicht installiert oder Version zu niedrig, siehe CLI-Installationsanleitung

2. MCP Server-Konfiguration (Fallback)

• Wenn KooCLI nicht verfügbar ist, MCP Server als Alternative verwenden
• Siehe MCP-Installationsanleitung

3. Authentifizierungskonfiguration

• Gültige Huawei Cloud-Anmeldeinformationen (AK/SK-Modus oder IAM-Token)
• Sicherheitsregeln:
  • AK/SK-Werte niemals in Gesprächen oder Befehlen preisgeben
  • Benutzer niemals bitten, AK/SK direkt im Gespräch einzugeben
  • Nur hcloud configure list verwenden, um den Anmeldestatus zu überprüfen

4. IAM-Berechtigungsanforderungen

• dws:clusters:get, dws:clusters:list
• dws:metricData:get, dws:hostOverview:get
• Siehe IAM-Richtlinien

KooCLI-Befehlsformat-Standard

Befehlsformat

# Metrikdaten abfragen
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>

# Host-Informationen abfragen
hcloud DWS ListHostOverview --cli-region=<region> --project_id=<pid> --cluster_id=<cid> --offset=0 --limit=200

Tool-Auswahlstrategie

Wählen Sie zwischen KooCLI und MCP Server, bevorzugen Sie KooCLI. Schritt 0 prüft die hcloud-Verfügbarkeit:

• hcloud verfügbar (Version >= 3.2.0) → KooCLI-Befehlszeilenaufrufe für nachfolgende Schritte verwenden
• hcloud nicht verfügbar (nicht installiert oder Version < 3.2.0) → MCP Server-Toolaufrufe für nachfolgende Schritte verwenden

Fallback- und Beendigungsstrategie:

• Nach Auswahl von hcloud: Wenn der erste Aufruf NETWORK_ERROR zurückgibt (Verbindungszeitüberschreitung, Netzwerk nicht erreichbar usw.), automatisch auf MCP Server zurückfallen und MCP-Modus für alle nachfolgenden Schritte verwenden
• Wenn hcloud NETWORK_ERROR zurückgibt und MCP Server ebenfalls nicht verfügbar ist (nicht konfiguriert oder gibt Authentifizierungs-/Verbindungsfehler zurück), diesen Skill beenden und ausgeben: KooCLI-Netzwerk nicht verfügbar und MCP Server-Verbindung fehlgeschlagen. Bitte überprüfen Sie die KooCLI-Netzwerkkonfiguration oder die DWS Autopilot MCP Server-Konfiguration und wiederholen Sie den Vorgang.
• Nach Auswahl von MCP Server: Wenn der erste Aufruf einen Authentifizierungsfehler zurückgibt (z. B. 401 Nicht autorisiert), nicht auf hcloud zurückfallen. Diesen Skill direkt beenden und ausgeben: MCP Server-Authentifizierung fehlgeschlagen. Bitte überprüfen Sie die DWS Autopilot MCP Server-Authentifizierungskonfiguration und wiederholen Sie den Vorgang.
• hcloud-Aufruffehler, die NICHT NETWORK_ERROR sind (z. B. Parameterfehler, unzureichende Berechtigungen), lösen keinen Fallback aus; vorhandene Wiederholungslogik befolgen

Sobald ein Tool ausgewählt wurde, wird es durchgehend verwendet, ohne zu wechseln (außer für NETWORK_ERROR-Fallback). Wenn ein Aufruf fehlschlägt, einmal wiederholen (maximal 2 Versuche). Wenn immer noch fehlschlagend, die Metrik als „nicht verfügbar“ markieren und mit dem nächsten Schritt fortfahren. Wenn alle Metrikabfragen fehlschlagen, den Diagnosebericht direkt generieren.

Parameterzuordnung

Allgemeiner Parameter	hcloud-Parameter	MCP-Parameter
Region	--cli-region	(in MCP-Verbindung integriert)
Projekt-ID	--project_id	project_id
Cluster-ID	--cluster_id	cluster_id
Metrikname	--metric_name	metric_name
Startzeit	--from	from_ts
Endzeit	--to	to_ts
Paginierungs-Offset	--offset	offset
Paginierungslimit	--limit	limit
Sortierfeld	(nicht unterstützt)	order_by
Sortierrichtung	(nicht unterstützt)	sort_by

MCP-Tools

Tool-Name	Zweck	Wichtige Parameter
dws_autopilot_get_clusters	Cluster-Liste abfragen	project_id, cluster_id, limit, offset
dws_autopilot_get_hosts	Host-Informationen abfragen	project_id, cluster_id, limit, offset
dws_autopilot_get_metric	Metrikdaten abfragen	project_id, cluster_id, metric_name, from_ts, to_ts, limit, offset, order_by, sort_by

Hinweise zu metric_data-Parametern: metric_data unterstützt keine Filterung nach instance_name (kein solcher Parameter); die Abfrage gibt vollständige Clusterdaten zurück und muss nach dem inst_name-Feld für Zielinstanzen gefiltert werden; metric_data unterstützt keinen period-Parameter (das Abtastintervall wird automatisch von der Plattform bestimmt).

Verfügbare metric_name: IOStat, CpuStat, cpu_io_diagnose_detail, business_concurrency, business_query_monitor, business_thread_wait, bussiness_conflict_lock

Zeitprotokoll: from_ts/to_ts müssen Unix-Millisekunden-Zeitstempel verwenden; alle Zeiten sind in UTC-Zeitzone; empfohlenes Zeitfenster: von 5 Minuten vor Alarmzeit bis zur Alarmzeit (from_ts = erste_Alarmzeit - 300000).

Rückgabeformat: Erfolg {"code": 0, "data": [...]}; Fehler {"code": -1, "message": "Fehlerbeschreibung"}. Bei Fehler einmal wiederholen; wenn immer noch fehlschlagend, Degradationspfad verwenden und im Bericht als „nicht verfügbar“ markieren.

Schlüsselfelder pro Metrik:

• 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} → Kern-I/O-Metriken
• CpuStat: ctime, host_id, cpu_data{usr, sys, idle, iowait} → iowait > 30 % weist auf erheblichen I/O-Druck hin
• 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-Diagnosedetails + aktive Abfragen
• business_concurrency: ctime, concurrency_value, active_connections → Geschäftskonkurrenz
• business_query_monitor: ctime, query, query_id, username, duration_ms, host_id → historische Echtzeit-Abfragen
• business_thread_wait: ctime, wait_event, count, username, host_id → Warte-Ereignisse (Warte auf WAL-Sync, WALWriteLock usw.)
• bussiness_conflict_lock: ctime, lock_type, blocker, waiter, username, host_id → Sperrkonflikte

Für Abfrageunterschiede pro Schritt siehe Metrik-Referenz.

Paginierungsspezifikation

Alle Tool-Aufrufe (MCP und hcloud) müssen paginierte Abfragen verwenden, um zu verhindern, dass einzelne Antworten zu groß werden und Token-Limits überschreiten.

Paginierungsregeln:

• Einheitlich limit=200 verwenden (keine Werte größer als 200 verwenden, außer der deklarierten Ausnahme unten)
• Explizite Ausnahme: cpu_io_diagnose_detail verwendet limit=800-Paginierung (aufgrund des größten Datenvolumens: Multi-Knoten × Multi-Instanz × Multi-Zeitpunkt × Multi-Abfrage); eine einzelne Seite von 200 reicht möglicherweise nicht aus
• Erste Seite offset=0; wenn zurückgegebene Datenanzahl = limit, dann offset+=limit und Abfrage fortsetzen
• Wiederholen, bis zurückgegebene Datenanzahl < limit, dann alle paginierten Daten zusammenführen
• Beim Zusammenführen alle Datenarrays aller Seiten zu einem vollständigen Datensatz konkatenieren

MCP-Aufrufbeispiel (mit IOStat):

Seite 1: dws_autopilot_get_metric(project_id, cluster_id, metric_name="IOStat", from_ts, to_ts, limit=200, offset=0)
Wenn zurückgegebene Datenlänge = 200:
Seite 2: dws_autopilot_get_metric(project_id, cluster_id, metric_name="IOStat", from_ts, to_ts, limit=200, offset=200)
Wenn zurückgegebene Datenlänge < 200: Paginierung stoppen, Daten von Seite 1 + Seite 2 zusammenführen

hcloud-Aufrufbeispiel (mit IOStat):

Seite 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>
Wenn zurückgegebene Datenanzahl = 200:
Seite 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>
Wenn zurückgegebene Datenanzahl < 200: Paginierung stoppen, Daten zusammenführen

Arbeitsablauf

Erstellen Sie vor der Diagnose einen Ausführungsplan basierend auf den Schritten 0-7 und führen Sie ihn dann sequenziell aus. Informationen zur Tool-Auswahlstrategie finden Sie im Abschnitt „KooCLI-Befehlsformat-Standard“; nachfolgende Schritte wiederholen dies nicht. Alle MCP-Toolaufrufe befolgen den Abschnitt „Paginierungsspezifikation“; nachfolgende Schritte wiederholen keine Paginierungsdetails.

Schritt 0: Umgebungserkennung & Parameterauflösung

Erforderliche Parametervalidierung: Stellen Sie vor dem Fortfahren sicher, dass mindestens einer von cluster_id oder cluster_name bereitgestellt wurde (beide können bereitgestellt werden, aber mindestens einer ist erforderlich). Wenn beide fehlen, fordern Sie den Benutzer auf, eine gültige cluster_id oder einen gültigen cluster_name bereitzustellen und beenden Sie die Diagnose, bis dies geschehen ist.

Cluster-Existenzvalidierung: Verwenden Sie die Clusterlistenabfrage (hcloud DWS ListClusters im hcloud-Modus oder dws_autopilot_get_clusters im MCP-Modus), um zu bestätigen, dass der Zielcluster existiert:

• Wenn die Abfrage die Fehlercodes DWS.13026 oder DWS.13032 zurückgibt (Cluster nicht gefunden) oder die zurückgegebene Clusterliste die angegebene cluster_id/cluster_name nicht enthält → der Cluster existiert nicht. Beenden Sie die Diagnose und geben Sie aus: Der angegebene DWS-Cluster existiert nicht. Bitte überprüfen Sie die cluster_id/cluster_name und wiederholen Sie den Vorgang.
• Wenn die Abfrage erfolgreich ist und der Cluster existiert → mit den folgenden Schritten fortfahren.

Parameterauflösung: Wenn project_id oder region_id nicht vom Benutzer bereitgestellt wurden, aus der MCP Server-Konfigurationsdatei conf/dws_config.yaml lesen:

• Wenn project_id fehlt: python -c "import yaml; c=yaml.safe_load(open('conf/dws_config.yaml')); print(c.get('project_id',''))" ausführen, um sie zu erhalten
• Wenn region_id fehlt: python -c "import yaml; c=yaml.safe_load(open('conf/dws_config.yaml')); print(c.get('region_id',''))" ausführen, um sie zu erhalten
• Wenn das entsprechende Feld in der Konfigurationsdatei ebenfalls leer ist, den Benutzer auffordern, den Parameter bereitzustellen

hcloud version ausführen; Version >= 3.2.0 → tool_mode=hcloud, sonst tool_mode=mcp.

hcloud-Netzwerkverfügbarkeitsprüfung: Wenn tool_mode=hcloud, einen leichten API-Aufruf ausführen (z. B. hcloud DWS ListClusters --cli-region=<region> --project_id=<project_id>), um die Netzwerkkonnektivität zu überprüfen:

• Gibt Normalwert oder Geschäftsfehler zurück (z. B. unzureichende Berechtigungen, Parameterfehler) → Netzwerk verfügbar, tool_mode=hcloud beibehalten
• Gibt NETWORK_ERROR zurück → Netzwerk nicht verfügbar, auf tool_mode=mcp zurückfallen
• Nach Fallback, wenn MCP ebenfalls nicht verfügbar ist → Ausführung beenden, Benutzer auffordern, die KooCLI-Netzwerkkonfiguration oder die MCP Server-Konfiguration zu überprüfen

Schritt 1: IOStat abfragen

Metrikabfrage mit metric_name="IOStat" aufrufen, Zeitfenster: from_ts=erste_Alarmzeit - 300000, to_ts=erste_Alarmzeit. Im MCP-Modus limit=200-paginierte Abfrage verwenden.

Autopilot-Nicht-Verfügbarkeitsbestimmung: Gibt Fehler 50201/RDS.9999 zurück → Schritte 1-6 überspringen, alle Metriken als „nicht verfügbar“ markieren, direkt zu Schritt 7 gehen.

Parsen: Nach host_id und disk_name gruppieren, die neuesten I/O-Daten für jede Festplatte auf jedem Knoten finden. Für jede Festplatte 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 extrahieren.

I/O-Überlastungsbestimmung: Ob eine Festplatte util > 90 % oder await > 100 oder Durchsatz/IOPS die Obergrenze erreicht.

I/O-Ungleichgewichtsbestimmung: Ob die Abweichung von util oder await zwischen Knoten > 20 %.

TOP-Knoten-Filterung: Die beiden Knoten mit der höchsten I/O-Last finden.

Phänomenverteilungsbestimmung: Ob ein Knoten einzelne Festplatte mit hohem I/O oder alle Festplatten mit hohem I/O hat (für Schritt 4 Szenario-Routing verwendet).

Hohe I/O-Zeitpunkte: Aus den IOStat-Zeitreihendaten alle ctime-Punkte finden, an denen auf den Top-2-I/O-Knoten eine Festplatte util > 90 % aufweist. Diese ctime-Werte als high_io_ctimes (Liste von Millisekunden-Zeitstempeln) sammeln. Auch die ctime mit der höchsten util als peak_io_ctime aufzeichnen. Wenn keine ctime util > 90 % aufweist, ist high_io_ctimes leer und peak_io_ctime ist die ctime mit dem höchsten util-Wert.

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

Schritt 2: Hostnamen abrufen

Hostinformationsabfrage aufrufen (MCP-Modus limit=200-paginiert), host_id → {ho ... [für die Übersetzung gekürzt]