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

A saúde do cluster Elasticsearch é uma daquelas verificações que parecem simples até o pager disparar. A API fornece uma cor, mas a cor é apenas o ponto de partida. Um cluster verde ainda pode ser lento. Um cluster amarelo pode ser perfeitamente utilizável durante uma janela de manutenção curta. Um cluster vermelho pode significar que um pequeno índice de teste está indisponível, ou pode significar que a pesquisa voltada para o cliente está perdendo dados reais.

Quando verifico a saúde do cluster Elasticsearch, tento não pular direto de vermelho para comandos de recuperação perigosos. Quero responder a três perguntas primeiro: os shards primários estão atribuídos, as réplicas estão atribuídas e o cluster está atualmente tentando se recuperar sozinho? Os comandos abaixo são os que uso para passar de uma cor de saúde ampla para um motivo específico.

Comece com a API de saúde

Para uma visualização rápida no terminal, _cat/health é suficiente:

curl -s "http://localhost:9200/_cat/health?v"

Uma resposta típica se parece com isso:

epoch      timestamp cluster     status node.total node.data shards pri relo init unassign pending_tasks
1762219800 12:10:00  logs-prod   yellow          3         3    124  62    0    0        2             0

Os campos que observo primeiro são status, node.total, node.data, relo, init, unassign e pending_tasks. Um status amarelo com init ou relo maior que zero pode ser simplesmente um cluster se recuperando após uma reinicialização. Um status amarelo com shards não atribuídos e nenhum movimento geralmente precisa de investigação.

Para automação, use a API JSON em vez de analisar a saída _cat:

curl -s "http://localhost:9200/_cluster/health?pretty"

Essa resposta inclui campos como active_primary_shards, active_shards, relocating_shards, initializing_shards, unassigned_shards e delayed_unassigned_shards. Esses nomes são mais fáceis de usar em scripts e verificações de monitoramento.

O que verde, amarelo e vermelho realmente significam

Verde significa que todo shard primário e toda réplica configurada estão atribuídos. Isso não significa que as consultas são rápidas, o disco está saudável ou os mapeamentos são bem projetados. Significa apenas que o Elasticsearch colocou os shards que deveria colocar.

Amarelo significa que todos os shards primários estão atribuídos, mas pelo menos um shard de réplica não está atribuído. Seus dados ainda devem ser pesquisáveis porque os primários estão disponíveis. O risco é a redundância. Se o nó que contém um primário falhar enquanto sua réplica ainda não estiver atribuída, esse índice pode se tornar vermelho.

Vermelho significa que pelo menos um shard primário não está atribuído. As pesquisas nos índices afetados podem falhar ou retornar resultados parciais, e as gravações nesses shards não podem prosseguir normalmente. O vermelho merece atenção imediata, mas a ação correta depende do motivo pelo qual o primário não está atribuído.

Um exemplo comum de cluster pequeno é um cluster de desenvolvimento de nó único com uma réplica configurada. Ele permanecerá amarelo porque o Elasticsearch não colocará uma réplica no mesmo nó que seu primário. Isso não é um mistério e não é motivo para forçar a alocação. Adicione outro nó de dados ou defina réplicas como zero para esse índice:

curl -X PUT "http://localhost:9200/my-index/_settings"   -H 'Content-Type: application/json'   -d '{"index":{"number_of_replicas":0}}'

Não use essa configuração casualmente em produção. Ela remove a redundância para esse índice.

Encontre os shards não atribuídos exatos

Após a cor de saúde, liste os shards:

curl -s "http://localhost:9200/_cat/shards?v&h=index,shard,prirep,state,node,unassigned.reason" | sort

Procure por UNASSIGNED. A coluna prirep informa se o shard é primário (p) ou réplica (r). Essa distinção importa mais do que a cor em si. Algumas réplicas não atribuídas geralmente significam tolerância a falhas reduzida. Um primário não atribuído significa que pelo menos parte de um índice está indisponível.

Se você vir muitos shards não atribuídos após uma reinicialização planejada de nó, verifique também a alocação atrasada:

curl -s "http://localhost:9200/_cluster/health?pretty" | grep delayed_unassigned_shards

O Elasticsearch pode esperar antes de realocar réplicas após a saída de um nó, porque o nó pode voltar rapidamente. Esse comportamento evita rotatividade desnecessária de rede e disco durante reinicializações contínuas.

Pergunte ao Elasticsearch por que a alocação falhou

A API de explicação de alocação é o melhor próximo passo. Você pode perguntar sobre qualquer shard não atribuído:

curl -X GET "http://localhost:9200/_cluster/allocation/explain?pretty"   -H 'Content-Type: application/json'   -d '{}'

Ou perguntar sobre um shard específico:

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

