huaweicloud/huawei-cloud-dws-io-diag

Habilidade de Diagnóstico de Sobrecarga de I/O do DWS da Huawei Cloud

Visão Geral

Esta habilidade é dedicada ao diagnóstico de causa raiz de sobrecarga de I/O do cluster DWS. Quando um cluster dispara um alarme de uso de I/O muito alto, ela coleta automaticamente dados de métrica, analisa as causas raiz (lado do cliente / lado do sistema) por meio de uma árvore de decisão de três estágios e gera um relatório de diagnóstico padronizado.

Arquitetura: KooCLI (hcloud) → API do DWS Autopilot → Métricas de monitoramento do cluster; MCP Server (dws_autopilot) → Canal de fallback para a mesma API

Cenários Aplicáveis:

• Alarme de uso de I/O muito alto do cluster DWS
• Investigação de anomalia de carga de I/O de disco
• Solicitação de diagnóstico de I/O iniciada pelo usuário

Casos de Uso Típicos:

• "O uso de I/O do meu cluster DWS está muito alto, ajude a diagnosticar"
• "Recebi um alarme de I/O, o ID do cluster é xxx, ajude a analisar a causa"
• "O util do disco do cluster DWS está no máximo, veja o que está causando isso"

Escopo e Limites da Habilidade:

• Limite de serviço: Esta habilidade só suporta o serviço de data warehouse DWS (GaussDB(DWS)) da Huawei Cloud. NÃO se aplica a serviços não DWS, como ECS, RDS, CCE ou outros.
• Limite de tipo de problema: Esta habilidade só diagnostica sobrecarga de I/O / uso de I/O muito alto / anomalia de carga de I/O de disco do cluster DWS (sobrecarga de I/O, anomalia de I/O, await alto, util alto, etc.). Ela NÃO lida com sobrecarga de CPU, memória alta ou outros problemas não relacionados a I/O (consulte as habilidades de diagnóstico de CPU/memória dedicadas).
• Limite de operação: Esta habilidade é um diagnóstico somente leitura. Ela NÃO executa nenhuma operação de gerenciamento ou manutenção, como reinicialização de cluster, expansão/redução, substituição de nó, encerramento de SQL ou modificação de parâmetros.

Regras Importantes: Todas as conclusões de diagnóstico devem vir dos resultados reais das ferramentas. Fabricar ou assumir valores é proibido. A saída contém apenas o relatório de diagnóstico; é proibido adicionar sugestões de correção, gerar instruções de otimização SQL e usar emojis.

Conhecimento de Base: A arquitetura RAID, os limites das métricas-chave de I/O, as características dos indicadores dos três principais cenários de I/O e os princípios importantes estão documentados em Conhecimento de Base de I/O. Deve ser lido antes do diagnóstico.

Pré-requisitos

1. Requisitos da CLI

• KooCLI (hcloud) >= 3.2.0
• Verificar instalação: hcloud version
• Se não estiver instalado ou a versão for muito antiga, consulte Guia de Instalação da CLI

2. Configuração do MCP Server (Fallback)

• Quando o KooCLI não estiver disponível, use o MCP Server como alternativa
• Consulte Guia de Instalação do MCP

3. Configuração de Autenticação

• Credenciais válidas da Huawei Cloud (modo AK/SK ou IAM Token)
• Regras de Segurança:
  • Nunca exponha valores de AK/SK em conversas ou comandos
  • Nunca peça aos usuários para inserir AK/SK diretamente na conversa
  • Use apenas hcloud configure list para verificar o status da credencial

4. Requisitos de Permissão do IAM

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

Padrão de Formato de Comando KooCLI

Formato do Comando

# Consultar dados de métrica
hcloud DWS ListMetricsData --cli-region=<região> --cluster_id=<id> --metric_name=<nome> --project_id=<pid> --offset=0 --limit=200 --from=<ts_inicial> --to=<ts_final>

# Consultar informações do host
hcloud DWS ListHostOverview --cli-region=<região> --project_id=<pid> --cluster_id=<cid> --offset=0 --limit=200

Estratégia de Seleção de Ferramenta

Escolha entre KooCLI e MCP Server, preferindo o KooCLI. A Etapa 0 verifica a disponibilidade do hcloud:

• hcloud disponível (versão >= 3.2.0) → Use chamadas de linha de comando do KooCLI para as etapas subsequentes
• hcloud indisponível (não instalado ou versão < 3.2.0) → Use chamadas de ferramenta do MCP Server para as etapas subsequentes

Estratégia de Fallback e Encerramento:

• Após selecionar o hcloud, se a primeira chamada retornar NETWORK_ERROR (timeout de conexão, rede inacessível, etc.), faça fallback automaticamente para o MCP Server e use o modo MCP para todas as etapas subsequentes
• Se o hcloud retornar NETWORK_ERROR e o MCP Server também estiver indisponível (não configurado ou retornar erro de autenticação/conexão), encerre esta habilidade e produza: Rede do KooCLI indisponível e conexão com o MCP Server falhou. Verifique a configuração de rede do KooCLI ou a configuração do MCP Server do DWS Autopilot e tente novamente
• Após selecionar o MCP Server, se a primeira chamada retornar um erro de autenticação (por exemplo, 401 Não Autorizado), não faça fallback para o hcloud. Encerre esta habilidade diretamente e produza: Falha de autenticação do MCP Server. Verifique a configuração de autenticação do MCP Server do DWS Autopilot e tente novamente
• Falhas de chamada do hcloud que não são NETWORK_ERROR (por exemplo, erros de parâmetro, permissões insuficientes) não acionam fallback; siga a lógica de repetição existente

