Risoluzione dei problemi: Verifica e interpretazione dello stato di salute del cluster Elasticsearch

Lo stato di salute del cluster Elasticsearch è uno di quei controlli che sembrano semplici finché non scatta l'allarme. L'API restituisce un colore, ma il colore è solo il punto di partenza. Un cluster verde può comunque essere lento. Un cluster giallo può essere perfettamente utilizzabile per una breve finestra di manutenzione. Un cluster rosso può significare che un piccolo indice di test non è disponibile, oppure che la ricerca rivolta ai clienti sta perdendo dati reali.

Quando controllo lo stato di salute del cluster Elasticsearch, cerco di non passare direttamente dal rosso a comandi di ripristino pericolosi. Voglio prima rispondere a tre domande: gli shard primari sono assegnati, le repliche sono assegnate e il cluster sta attualmente tentando di riprendersi da solo? I comandi seguenti sono quelli che uso per passare da un colore di salute generico a una ragione specifica.

Inizia con l'API di salute

Per una rapida visualizzazione da terminale, _cat/health va bene:

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

Una risposta tipica appare così:

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

I campi che guardo per primi sono status, node.total, node.data, relo, init, unassign e pending_tasks. Uno stato giallo con init o relo maggiore di zero potrebbe semplicemente essere un cluster che si sta riprendendo dopo un riavvio. Uno stato giallo con shard non assegnati e nessun movimento di solito richiede un'indagine.

Per l'automazione, usa l'API JSON invece di analizzare l'output di _cat:

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

Quella risposta include campi come active_primary_shards, active_shards, relocating_shards, initializing_shards, unassigned_shards e delayed_unassigned_shards. Questi nomi sono più facili da usare in script e controlli di monitoraggio.

Cosa significano realmente verde, giallo e rosso

Verde significa che ogni shard primario e ogni shard replica configurato è assegnato. Non significa che le query siano veloci, il disco sia sano o i mapping siano ben progettati. Significa solo che Elasticsearch ha posizionato gli shard che doveva posizionare.

Giallo significa che tutti gli shard primari sono assegnati, ma almeno uno shard replica non è assegnato. I tuoi dati dovrebbero essere ancora ricercabili perché i primari sono disponibili. Il rischio è la ridondanza. Se il nodo che ospita un primario fallisce mentre la sua replica è ancora non assegnata, quell'indice può diventare rosso.

Rosso significa che almeno uno shard primario non è assegnato. Le ricerche sugli indici interessati potrebbero fallire o restituire risultati parziali, e le scritture su quegli shard non possono procedere normalmente. Il rosso merita attenzione immediata, ma l'azione corretta dipende dal motivo per cui il primario non è assegnato.

Un esempio comune per cluster piccoli è un cluster di sviluppo a nodo singolo con una replica configurata. Rimarrà giallo perché Elasticsearch non metterà una replica sullo stesso nodo del suo primario. Non è un mistero e non è un motivo per forzare l'allocazione. Aggiungi un altro nodo dati o imposta le repliche a zero per quell'indice:

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

Non usare questa impostazione con leggerezza in produzione. Rimuove la ridondanza per quell'indice.

Trova gli shard non assegnati esatti

Dopo il colore di salute, elenca gli shard:

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

Cerca UNASSIGNED. La colonna prirep ti dice se lo shard è primario (p) o replica (r). Questa distinzione è più importante del colore stesso. Poche repliche non assegnate di solito significano una tolleranza ai guasti ridotta. Un primario non assegnato significa che almeno una parte di un indice non è disponibile.

Se vedi molti shard non assegnati dopo un riavvio pianificato del nodo, controlla anche l'allocazione ritardata:

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

Elasticsearch potrebbe attendere prima di riallocare le repliche dopo che un nodo se ne va, perché il nodo potrebbe tornare rapidamente. Questo comportamento evita inutili cambiamenti di rete e disco durante i riavvii progressivi.

Chiedi a Elasticsearch perché l'allocazione è fallita

L'API di spiegazione dell'allocazione è il passo successivo migliore. Puoi chiedere per qualsiasi shard non assegnato:

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

Oppure chiedere su uno shard specifico:

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
  }'

Leggi unassigned_info, can_allocate e node_allocation_decisions. La parte utile è solitamente in inglese semplice: soglia del disco superata, allocazione disabilitata, nessun attributo del nodo corrispondente, troppi shard su un nodo, o una replica non può essere posizionata perché esiste un solo nodo.

