Solução de Problemas: Verificação e Interpretação do Status de Saúde do Cluster Elasticsearch

Solução de Problemas: Verificando e Interpretando o Status de Saúde do Cluster Elasticsearch

O Elasticsearch é um mecanismo de busca e análise robusto e distribuído, mas sua natureza distribuída exige monitoramento constante para garantir a integridade dos dados e a alta disponibilidade. O primeiro e mais crucial passo na administração é verificar o status de saúde do cluster. Um status saudável garante que todos os segmentos de dados primários e de réplica (shards) estejam corretamente atribuídos aos nós e operacionais.

Este guia oferece uma abordagem prática para verificar a saúde do cluster usando a API essencial _cat/health. Detalharemos como interpretar os status codificados por cores (Verde, Amarelo, Vermelho) e forneceremos etapas acionáveis para diagnosticar e resolver problemas comuns de instabilidade, ajudando os administradores a restaurar rapidamente o desempenho ideal do cluster.

Entendendo o Status de Saúde do Elasticsearch

O Elasticsearch usa um sistema simples de semáforo codificado por cores para comunicar o status operacional dos índices e shards do cluster. Esse status reflete o estado de atribuição dos shards primários e de réplica.

Os Três Estados Principais de Saúde

Status	Significado	Disponibilidade de Dados	Redundância	Ação Necessária
Verde	Todos os shards primários e de réplica estão atribuídos e operacionais.	100% Disponível	Total	Somente Monitoramento
Amarelo	Todos os shards primários estão atribuídos, mas um ou mais shards de réplica estão não atribuídos.	100% Disponível	Comprometida	Investigar/Resolver Atribuição de Réplicas
Vermelho	Um ou mais shards primários estão não atribuídos.	Perda/Indisponibilidade Parcial ou Total de Dados	Gravemente Comprometida	Intervenção Imediata

Verificando a Saúde do Cluster com `_cat/health`

As APIs _cat são projetadas para diagnósticos rápidos e legíveis por humanos. O endpoint _cat/health é a maneira mais rápida de obter uma visão geral do estado atual do cluster.

Comando Básico

Você pode executar este comando usando cURL, o console Kibana Dev Tools ou qualquer cliente HTTP.

# Usando cURL (Formato legível por humanos)
curl -X GET "localhost:9200/_cat/health?v&pretty"

Interpretando a Saída do `_cat/health`

Uma consulta bem-sucedida retorna uma tabela com as métricas chave:

Coluna	Descrição
`epoch`	O tempo (timestamp Unix) em que a solicitação foi executada.
`timestamp`	O tempo no formato HH:MM:SS.
`cluster`	O nome do cluster.
`status`	O indicador de cor crucial (Verde, Amarelo ou Vermelho).
`node.total`	Número total de nós atualmente conectados ao cluster.
`node.data`	Número de nós de dados no cluster.
`shards`	Número total de shards (primário + réplica) que devem estar ativos.
`pri`	Número total de shards primários.
`relo`	Número de shards atualmente em realocação entre nós.
`init`	Número de shards atualmente em inicialização.
`unassign`	Número de shards que estão atualmente não atribuídos.

Exemplo de um Cluster Saudável (Verde):

epoch      timestamp cluster       status node.total node.data shards pri relo init unassign
1678886400 10:30:00  my-cluster-dev green         3         3     30  15    0    0        0

Diagnosticando Status: Amarelo

Quando um cluster reporta o status Amarelo, isso significa que, embora todos os seus dados estejam tecnicamente disponíveis (todos os shards primários estão atribuídos), o nível de redundância definido não está sendo atendido. Um ou mais shards de réplica não puderam ser alocados.

Causas Comuns do Status Amarelo

Perda de Nó (Temporário): Um nó de dados que hospeda shards de réplica ficou offline. O Elasticsearch está esperando que esse nó retorne ou que um novo nó se junte antes de tentar a realocação.
Nós Insuficientes: Se você exigir 2 réplicas (3 cópias dos dados no total), mas tiver apenas 2 nós de dados, a terceira cópia não poderá ser colocada, levando a um status Amarelo permanente até que outro nó seja adicionado.
Alocação Atrasada: O cluster está configurado para atrasar a alocação de réplicas após uma falha de nó para evitar um rebalanceamento imediato e custoso caso o nó retorne rapidamente.
Restrições de Espaço em Disco: Os nós podem ter espaço em disco insuficiente para hospedar os shards de réplica.

Etapas Acionáveis para o Status Amarelo

Verificar Shards Não Atribuídos: Use a API _cat/shards para identificar exatamente quais shards estão não atribuídos (u) e por que estão esperando.

bash curl -X GET "localhost:9200/_cat/shards?v"
Usar a Allocation Explain API: Para diagnósticos detalhados sobre por que um shard específico está não atribuído, use a Allocation Explain API. Substitua index_name e shard_id abaixo pelos valores reais encontrados via _cat/shards.