Depois que uma ferramenta é selecionada, use-a durante todo o processo sem alternar (exceto para fallback de NETWORK_ERROR). Se uma chamada falhar, repita uma vez (máximo de 2 tentativas). Se ainda falhar, marque a métrica como "indisponível" e continue para a próxima etapa. Quando todas as consultas de métrica falharem, gere o relatório de diagnóstico diretamente.

Mapeamento de Parâmetros

Parâmetro Comum	Parâmetro hcloud	Parâmetro MCP
Região	--cli-region	(incorporado na conexão MCP)
ID do Projeto	--project_id	project_id
ID do Cluster	--cluster_id	cluster_id
Nome da Métrica	--metric_name	metric_name
Hora de Início	--from	from_ts
Hora de Fim	--to	to_ts
Deslocamento de Paginação	--offset	offset
Limite de Paginação	--limit	limit
Campo de Ordenação	(não suportado)	order_by
Direção de Ordenação	(não suportado)	sort_by

Ferramentas MCP

Nome da Ferramenta	Finalidade	Parâmetros Chave
dws_autopilot_get_clusters	Consultar lista de clusters	project_id, cluster_id, limit, offset
dws_autopilot_get_hosts	Consultar informações do host	project_id, cluster_id, limit, offset
dws_autopilot_get_metric	Consultar dados de métrica	project_id, cluster_id, metric_name, from_ts, to_ts, limit, offset, order_by, sort_by

Notas sobre o Parâmetro metric_data: metric_data não suporta filtragem por instance_name (nenhum parâmetro desse tipo); a consulta retorna dados completos do cluster e deve ser filtrada pelo campo inst_name para as instâncias alvo; metric_data não suporta o parâmetro period (o período de amostragem é determinado automaticamente pela plataforma).

metric_name disponível: IOStat, CpuStat, cpu_io_diagnose_detail, business_concurrency, business_query_monitor, business_thread_wait, bussiness_conflict_lock

Protocolo de Tempo: from_ts/to_ts devem usar timestamps Unix em milissegundos; todas as horas estão no fuso horário UTC; janela de tempo recomendada: de 5 minutos antes da hora do alarme até a hora do alarme (from_ts = hora_primeiro_alarme - 300000).

Formato de Retorno: Sucesso {"code": 0, "data": [...]}; Falha {"code": -1, "message": "descrição do erro"}. Em caso de falha, repita uma vez; se ainda falhar, use o caminho de degradação e marque como "indisponível" no relatório.

Campos Chave 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 principais de I/O
• CpuStat: ctime, host_id, cpu_data{usr, sys, idle, iowait} → iowait > 30% indica pressão significativa de 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} → detalhes do diagnóstico de I/O + consultas ativas
• business_concurrency: ctime, concurrency_value, active_connections → concorrência de negócios
• business_query_monitor: ctime, query, query_id, username, duration_ms, host_id → consultas históricas em tempo real
• business_thread_wait: ctime, wait_event, count, username, host_id → eventos de espera (esperar wal sync, WALWriteLock, etc.)
• bussiness_conflict_lock: ctime, lock_type, blocker, waiter, username, host_id → conflitos de bloqueio

Para diferenças de consulta por etapa, consulte Referência de Métrica.

Especificação de Paginação

Todas as chamadas de ferramenta (MCP e hcloud) devem usar consultas paginadas para evitar que respostas individuais sejam muito grandes e excedam os limites de token.

Regras de Paginação:

• Use limit=200 de forma uniforme (não use valores maiores que 200, exceto a exceção declarada abaixo)
• Exceção explícita: cpu_io_diagnose_detail usa paginação limit=800 (devido ao seu maior volume de dados, multi-nó × multi-instância × multi-ponto no tempo × multi-consulta); uma única página de 200 pode não ser suficiente
• Primeira página offset=0; se a contagem de dados retornados = limit, então offset+=limit e continue consultando
• Repita até que a contagem de dados retornados < limit, então mescle todos os dados paginados
• Ao mesclar, concatene todos os arrays de dados de página em um conjunto de dados completo

Exemplo de Chamada 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)
Se o comprimento dos dados retornados = 200:
Página 2: dws_autopilot_get_metric(project_id, cluster_id, metric_name="IOStat", from_ts, to_ts, limit=200, offset=200)
Se o comprimento dos dados retornados < 200: Pare a paginação, mescle os dados da página 1 + página 2

Exemplo de Chamada hcloud (usando IOStat):