Se la spiegazione dice allocation_delayed, attendi solo se si prevede che il nodo mancante torni presto. Se la spiegazione dice che nessun nodo soddisfa le regole di allocazione, aspettare non risolverà il problema.

Playbook per cluster giallo

Per la salute gialla, uso questo ordine:

1. Controlla se il cluster ha abbastanza nodi dati per il numero di repliche configurato.
2. Controlla le soglie del disco con _cat/allocation.
3. Controlla se l'allocazione è stata disabilitata durante la manutenzione.
4. Controlla i filtri di routing a livello di indice e le regole di awareness.
5. Decidi se aggiungere capacità, ridurre il numero di repliche o correggere una regola errata.

Il controllo del numero di nodi è semplice. Se un indice ha number_of_replicas: 2, Elasticsearch ha bisogno di tre nodi dati adatti per posizionare un primario più due repliche. "Adatto" è importante. Se l'awareness dell'allocazione richiede zone separate, hai bisogno di nodi in quelle zone, non solo di tre nodi qualsiasi.

Controlla allocazione e disco:

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

Se i nodi sono al di sopra delle soglie del disco, Elasticsearch potrebbe rifiutare nuove allocazioni di shard. Libera spazio, aggiungi nodi, espandi i dischi o elimina vecchi indici dopo aver creato snapshot. Alzare le soglie può far guadagnare tempo in un'emergenza controllata, ma non crea capacità.

Controlla le impostazioni di allocazione:

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

Se cluster.routing.allocation.enable è none, l'allocazione è disabilitata. Questo è comune dopo script di manutenzione che hanno dimenticato di riattivarla. Riattivala con:

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

Controlla anche se il valore è stato impostato come transient; le impostazioni persistenti e transitorie possono entrambe influenzare il comportamento.

Playbook per cluster rosso

Per la salute rossa, rallenta e identifica il raggio d'esplosione. Non iniziare con allocate_empty_primary. Quel comando accetta la perdita di dati per progettazione.

Prima, trova gli shard primari interessati:

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

Poi ispezionane uno con la spiegazione dell'allocazione:

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

Se il primario non è assegnato perché un nodo è giù, il tuo miglior ripristino potrebbe essere ripristinare quel nodo. Controlla il servizio, il disco, i log JVM e il percorso di rete. Se esiste una copia replica su un altro nodo, Elasticsearch dovrebbe normalmente promuoverla. Se non lo fa, l'output della spiegazione e i log di solito ti dicono perché.

Se i dati sono persi o corrotti, ripristina da uno snapshot. Questo è il percorso di ripristino pulito. Se non esiste alcuno snapshot e i dati possono essere ricostruiti da un'altra fonte, potresti decidere di allocare un primario vuoto:

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
        }
      }
    ]
  }'

Usalo solo quando perdere il contenuto dello shard è accettabile. Il nome è letterale: Elasticsearch alloca un primario vuoto e va avanti.

Osserva il ripristino invece di indovinare

Dopo una correzione, osserva il movimento degli shard:

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"

Il ripristino può essere limitato dalla velocità del disco, dalla larghezza di banda di rete, dalla dimensione dello shard e dalle impostazioni di ripristino del cluster. Uno shard grande potrebbe rimanere in INITIALIZING più a lungo del previsto. Questo è diverso dall'essere bloccato. Se i conteggi di byte e file si muovono in _cat/recovery, lascialo lavorare.

Controlla anche le attività del cluster in sospeso quando la salute non cambia:

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

Una lunga coda può indicare un nodo master sovraccarico o decisioni di allocazione ripetute che non possono essere completate.

Un esempio pratico

Supponiamo che _cat/health mostri giallo con due shard non assegnati. _cat/shards mostra che entrambi sono repliche per logs-2026.05.24. La spiegazione dell'allocazione dice che il cluster non può allocare perché ogni nodo dati è al di sopra della soglia del disco bassa. La soluzione non è reindirizzare manualmente gli shard. La soluzione è la capacità: elimina vecchi indici dopo aver creato snapshot, aggiungi storage, aggiungi nodi dati o sposta i dati freddi altrove.

Un altro esempio: un cluster a tre nodi è giallo dopo un riavvio progressivo. _cluster/health mostra delayed_unassigned_shards: 8. Il nodo fermato sta già tornando. In questo caso, aspettare qualche minuto potrebbe essere corretto. Forzare immediatamente l'allocazione può creare lavoro di ripristino extra e rallentare il riavvio.