bash curl -X GET "localhost:9200/_cluster/allocation/explain?pretty" -H 'Content-Type: application/json' -d' { "index": "index_name", "shard": 0, "primary": false } '

Procure especificamente nos campos unassigned_info e decisions por razões como CLUSTER_REBALANCE_ALLOCATION_DELAY ou NO_VALID_TARGET_NODE.
Verificar a Contagem e Configuração dos Nós: Garanta que o número de nós de dados atenda ou exceda o número necessário de réplicas mais um (N réplicas + 1 primário).

Dica: Se o cluster estiver Amarelo devido a uma manutenção conhecida de curto prazo em um nó, muitas vezes você pode ignorá-lo temporariamente, mas esteja ciente de que estará operando sem redundância.

Diagnosticando Status: Vermelho

Um status Vermelho é crítico e significa que um ou mais shards primários estão não atribuídos. Isso significa que os dados armazenados nesse shard estão completamente indisponíveis para indexação ou pesquisa.

Causas Comuns do Status Vermelho

Falha Massiva de Nó: Um nó primário falhou e nenhum outro nó pôde assumir com sucesso a função primária porque os dados foram corrompidos ou ficaram totalmente indisponíveis no restante do cluster.
Corrupção/Falha de Disco: O dispositivo de armazenamento contendo o shard primário falhou e não existe réplica para ser promovida.
Problemas de Configuração de Índice: Má configuração ou exclusão incorreta de arquivos de índice no nível do sistema de arquivos.

Intervenção Imediata para o Status Vermelho

Sempre faça backup do seu cluster (via snapshots) antes de tentar ações manuais de recuperação quando o cluster estiver Vermelho.

Verificar Logs Imediatamente: Revise os logs do nó mestre e do(s) nó(s) que hospedam o shard primário com falha para identificar a exceção exata ou o motivo da falha (muitas vezes relacionado a falha de disco ou erros de falta de memória).
Identificar o Índice com Falha: Use _cat/shards para encontrar o índice associado ao primário não atribuído (p).

```bash

Procure por linhas onde o estado é 'UNASSIGNED' e o primário é 'p'

curl -X GET "localhost:9200/_cat/shards?h=index,shard,prirep,state,unassigned.reason"
```
Tentar Reroute Forçado (Perigoso - Usar como Último Recurso): Se você tiver certeza de que os dados existem em um dos nós (por exemplo, um nó voltou a funcionar, mas o roteamento não foi corrigido), você pode tentar um reroute manual. Isso é frequentemente usado quando um shard primário é permanentemente perdido e você decide descartar os dados perdidos e forçar um novo primário vazio em um nó saudável.

```bash

CUIDADO: Este comando pode levar à perda de dados se usado incorretamente.

Ele atribui um shard primário vazio a um nó, marcando o índice como saudável.

curl -X POST "localhost:9200/_cluster/reroute?pretty" -H 'Content-Type: application/json' -d'
{
"commands" : [
{
"allocate_empty_primary" : {
"index" : "failed_index_name",
"shard" : 0,
"node" : "target_node_name",
"accept_data_loss" : true
}
}
]
}
'
```
Restaurar de Snapshot: Se o shard primário com falha não puder ser recuperado, a única maneira segura de restaurar a integridade dos dados é restaurar o índice afetado a partir do snapshot mais recente bem-sucedido.

Diagnósticos Avançados: Configurações do Cluster

Às vezes, o status do cluster é Vermelho ou Amarelo devido a ações administrativas ou salvaguardas operacionais pré-configuradas.

Verificando a Alocação de Roteamento do Cluster

A API _cluster/settings permite verificar se a alocação automática de shards foi explicitamente desativada, o que impediria o cluster de se curar.

# Recuperar as configurações atuais do cluster
curl -X GET "localhost:9200/_cluster/settings?include_defaults=true&pretty"

Procure especificamente pela seguinte configuração:

{
  "persistent": {
    "cluster": {
      "routing": {
        "allocation": {
          "enable": "none" 
        }
      }
    }
  }
}

Se cluster.routing.allocation.enable estiver definido como none (ou primaries), o Elasticsearch não alocará shards, bloqueando o cluster em seu estado atual (provavelmente Amarelo ou Vermelho).

Reativando a Alocação

Para restaurar a alocação normal de shards, atualize a configuração para all:

curl -X PUT "localhost:9200/_cluster/settings?pretty" -H 'Content-Type: application/json' -d'
{
  "persistent": {
    "cluster.routing.allocation.enable": "all"
  }
}
'

Conclusão

Interpretar o status de saúde do cluster Elasticsearch é a habilidade fundamental para qualquer administrador. A API _cat/health fornece uma visão imediata da integridade operacional dos seus dados. Embora um status Verde seja o objetivo, entender que Amarelo significa redundância reduzida e Vermelho significa dados indisponíveis permite a solução de problemas precisa e imediata usando ferramentas secundárias como _cat/shards e a Allocation Explain API. O monitoramento regular e o snapshotting proativo continuam sendo as melhores defesas contra falhas críticas do cluster.