Herramientas y Técnicas Esenciales para Depurar Problemas de Clúster Elasticsearch

Los problemas de clúster Elasticsearch suelen manifestarse como un estado de salud red o yellow, búsquedas lentas, escrituras rechazadas o nodos que se caen del clúster. La forma más rápida de depurarlos es comenzar con la salud del clúster, luego reducir el problema a shards, nodos, reglas de asignación, logs o presión de recursos.

Esta guía recorre las herramientas integradas que usarás con más frecuencia: APIs _cat, _cluster/allocation/explain, estadísticas de nodos, tareas pendientes y logs de Elasticsearch.

Comprendiendo la Salud del Clúster Elasticsearch

La salud del clúster te da la primera señal:

• green: Todos los shards primarios y réplica están asignados.
• yellow: Todos los shards primarios están asignados, pero uno o más shards réplica no lo están.
• red: Uno o más shards primarios no están asignados, por lo que algunos datos no están disponibles.

Un clúster yellow aún puede servir lecturas y escrituras para los shards primarios disponibles, pero tiene menos redundancia. Un clúster red necesita investigación inmediata porque los shards primarios afectados no están disponibles.

Comienza con las APIs _cat

Las APIs _cat están diseñadas para verificaciones rápidas y legibles 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"

Usa _cat/health para confirmar el estado general. Usa _cat/shards para encontrar shards UNASSIGNED, INITIALIZING o que se reubican repetidamente. Usa _cat/nodes para detectar presión de heap, CPU o disco en un nodo específico.

Para un clúster red o yellow, este comando te da una vista enfocada:

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

Explicar la Asignación de Shards

Cuando un shard no está asignado, _cluster/allocation/explain te dice por qué Elasticsearch no puede colocarlo.

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

También puedes pedirle a Elasticsearch que explique el primer shard no asignado que encuentre:

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

Lee los campos can_allocate, allocate_explanation y node_allocation_decisions. Las causas comunes incluyen watermarks de disco, filtros de asignación, nodos faltantes, configuraciones de índice incompatibles o muy pocos nodos de datos para el número de réplicas solicitado.

Verificar Estadísticas de Nodos y Clúster

Cuando la salud es verde pero las búsquedas o escrituras son lentas, verifica la presión de recursos.

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

Busca uso elevado de heap JVM, presión de disco, tareas de búsqueda o escritura rechazadas y nodos con carga mucho mayor que sus pares. Un solo nodo sobrecargado puede ralentizar todo el clúster si posee shards calientes.

Para rechazos de thread pool, usa:

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

Las tareas rechazadas generalmente significan que el nodo no pudo mantener el ritmo de la tasa de solicitudes. Corrige la causa antes de aumentar las colas: reduce el costo de las consultas, distribuye los shards, escala los nodos o ralentiza la indexación por lotes.

Revisar Tareas Pendientes y Recuperación

Si los cambios en el estado del clúster parecen atascados, verifica las tareas pendientes:

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

Una cola larga puede indicar presión en el nodo maestro, actualizaciones frecuentes de mapeo, cambios constantes de shards o nodos inestables.

Para el movimiento y recuperación de shards, usa:

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

Esto te ayuda a distinguir un clúster que se está recuperando activamente de uno que está bloqueado por reglas de asignación o datos faltantes.

Leer los Logs de Elasticsearch

Los logs de Elasticsearch a menudo explican lo que las APIs solo insinúan. Revisa los logs en el nodo afectado, no solo en un nodo aleatorio del clúster.

Busca mensajes como:

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

Por ejemplo, un flood-stage disk watermark puede bloquear escrituras estableciendo los índices afectados como solo lectura hasta que se resuelva la presión de disco. Después de liberar disco o agregar capacidad, elimina el bloqueo de escritura solo después de entender por qué se llenó el disco:

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

Un Flujo Práctico de Depuración

Usa este orden cuando no estés seguro por dónde empezar:

1. Verifica _cat/health?v para ver si el problema es de todo el clúster.
2. Usa _cat/shards?v para encontrar shards no asignados, en reubicación o calientes.
3. Ejecuta _cluster/allocation/explain para shards no asignados.
4. Verifica _cat/nodes para heap, CPU, disco y roles de nodo.
5. Revisa los logs del nodo para mensajes de asignación, disco, JVM y circuit breaker.
6. Usa estadísticas de nodos y estadísticas de thread pool si el problema es latencia o solicitudes rechazadas.

Conclusión Clave

Depurar Elasticsearch funciona mejor cuando pasas de verificaciones amplias de salud al shard, nodo o configuración exacta que causa el problema. Comienza con _cat/health, _cat/shards y allocation explain, luego usa logs y estadísticas de nodos para confirmar la causa raíz antes de cambiar configuraciones.