Leia unassigned_info, can_allocate e node_allocation_decisions. A parte útil geralmente está em inglês simples: limite de disco excedido, alocação desabilitada, nenhum atributo de nó correspondente, muitos shards em um nó ou uma réplica não pode ser colocada porque existe apenas um nó.

Se a explicação disser allocation_delayed, espere apenas se o nó ausente deve retornar em breve. Se a explicação disser que nenhum nó satisfaz as regras de alocação, esperar não vai resolver.

Manual do cluster amarelo

Para saúde amarela, uso esta ordem:

1. Verifique se o cluster tem nós de dados suficientes para o número de réplicas configurado.
2. Verifique os limites de disco com _cat/allocation.
3. Verifique se a alocação foi desabilitada durante a manutenção.
4. Verifique filtros de roteamento no nível do índice e regras de awareness.
5. Decida se deve adicionar capacidade, reduzir o número de réplicas ou corrigir uma regra ruim.

A verificação do número de nós é simples. Se um índice tem number_of_replicas: 2, o Elasticsearch precisa de três nós de dados adequados para colocar um primário mais duas réplicas. "Adequado" importa. Se a awareness de alocação exigir zonas separadas, você precisa de nós nessas zonas, não apenas de quaisquer três nós.

Verifique alocação e disco:

curl -s "http://localhost:9200/_cat/allocation?v"

Se os nós estiverem acima dos limites de disco, o Elasticsearch pode recusar novas alocações de shard. Libere espaço, adicione nós, expanda discos ou exclua índices antigos após tirar snapshots. Aumentar os limites pode ganhar tempo em uma emergência controlada, mas não cria capacidade.

Verifique as configurações de alocação:

curl -s "http://localhost:9200/_cluster/settings?include_defaults=true&pretty"

Se cluster.routing.allocation.enable for none, a alocação está desabilitada. Isso é comum após scripts de manutenção que esqueceram de reativá-la. Reative-a com:

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

Verifique também se o valor foi definido como transient; configurações persistentes e transitórias podem afetar o comportamento.

Manual do cluster vermelho

Para saúde vermelha, vá devagar e identifique o raio de explosão. Não comece com allocate_empty_primary. Esse comando aceita perda de dados por design.

Primeiro, encontre os shards primários afetados:

curl -s "http://localhost:9200/_cat/shards?v&h=index,shard,prirep,state,node,unassigned.reason"   | grep ' p '   | grep UNASSIGNED

Em seguida, inspecione um com a explicação de alocação:

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

Se o primário não estiver atribuído porque um nó está inativo, sua melhor recuperação pode ser restaurar esse nó. Verifique o serviço, disco, logs JVM e caminho de rede. Se existir uma cópia de réplica em outro nó, o Elasticsearch normalmente deve promovê-la. Se não o fizer, a saída de explicação e os logs geralmente informam o motivo.

Se os dados forem perdidos ou corrompidos, restaure de um snapshot. Esse é o caminho de recuperação limpo. Se não existir snapshot e os dados puderem ser reconstruídos de outra fonte, você pode decidir alocar um primário vazio:

curl -X POST "http://localhost:9200/_cluster/reroute?pretty"   -H 'Content-Type: application/json'   -d '{
    "commands": [
      {
        "allocate_empty_primary": {
          "index": "affected-index",
          "shard": 0,
          "node": "target-node-name",
          "accept_data_loss": true
        }
      }
    ]
  }'

Use isso apenas quando perder o conteúdo do shard for aceitável. O nome é literal: o Elasticsearch aloca um primário vazio e segue em frente.

Observe a recuperação em vez de adivinhar

Após uma correção, observe o movimento dos shards:

curl -s "http://localhost:9200/_cat/recovery?v&active_only=true"
curl -s "http://localhost:9200/_cat/shards?v&h=index,shard,prirep,state,node,unassigned.reason"
curl -s "http://localhost:9200/_cluster/health?pretty"

A recuperação pode ser limitada pela velocidade do disco, largura de banda da rede, tamanho do shard e configurações de recuperação do cluster. Um shard grande pode ficar em INITIALIZING por mais tempo do que o esperado. Isso é diferente de estar travado. Se as contagens de bytes e arquivos estão se movendo em _cat/recovery, deixe funcionar.

Verifique também tarefas pendentes do cluster quando a saúde não estiver mudando:

curl -s "http://localhost:9200/_cat/pending_tasks?v"

Uma fila longa pode apontar para um nó mestre sobrecarregado ou decisões de alocação repetidas que não podem ser concluídas.

Um exemplo prático

Digamos que _cat/health mostre amarelo com dois shards não atribuídos. _cat/shards mostra que ambos são réplicas para logs-2026.05.24. A explicação de alocação diz que o cluster não pode alocar porque cada nó de dados está acima do limite de disco baixo. A correção não é redirecionar shards manualmente. A correção é capacidade: exclua índices antigos após fazer snapshots, adicione armazenamento, adicione nós de dados ou mova dados frios para outro lugar.