Página 1: hcloud DWS ListMetricsData --cli-region=<região> --cluster_id=<id> --metric_name=IOStat --project_id=<pid> --offset=0 --limit=200 --from=<ts_inicial> --to=<ts_final>
Se a contagem de dados retornados = 200:
Página 2: hcloud DWS ListMetricsData --cli-region=<região> --cluster_id=<id> --metric_name=IOStat --project_id=<pid> --offset=200 --limit=200 --from=<ts_inicial> --to=<ts_final>
Se a contagem de dados retornados < 200: Pare a paginação, mescle os dados

Fluxo de Trabalho

Antes do diagnóstico, crie um plano de execução baseado nas Etapas 0-7 e, em seguida, execute sequencialmente. Para a estratégia de seleção de ferramenta, consulte a seção "Padrão de Formato de Comando KooCLI"; as etapas subsequentes não repetirão isso. Todas as chamadas de ferramenta MCP seguem a seção "Especificação de Paginação"; as etapas subsequentes não repetirão os detalhes de paginação.

Etapa 0: Detecção de Ambiente e Resolução de Parâmetros

Validação de Parâmetros Obrigatórios: Antes de prosseguir, verifique se pelo menos um de cluster_id ou cluster_name foi fornecido (ambos podem ser fornecidos, mas pelo menos um é obrigatório). Se ambos estiverem faltando, solicite ao usuário que forneça um cluster_id ou cluster_name válido e encerre o diagnóstico até que seja fornecido.

Validação de Existência do Cluster: Use a consulta de lista de clusters (hcloud DWS ListClusters no modo hcloud, ou dws_autopilot_get_clusters no modo MCP) para confirmar se o cluster alvo existe:

• Se a consulta retornar os códigos de erro DWS.13026 ou DWS.13032 (cluster não encontrado), ou a lista de clusters retornada não contiver o cluster_id/cluster_name especificado → o cluster não existe. Encerre o diagnóstico e solicite: O cluster DWS especificado não existe. Verifique o cluster_id/cluster_name e tente novamente.
• Se a consulta for bem-sucedida e o cluster existir → continue com as etapas a seguir.

Resolução de Parâmetros: Se project_id ou region_id não for fornecido pelo usuário, leia do arquivo de configuração do MCP Server conf/dws_config.yaml:

• Quando project_id estiver faltando: Execute python -c "import yaml; c=yaml.safe_load(open('conf/dws_config.yaml')); print(c.get('project_id',''))" para obtê-lo
• Quando region_id estiver faltando: Execute python -c "import yaml; c=yaml.safe_load(open('conf/dws_config.yaml')); print(c.get('region_id',''))" para obtê-lo
• Se o campo correspondente no arquivo de configuração também estiver vazio, solicite ao usuário que forneça o parâmetro

Execute hcloud version; versão >= 3.2.0 → tool_mode=hcloud, caso contrário tool_mode=mcp.

Sonda de Disponibilidade de Rede hcloud: Se tool_mode=hcloud, execute uma chamada de API leve (por exemplo, hcloud DWS ListClusters --cli-region=<região> --project_id=<project_id>) para verificar a conectividade de rede:

• Retorna normal ou erro de negócio (por exemplo, permissões insuficientes, erro de parâmetro) → Rede disponível, mantenha tool_mode=hcloud
• Retorna NETWORK_ERROR → Rede indisponível, faça fallback para tool_mode=mcp
• Após o fallback, se o MCP também estiver indisponível → Encerre a execução, solicite ao usuário que verifique a configuração de rede do KooCLI ou a configuração do MCP Server

Etapa 1: Consultar IOStat

Chame a consulta de métrica com metric_name="IOStat", janela de tempo: from_ts=hora_primeiro_alarme - 300000, to_ts=hora_primeiro_alarme. No modo MCP, use consulta paginada com limit=200.

Determinação de Indisponibilidade do Autopilot: Retorna erro 50201/RDS.9999 → Pule as Etapas 1-6, marque todas as métricas como "indisponíveis", prossiga diretamente para a Etapa 7.

Análise: Agrupe por host_id e disk_name, encontre os dados de I/O mais recentes para cada disco em cada nó. Extraia 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.

Determinação de Sobrecarga de I/O: Se algum disco tem util > 90% ou await > 100 ou throughput/IOPS atingindo o limite superior.

Determinação de Desequilíbrio de I/O: Se o desvio de util ou await entre nós > 20%.

Filtragem de Nós TOP: Encontre os dois nós com a maior carga de I/O.

Determinação de Distribuição de Fenômeno: Se um nó tem I/O alto em um único disco ou I/O alto em todos os discos (usado para o roteamento de cenário da Etapa 4).

Pontos de Tempo de I/O Alto: Dos dados da série temporal IOStat, encontre todos os pontos ctime onde qualquer disco util > 90% nos 2 principais nós de I/O. Colete esses valores ctime como high_io_ctimes (lista de timestamps em milissegundos). Registre também o ctime com o maior util como peak_io_ctime. Se nenhum ctime tiver util > 90%, high_io_ctimes estará vazio e peak_io_ctime será o ctime com o maior valor de util.

Saída: 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

Etapa 2: Obter Nomes dos Hosts

Chame a consulta de informações do host (modo MCP com paginação limit=200), construa o mapeamento host_id → {host_name, ...}.

...