Un terzo esempio: un cluster di laboratorio a nodo singolo è giallo per sempre. _cat/shards mostra che ogni shard non assegnato è una replica. L'indice ha una replica. Elasticsearch si sta comportando correttamente. Imposta le repliche a zero per il laboratorio o aggiungi un secondo nodo dati.

Mantieni onesto il controllo di salute

La salute del cluster dovrebbe far parte del monitoraggio, ma le regole di avviso necessitano di contesto. Avvisa immediatamente sul rosso. Avvisa sul giallo quando dura oltre una breve finestra di manutenzione, quando le repliche non assegnate aumentano o quando il motivo è la pressione del disco. Tieni traccia delle soglie del disco, del numero di nodi, della pressione JVM e del successo degli snapshot insieme al colore di salute. Il colore ti dice da dove iniziare; le API degli shard e dell'allocazione ti dicono cosa fare dopo.

Quando i controlli di salute non sono d'accordo con i sintomi degli utenti

A volte il cluster è verde e gli utenti si lamentano ancora. Questa non è una contraddizione. La salute del cluster riguarda l'assegnazione degli shard, non la latenza o la correttezza delle query. Se la salute è verde ma le ricerche sono lente, passa alla latenza di ricerca, ai pool di thread, agli shard caldi, alla pressione JVM e alla latenza di storage. Un cluster verde con un nodo dati sovraccarico può comunque sembrare rotto.

Succede anche il contrario. Un cluster può essere giallo per un motivo innocuo, come un ambiente di sviluppo a nodo singolo con repliche configurate. L'abitudine utile è collegare lo stato di salute all'impatto aziendale. Quale indice è interessato? È un primario o una replica? L'applicazione sta leggendo da quell'indice in questo momento? Questo avviene durante la manutenzione pianificata? Queste domande ti impediscono di trattare ogni stato giallo come un disastro.

Per i sistemi rivolti ai clienti, mi piace tenere una piccola tabella di runbook al di fuori di Elasticsearch: pattern dell'indice, servizio proprietario, fonte dei dati, politica degli snapshot, se i dati possono essere riprodotti e chi approva il ripristino distruttivo. Durante un incidente rosso, quella tabella è spesso più utile di un altro dashboard. Se clickstream-* può essere riprodotto da Kafka, la scelta di ripristino è diversa da un indice che contiene documenti generati dagli utenti senza copia a monte.

Abitudini più sicure con i comandi

Usa nomi di indice espliciti quando puoi. I caratteri jolly sono convenienti, ma nascondono il raggio d'esplosione. Prima di eseguire qualsiasi comando che modifichi impostazioni o elimini dati, elenca cosa corrisponde al pattern:

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

Conserva l'output del comando dall'incidente. Incolla i risultati della spiegazione dell'allocazione, gli elenchi degli shard e le risposte di salute nel ticket. Lo stato di Elasticsearch cambia rapidamente durante il ripristino e potresti aver bisogno dell'output precedente per capire perché è stata presa una decisione.

Se la sicurezza è abilitata, esegui questi comandi con un utente che abbia i privilegi minimi utili per la diagnostica e un processo separato e più ristretto per le operazioni distruttive. In un incidente stressante, è troppo facile incollare un comando di scrittura nella stessa shell in cui stavi solo ispezionando la salute.

Cosa controllare dopo che il cluster torna verde

Il verde non è la fine dell'incidente. Controlla se le repliche sono state ricostruite sui nodi che ti aspettavi, se il disco è ancora vicino alle soglie e se qualche indice è stato lasciato con impostazioni temporanee come number_of_replicas: 0, un refresh_interval lungo o l'allocazione disabilitata.

Conferma anche che gli snapshot stiano avendo successo dopo il ripristino. Un cluster che ha appena avuto problemi con gli shard potrebbe aver esposto una lacuna nella conservazione, nelle credenziali del repository o nella pianificazione degli snapshot. Se il ripristino è dipeso dalla fortuna perché non esisteva alcuno snapshot, scrivilo e risolvilo prima del prossimo guasto.

Infine, rivedi gli avvisi. Se gli umani hanno notato il problema prima del monitoraggio, aggiungi o ottimizza gli avvisi per salute rossa, salute gialla di lunga durata, pressione delle soglie del disco, nodi mancanti, snapshot falliti ed elezioni del master ripetute. Un colore di salute del cluster è utile, ma il miglior avviso ti dice perché il colore è cambiato e quale indice è interessato.