Outro exemplo: um cluster de três nós está amarelo após uma reinicialização contínua. _cluster/health mostra delayed_unassigned_shards: 8. O nó parado já está voltando. Nesse caso, esperar alguns minutos pode ser correto. Forçar a alocação imediatamente pode criar trabalho extra de recuperação e tornar a reinicialização mais lenta.

Um terceiro exemplo: um cluster de laboratório de nó único está amarelo para sempre. _cat/shards mostra que todo shard não atribuído é uma réplica. O índice tem uma réplica. O Elasticsearch está se comportando corretamente. Defina réplicas como zero para o laboratório ou adicione um segundo nó de dados.

Mantenha a verificação de saúde honesta

A saúde do cluster deve fazer parte do monitoramento, mas as regras de alerta precisam de contexto. Alerte imediatamente no vermelho. Alerte no amarelo quando durar além de uma curta janela de manutenção, quando as réplicas não atribuídas estiverem aumentando ou quando o motivo for pressão de disco. Monitore os limites de disco, número de nós, pressão JVM e sucesso de snapshot junto com a cor de saúde. A cor informa por onde começar; as APIs de shard e alocação informam o que fazer em seguida.

Quando as verificações de saúde discordam dos sintomas do usuário

Às vezes o cluster está verde e os usuários ainda estão reclamando. Isso não é uma contradição. A saúde do cluster é sobre atribuição de shards, não latência ou correção de consultas. Se a saúde está verde, mas as pesquisas estão lentas, vá para latência de pesquisa, pools de threads, shards quentes, pressão JVM e latência de armazenamento. Um cluster verde com um nó de dados sobrecarregado ainda pode parecer quebrado.

O oposto também acontece. Um cluster pode estar amarelo por um motivo inofensivo, como um ambiente de desenvolvimento de nó único com réplicas configuradas. O hábito útil é conectar o estado de saúde ao impacto nos negócios. Qual índice está afetado? É um primário ou réplica? O aplicativo está lendo desse índice agora? Isso é durante manutenção planejada? Essas perguntas impedem que você trate todo status amarelo como um desastre.

Para sistemas voltados para o cliente, gosto de manter uma pequena tabela de runbook fora do Elasticsearch: padrão de índice, serviço proprietário, fonte de dados, política de snapshot, se os dados podem ser reproduzidos e quem aprova a recuperação destrutiva. Durante um incidente vermelho, essa tabela geralmente é mais útil do que outro painel. Se clickstream-* pode ser reproduzido a partir do Kafka, a escolha de recuperação é diferente de um índice que contém documentos gerados pelo usuário sem cópia upstream.

Hábitos de comando mais seguros

Use nomes de índice explícitos quando puder. Curingas são convenientes, mas escondem o raio de explosão. Antes de executar qualquer comando que altere configurações ou exclua dados, liste o que o padrão corresponde:

curl -s "http://localhost:9200/_cat/indices/logs-prod-*?v&s=index"

Mantenha a saída do comando do incidente. Cole os resultados da explicação de alocação, listagens de shards e respostas de saúde no ticket. O estado do Elasticsearch muda rapidamente durante a recuperação, e você pode precisar da saída anterior para entender por que uma decisão foi tomada.

Se a segurança estiver ativada, execute esses comandos com um usuário que tenha os privilégios mínimos úteis para diagnósticos e um processo separado e mais restrito para operações destrutivas. Em um incidente estressante, é muito fácil colar um comando de gravação no mesmo shell onde você estava apenas inspecionando a saúde.

O que verificar depois que o cluster retornar ao verde

Verde não é o fim do incidente. Verifique se as réplicas foram reconstruídas nos nós esperados, se o disco ainda está próximo dos limites, e se algum índice foi deixado com configurações temporárias como number_of_replicas: 0, um refresh_interval longo ou alocação desabilitada.

Confirme também se os snapshots estão sendo bem-sucedidos após a recuperação. Um cluster que acabou de ter problemas de shard pode ter exposto uma lacuna na retenção, credenciais do repositório ou agendamento de snapshot. Se a recuperação dependeu da sorte porque nenhum snapshot existia, anote isso e corrija antes da próxima falha.

Finalmente, revise os alertas. Se os humanos notaram o problema antes do monitoramento, adicione ou ajuste alertas para saúde vermelha, saúde amarela duradoura, pressão de limite de disco, nós ausentes, snapshots com falha e eleições de mestre repetidas. Uma cor de saúde do cluster é útil, mas o melhor alerta informa por que a cor mudou e qual índice está afetado.