Ferramentas e Técnicas Essenciais para Depurar Problemas em Clusters Elasticsearch

Problemas em clusters Elasticsearch geralmente se manifestam como status de saúde red ou yellow, buscas lentas, escritas rejeitadas ou nós saindo do cluster. A maneira mais rápida de depurá-los é começar pela saúde do cluster, depois restringir o problema a shards, nós, regras de alocação, logs ou pressão sobre recursos.

Este guia aborda as ferramentas integradas que você usará com mais frequência: APIs _cat, _cluster/allocation/explain, estatísticas de nós, tarefas pendentes e logs do Elasticsearch.

Entendendo a Saúde do Cluster Elasticsearch

A saúde do cluster fornece o primeiro sinal:

green: Todos os shards primários e réplicas estão alocados.
yellow: Todos os shards primários estão alocados, mas um ou mais shards de réplica não estão.
red: Um ou mais shards primários não estão atribuídos, então alguns dados estão indisponíveis.

Um cluster yellow ainda pode atender leituras e escritas para shards primários disponíveis, mas tem menos redundância. Um cluster red precisa de investigação imediata porque shards primários afetados estão indisponíveis.

Comece com as APIs `_cat`

As APIs _cat são feitas para verificações rápidas e legíveis por humanos.

curl -X GET "localhost:9200/_cat/health?v"
curl -X GET "localhost:9200/_cat/nodes?v&h=name,ip,heap.percent,ram.percent,cpu,disk.used_percent,load_1m,node.role"
curl -X GET "localhost:9200/_cat/shards?v"
curl -X GET "localhost:9200/_cat/indices?v"

Use _cat/health para confirmar o estado geral. Use _cat/shards para encontrar shards UNASSIGNED, INITIALIZING ou realocando repetidamente. Use _cat/nodes para identificar pressão de heap, CPU ou disco em um nó específico.

Para um cluster red ou yellow, este comando fornece uma visão focada:

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

Explique a Alocação de Shards

Quando um shard não está atribuído, _cluster/allocation/explain informa por que o Elasticsearch não consegue colocá-lo.

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

Você também pode pedir ao Elasticsearch para explicar o primeiro shard não atribuído que encontrar:

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

Leia os campos can_allocate, allocate_explanation e node_allocation_decisions. Causas comuns incluem watermarks de disco, filtros de alocação, nós ausentes, configurações de índice incompatíveis ou número insuficiente de nós de dados para a contagem de réplicas solicitada.

Verifique Estatísticas de Nós e do Cluster

Quando a saúde está verde, mas buscas ou escritas estão lentas, verifique a pressão sobre os recursos.

curl -X GET "localhost:9200/_nodes/stats/jvm,fs,os,process,thread_pool?pretty"
curl -X GET "localhost:9200/_cluster/stats?pretty"

Procure por uso elevado de heap JVM, pressão de disco, tarefas de busca ou escrita rejeitadas e nós com carga muito maior que seus pares. Um único nó sobrecarregado pode desacelerar todo o cluster se ele possuir shards quentes.

Para rejeições de thread pool, use:

curl -X GET "localhost:9200/_cat/thread_pool/search,write?v&h=node_name,name,active,queue,rejected,completed"

Tarefas rejeitadas geralmente significam que o nó não conseguiu acompanhar a taxa de requisições. Corrija a causa antes de aumentar as filas: reduza o custo das consultas, distribua shards, dimensione nós ou reduza a indexação em lote.

Revise Tarefas Pendentes e Recuperação

Se as mudanças no estado do cluster parecerem travadas, verifique as tarefas pendentes:

curl -X GET "localhost:9200/_cluster/pending_tasks?pretty"

Uma fila longa pode indicar pressão no nó mestre, atualizações frequentes de mapeamento, rotatividade de shards ou nós instáveis.

Para movimentação e recuperação de shards, use:

curl -X GET "localhost:9200/_cat/recovery?v&active_only=true"

Isso ajuda a distinguir um cluster que está se recuperando ativamente de um que está bloqueado por regras de alocação ou dados ausentes.

Leia os Logs do Elasticsearch

Os logs do Elasticsearch frequentemente explicam o que as APIs apenas sugerem. Verifique os logs no nó afetado, não apenas em um nó aleatório do cluster.

Procure por mensagens como:

master not discovered
flood-stage disk watermark
circuit_breaking_exception
rejected execution
failed to obtain node locks
shard failed

Por exemplo, um watermark de disco em estágio de inundação pode bloquear escritas definindo índices afetados como somente leitura até que a pressão de disco seja resolvida. Após liberar espaço em disco ou adicionar capacidade, remova o bloqueio de escrita somente depois de entender por que o disco encheu:

curl -X PUT "localhost:9200/*/_settings?expand_wildcards=all" \
  -H 'Content-Type: application/json' -d'
{
  "index.blocks.read_only_allow_delete": null
}'

Um Fluxo Prático de Depuração

Use esta ordem quando não tiver certeza por onde começar:

Verifique _cat/health?v para ver se o problema é em todo o cluster.
Use _cat/shards?v para encontrar shards não atribuídos, realocados ou quentes.
Execute _cluster/allocation/explain para shards não atribuídos.
Verifique _cat/nodes para heap, CPU, disco e papéis dos nós.
Revise os logs dos nós para mensagens de alocação, disco, JVM e circuit breaker.
Use estatísticas de nós e de thread pool se o problema for latência ou requisições rejeitadas.

Conclusão Principal

Depurar o Elasticsearch funciona melhor quando você passa de verificações amplas de saúde para o shard, nó ou configuração exata que está causando o problema. Comece com _cat/health, _cat/shards e allocation explain, depois use logs e estatísticas de nós para confirmar a causa raiz antes de alterar configurações.