Solução de Problemas na Saúde do Cluster Elasticsearch: Um Guia Passo a Passo

Solução de Problemas de Saúde do Cluster Elasticsearch: Um Guia Passo a Passo

Elasticsearch é um sistema distribuído robusto, mas, como qualquer arquitetura distribuída, requer monitoramento ativo e intervenção ocasional para manter a saúde ideal. O status de saúde do cluster é a métrica mais crítica para determinar a prontidão operacional e a segurança dos dados da sua implantação. Quando o cluster transita de Verde para Amarelo ou, criticamente, para Vermelho, a integridade ou a disponibilidade dos dados é ameaçada.

Este guia abrangente fornece etapas especializadas para diagnosticar e resolver problemas comuns de saúde do cluster Elasticsearch, focando especificamente na recuperação de status Amarelo e Vermelho. Usaremos APIs Cat práticas e verificações passo a passo para identificar rapidamente a causa raiz e implementar ações corretivas.

1. Compreendendo o Status de Saúde do Cluster Elasticsearch

Antes de solucionar problemas, é essencial entender o que cada cor de saúde do cluster significa. O status de saúde é determinado pelo estado de alocação de seus shards primários e de réplica nos nós do cluster.

Status	Significado	Implicações
Verde	Todos os shards primários e de réplica estão alocados com sucesso.	O cluster está totalmente operacional e resiliente.
Amarelo	Todos os shards primários estão alocados, mas um ou mais shards de réplica estão não alocados.	Os dados estão disponíveis, mas o cluster carece de resiliência total a falhas de nós.
Vermelho	Pelo menos um shard primário está não alocado (e, portanto, indisponível).	Perda de dados ou inacessibilidade para o índice que contém o(s) shard(s) com falha. Ação crítica necessária.

2. Diagnóstico Inicial: Verificando a Saúde do Cluster

O primeiro passo em qualquer processo de solução de problemas é confirmar o status atual e coletar métricas básicas usando a API Cluster Health e a API Nodes.

Passo 2.1: Verificar a Saúde do Cluster

Use a API _cat/health para obter um resumo de alto nível. O parâmetro ?v fornece uma saída detalhada (verbose), incluindo o número de nós e a contagem total de shards.

GET /_cat/health?v

Exemplo de Saída (Status Amarelo):

epoch      timestamp cluster       status node.total node.data shards  pri relo init unassign pending_tasks max_task_wait_time active_shards_percent
1678233600 09:00:00  my-cluster    yellow 3          3         10     5    0    0        5 0             -                  50.0%

Se o status for Amarelo ou Vermelho, anote o valor em unassign.

Passo 2.2: Verificar o Status e a Memória do Nó

Certifique-se de que todos os nós esperados estejam conectados e operando corretamente. Além disso, verifique a utilização do heap (crítica para o desempenho e a estabilidade).

GET /_cat/nodes?v&h=name,node.role,version,heap.percent,disk.total,disk.used,disk.avail

Se um nó estiver faltando nesta lista, você pode ter um problema de conectividade ou um serviço interrompido.

3. Resolvendo o Status Vermelho do Cluster (Falha do Shard Primário)

Um status Vermelho significa que os dados estão imediatamente inacessíveis. O objetivo é trazer o shard primário de volta online o mais rápido possível.

Passo 3.1: Identificar os Shards Primários Não Alocados

Use a API _cat/shards para identificar o índice exato e o shard que estão causando o problema. Procure especificamente por entradas marcadas como UNASSIGNED com uma função p (primário).

GET /_cat/shards?v | grep UNASSIGNED

Exemplo de Saída:

index_logs 0 p UNASSIGNED

Passo 3.2: Verificar a Explicação da Alocação

Este é o passo de diagnóstico mais importante. A API Allocation Explain informa por que um shard específico (ou qualquer shard não alocado) não pode ser alocado.

GET /_cluster/allocation/explain

Razões Comuns para Status Vermelho:

Falha do Nó: O nó que continha o shard primário travou ou foi removido do cluster. Se o nó com falha tiver réplicas suficientes em outros nós, o shard primário deve automaticamente promover uma réplica. Se todas as cópias (primárias e réplicas) estavam no nó com falha, o shard está perdido, a menos que o nó seja recuperado.
Dados Corrompidos: Os arquivos do shard primário no disco foram corrompidos, impedindo que o nó os inicialize.

Passo 3.3: Plano de Ação para Status Vermelho

Cenário A: Nó Offline (Preferencial)
- Se o nó que continha o shard primário estiver simplesmente offline, restaure o serviço do nó (por exemplo, reinicie o Elasticsearch ou corrija problemas de rede). Assim que o nó se juntar novamente ao cluster, o shard primário deve se recuperar.
Cenário B: Shard Primário Perdido (Último Recurso)
- Se o nó estiver permanentemente perdido e não existirem réplicas, os dados se foram. Você deve pular manualmente a recuperação usando o comando allocate_empty_primary. Aviso: Isso criará um novo shard primário vazio, resultando em perda permanente de dados para esse segmento do índice.

POST /_cluster/reroute
{
  "commands" : [
    {
      "allocate_empty_primary" : {
        "index" : "[index-name]", 
        "shard" : [shard-id],
        "node" : "[target-node-name]", 
        "accept_data_loss" : true
      }
    }
  ]
}

Melhor Prática: Antes de recorrer a allocate_empty_primary, verifique sempre se não existe um snapshot ou backup para o índice.

