Strumenti e Tecniche Essenziali per il Debug dei Problemi del Cluster Elasticsearch

I problemi del cluster Elasticsearch si manifestano solitamente con uno stato di salute red o yellow, ricerche lente, scritture rifiutate o nodi che abbandonano il cluster. Il modo più rapido per eseguire il debug è iniziare con la salute del cluster, poi restringere il problema agli shard, ai nodi, alle regole di allocazione, ai log o alla pressione delle risorse.

Questa guida illustra gli strumenti integrati che utilizzerai più spesso: le API _cat, _cluster/allocation/explain, le statistiche dei nodi, le attività in sospeso e i log di Elasticsearch.

Comprendere la Salute del Cluster Elasticsearch

La salute del cluster fornisce il primo segnale:

• green: Tutti gli shard primari e replica sono allocati.
• yellow: Tutti gli shard primari sono allocati, ma uno o più shard replica non lo sono.
• red: Uno o più shard primari non sono assegnati, quindi alcuni dati non sono disponibili.

Un cluster yellow può ancora servire letture e scritture per gli shard primari disponibili, ma ha meno ridondanza. Un cluster red richiede un'indagine immediata perché gli shard primari interessati non sono disponibili.

Iniziare con le API _cat

Le API _cat sono progettate per controlli rapidi e leggibili dall'uomo.

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"

Usa _cat/health per confermare lo stato generale. Usa _cat/shards per trovare shard UNASSIGNED, INITIALIZING o in ripetuta rilocazione. Usa _cat/nodes per individuare pressione su heap, CPU o disco su un nodo specifico.

Per un cluster red o yellow, questo comando fornisce una vista mirata:

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

Spiegare l'Allocazione degli Shard

Quando uno shard non è assegnato, _cluster/allocation/explain ti dice perché Elasticsearch non può posizionarlo.

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

Puoi anche chiedere a Elasticsearch di spiegare il primo shard non assegnato che trova:

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

Leggi i campi can_allocate, allocate_explanation e node_allocation_decisions. Le cause comuni includono watermarks del disco, filtri di allocazione, nodi mancanti, impostazioni dell'indice incompatibili o un numero insufficiente di nodi dati per il numero di repliche richiesto.

Controllare le Statistiche dei Nodi e del Cluster

Quando la salute è verde ma le ricerche o le scritture sono lente, controlla la pressione delle risorse.

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

Cerca un uso elevato dell'heap JVM, pressione del disco, attività di ricerca o scrittura rifiutate e nodi con un carico molto superiore rispetto ai loro pari. Un singolo nodo sovraccarico può rallentare l'intero cluster se possiede shard caldi.

Per i rifiuti del pool di thread, usa:

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

Le attività rifiutate di solito significano che il nodo non riusciva a tenere il passo con il tasso di richieste. Risolvi la causa prima di aumentare le code: riduci il costo delle query, distribuisci gli shard, scala i nodi o rallenta l'indicizzazione bulk.

Esaminare le Attività in Sospeso e il Recupero

Se le modifiche allo stato del cluster sembrano bloccate, controlla le attività in sospeso:

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

Una lunga coda può indicare pressione sul nodo master, aggiornamenti frequenti del mapping, cambiamenti degli shard o nodi instabili.

Per il movimento e il recupero degli shard, usa:

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

Questo aiuta a distinguere un cluster che si sta attivamente riprendendo da uno bloccato da regole di allocazione o dati mancanti.

Leggere i Log di Elasticsearch

I log di Elasticsearch spesso spiegano ciò che le API suggeriscono solo. Controlla i log sul nodo interessato, non solo su un nodo casuale del cluster.

Cerca messaggi come:

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

Ad esempio, un watermark del disco in fase di flood può bloccare le scritture impostando gli indici interessati in sola lettura fino a quando la pressione del disco non viene risolta. Dopo aver liberato spazio su disco o aggiunto capacità, rimuovi il blocco di scrittura solo dopo aver capito perché il disco si è riempito:

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

Un Flusso di Debug Pratico

Usa questo ordine quando non sai da dove iniziare:

1. Controlla _cat/health?v per vedere se il problema è a livello di cluster.
2. Usa _cat/shards?v per trovare shard non assegnati, in rilocazione o caldi.
3. Esegui _cluster/allocation/explain per gli shard non assegnati.
4. Controlla _cat/nodes per heap, CPU, disco e ruoli dei nodi.
5. Esamina i log dei nodi per messaggi di allocazione, disco, JVM e circuit breaker.
6. Usa le statistiche dei nodi e del pool di thread se il problema è la latenza o le richieste rifiutate.

Punto Chiave

Il debug di Elasticsearch funziona meglio quando si passa da controlli di salute ampi allo shard, nodo o impostazione specifica che causa il problema. Inizia con _cat/health, _cat/shards e la spiegazione dell'allocazione, poi usa i log e le statistiche dei nodi per confermare la causa principale prima di modificare le impostazioni.