4. Resolvendo o Status Amarelo do Cluster (Falha do Shard de Réplica)

Um status Amarelo significa que o cluster está operacional, mas vulnerável. O objetivo principal é alocar as réplicas ausentes.

Passo 4.1: Usar Allocation Explain

Se o status for Amarelo, use a API _cluster/allocation/explain (Seção 3.2) para entender por que a réplica não pode ser atribuída. A explicação para as réplicas é tipicamente mais direta.

Razões Comuns para Status Amarelo:

Código de Razão	Explicação	Correção
`NO_AVAILABLE_NODES`	O tamanho do cluster é muito pequeno (por exemplo, a contagem de réplicas é 2, mas existem apenas 2 nós).	Adicione mais nós de dados ou reduza `number_of_replicas`.
`NOT_ENOUGH_DISK_SPACE`	Os nós atingiram o limite mínimo ou máximo de marca d'água (watermark).	Exclua índices antigos, libere espaço em disco ou ajuste as marcas d'água de disco.
`ALLOCATION_DISABLED`	A alocação de shard foi explicitamente desabilitada nas configurações do cluster.	Reative o roteamento usando `PUT /_cluster/settings`.
`PRIMARY_NOT_ACTIVE`	O shard primário ainda está inicializando ou se recuperando.	Aguarde até que o primário se torne ativo (Verde).

Passo 4.2: Verificando Requisitos e Restrições de Nó

Certifique-se de que o cluster atenda aos requisitos básicos para alocação de réplicas:

Contagem de Nós: Para N réplicas, você precisa de pelo menos N+1 nós de dados para garantir que o primário e as réplicas nunca estejam no mesmo nó.
Marcas D'água de Disco (Disk Watermarks): O Elasticsearch para de alocar shards para nós quando o uso do disco excede a marca d'água alta (padrão 90%).

# Verificar as configurações de alocação de disco
GET /_cluster/settings?flat_settings=true&filter_path=*watermark*

# Exemplo: Definir marca d'água alta para 95% (Temporariamente!)
PUT /_cluster/settings
{
  "persistent": {
    "cluster.routing.allocation.disk.watermark.high": "95%"
  }
}

Passo 4.3: Roteamento Manual (Se a Lógica de Alocação Falhar)

Em casos raros, se o processo de alocação padrão parecer travado, apesar de recursos suficientes, você pode forçar manualmente a alocação da réplica para um nó saudável específico usando o comando allocate_replica.

POST /_cluster/reroute
{
  "commands" : [
    {
      "allocate_replica" : {
        "index" : "[index-name]", 
        "shard" : [shard-id],
        "node" : "[target-node-name]"
      }
    }
  ]
}

5. Solução de Problemas Avançada e Armadilhas Comuns

Se o status Vermelho ou Amarelo persistir, a causa raiz pode estar fora da lógica padrão de alocação de shards.

5.1 Conectividade de Rede e Split-Brain

Em sistemas distribuídos, o particionamento (split-brain) pode causar problemas graves. Se os nós elegíveis para mestre não puderem se comunicar, o cluster pode falhar em eleger um mestre estável, levando a shards não alocados.

Ação: Verifique a conectividade de rede entre todos os nós, especialmente entre nós elegíveis para mestre.
Verificação de Configuração: Certifique-se de que sua lista discovery.seed_hosts esteja precisa e que a configuração cluster.initial_master_nodes foi usada corretamente durante o bootstrap do cluster.

5.2 Alta Pressão de Memória JVM

O uso excessivo de heap (muitas vezes acima de 75%) leva a pausas frequentes e longas de Garbage Collection (GC). Durante essas pausas, um nó pode parecer não responsivo, fazendo com que o nó mestre o remova, o que leva a shards não alocados.

Ação: Monitore o uso do heap (_cat/nodes?h=heap.percent). Se estiver consistentemente alto, considere aumentar a memória do nó, otimizar processos de indexação ou implementar o gerenciamento do ciclo de vida do índice (ILM).

5.3 Filtragem de Alocação de Shards

A aplicação acidental de filtros de alocação (usando atributos de nó como tags ou IDs) pode impedir que os shards sejam alocados para nós que de outra forma seriam elegíveis.

# Verificar regras de alocação no nível do índice
GET /[index-name]/_settings
# Procurar por: index.routing.allocation.require.*

# Redefinir regras de alocação de índice (se necessário)
PUT /[index-name]/_settings
{
  "index.routing.allocation.require": null
}

Lista de Verificação Resumida para Recuperação Rápida

Status	Ferramenta de Diagnóstico Primária	Etapas Chave de Ação
Amarelo	`GET /_cluster/allocation/explain`	1. Verifique o espaço em disco. 2. Verifique a contagem de nós vs. contagem de réplicas. 3. Procure regras de filtragem de alocação. 4. Aguarde a recuperação primária.
Vermelho	`GET /_cat/shards?v \| grep UNASSIGNED`	1. Verifique os logs no nó que hospedava anteriormente. 2. Tente reiniciar o nó com falha. 3. Se o primário estiver confirmado como perdido e não houver backup, use `allocate_empty_primary` (Risco de perda de dados).

Ao utilizar sistematicamente as APIs _cat e o endpoint crítico _cluster/allocation/explain, você pode identificar rapidamente a causa da degradação da saúde do cluster e implementar as etapas corretivas necessárias para restaurar seu cluster ao status estável Verde.