Análisis Común de Logs de Elasticsearch para una Solución de Problemas Efectiva

El análisis de logs de Elasticsearch suele ser la forma más rápida de explicar un clúster en rojo, una solicitud de indexación fallida o una queja de búsqueda lenta. Cuando un clúster tiene varios nodos, los logs te indican qué nodo vio el primer fallo, qué componente reaccionó y si el problema es de disco, memoria, descubrimiento, seguridad o recuperación de fragmentos.

Esta guía te muestra cómo leer los logs de Elasticsearch sin perseguir ruido. Aprenderás dónde suelen estar los logs, qué campos importan, qué significan los mensajes de fallo comunes y cuándo cambiar del log principal del servidor a los logs lentos o las APIs de asignación.

Entendiendo la Estructura de los Logs de Elasticsearch

Elasticsearch usa Log4j 2 para el registro. Las instalaciones por paquete suelen escribir los archivos de log en /var/log/elasticsearch/. Los despliegues en contenedores a menudo envían los logs a la salida estándar, donde tu runtime de contenedor o agente de registro los recoge. Dependiendo de tu versión y log4j2.properties, puedes ver logs de texto plano, logs JSON, o ambos.

Tipo de Instalación	Ruta Típica del Log
Paquete RPM/DEB Linux	/var/log/elasticsearch/
Docker	Salida estándar del contenedor
ZIP o tarball	$ES_HOME/logs/

Los archivos comunes incluyen el log principal del servidor, logs de obsolescencia, logs lentos y, a veces, logs de auditoría si la auditoría de seguridad está habilitada.

Las entradas de log JSON suelen incluir campos como estos:

• @timestamp: Cuándo ocurrió el evento.
• level: La gravedad, como INFO, WARN o ERROR.
• component: La clase o subsistema de Elasticsearch que registró el mensaje.
• cluster.uuid: El identificador del clúster.
• node.name: El nodo que generó la línea de log.
• message: El texto legible del evento.

{
  "@timestamp": "2024-01-15T10:30:00.123Z",
  "level": "WARN",
  "component": "o.e.c.r.a.DiskThresholdMonitor",
  "cluster.uuid": "abcde12345",
  "node.name": "es-node-01",
  "message": "high disk watermark [90%] exceeded on [es-node-01]"
}

Priorizando Mensajes por Nivel de Log

Filtra primero por WARN y ERROR, luego amplía la búsqueda alrededor de la misma marca de tiempo. Las líneas anteriores al primer ERROR suelen explicar la causa mejor que el stack trace final.

Nivel	Qué Significa Habitualmente	Primera Acción
ERROR	Una solicitud, fragmento, nodo o subsistema falló.	Investigar inmediatamente.
WARN	Elasticsearch detectó una condición de riesgo.	Revisar antes de que se convierta en una interrupción.
INFO	Actividad normal del ciclo de vida.	Usar para contexto alrededor de advertencias y errores.
DEBUG / TRACE	Detalle de diagnóstico profundo.	Habilitar brevemente solo cuando sea necesario.

Evita dejar los nodos de producción en DEBUG o TRACE. El registro verboso puede consumir disco rápidamente y añadir una sobrecarga evitable.

Solucionando Patrones Comunes de Logs

Los logs de Elasticsearch raramente dicen "la causa raíz es X" en una frase limpia. Busca un patrón: la primera advertencia, el nombre del componente, el índice o fragmento afectado, y el mensaje repetido que sigue.

Fallos en las Comprobaciones de Bootstrap

Elasticsearch realiza comprobaciones de bootstrap en configuraciones de red similares a las de producción. Estas comprobaciones detectan configuraciones de host inseguras, como límites bajos de descriptores de archivo, límites bajos de memoria virtual o problemas de bloqueo de memoria. Si una comprobación requerida falla, el nodo se niega a iniciar.

Busca bootstrap checks failed:

[2024-01-15T10:00:00,123][ERROR][o.e.b.BootstrapCheck$Bootstrap] [es-node-01] bootstrap checks failed
[2024-01-15T10:00:00,124][ERROR][o.e.b.BootstrapCheck$Bootstrap] [es-node-01] max file descriptors [4096] for elasticsearch process is too low, increase to at least [65536]

Arregla la configuración del host, reinicia el nodo y confirma que el log de inicio alcanza el punto donde el nodo se une al clúster.

Fallos de Enlace de Red y Descubrimiento

Si el nodo se inicia pero no se une al clúster, busca BindException, master not discovered, discovery y cluster.initial_master_nodes. Un BindException generalmente apunta a un conflicto de dirección o puerto. Los mensajes de descubrimiento a menudo apuntan a hosts seed incorrectos, puerto de transporte 9300 bloqueado, nombres de clúster no coincidentes o configuraciones de seguridad que impiden que los nodos confíen entre sí.

Excepciones del Circuit Breaker

Los circuit breakers detienen solicitudes que usarían demasiada memoria. La solicitud fallida devuelve un error, pero el nodo debería permanecer activo.

Busca CircuitBreakingException o Data too large:

[2024-01-15T11:45:20,500][WARN][o.e.c.c.CircuitBreakerService] [es-node-02]
CircuitBreakingException: [parent] Data too large, data for [<transport_request>] would be [123456789b], which is larger than the limit of [500mb]

Las causas comunes incluyen agregaciones grandes, solicitudes que devuelven demasiados campos, indexación masiva pesada o fielddata cargada para campos de texto. Identifica el patrón de la solicitud, luego reduce el tamaño de la solicitud, corrige los mapeos o añade capacidad.

Advertencias de Garbage Collection

El log principal de Elasticsearch puede reportar pausas largas de garbage collection de la JVM. Busca gc, JvmGcMonitorService y overhead. Algunas advertencias durante un pico de carga pueden ser normales. Advertencias repetidas junto con una latencia de búsqueda creciente generalmente significan que el heap está bajo presión.

Recuperación de Fragmentos y Corrupción

Cuando un fragmento no se puede asignar o un nodo detecta una copia local de fragmento defectuosa, Elasticsearch registra el índice y el número del fragmento.

Busca shard failed, failed shard, failed to recover o el nombre del índice afectado:

[2024-01-15T12:05:10,999][ERROR][o.e.i.e.Engine] [es-node-03] [my_index][2] fatal error in engine loop
java.io.IOException: Corrupt index files, checksum mismatch

Si el mensaje menciona corrupción, no borres archivos manualmente. Conserva los logs, verifica si existe una réplica buena y utiliza las herramientas de recuperación y APIs de Elasticsearch en lugar de editar la ruta de datos directamente.

Watermarks de Disco

Elasticsearch cambia el comportamiento de asignación de fragmentos cuando los nodos cruzan los watermarks de disco. Busca DiskThresholdMonitor, low disk watermark, high disk watermark o flood-stage disk watermark. Los valores predeterminados pueden variar según la versión y la configuración, así que confirma la configuración de tu clúster antes de actuar:

GET /_cluster/settings?include_defaults=true&filter_path=**.disk.watermark*

Si un índice se vuelve de solo lectura después de un evento de flood-stage, primero libera espacio en disco. Luego, elimina el bloque solo después de que el nodo esté de forma segura por debajo del watermark:

PUT /my-index/_settings
{
  "index.blocks.read_only_allow_delete": null
}

Usando Logs Lentos para Problemas de Rendimiento

Para búsquedas lentas u operaciones de indexación, el log principal del servidor suele ser demasiado amplio. Los logs lentos rastrean operaciones que superan los umbrales configurados. Configúralos por índice con la API de configuración de índices.

PUT /my_index/_settings
{
  "index.search.slowlog.threshold.query.warn": "1s",
  "index.search.slowlog.threshold.query.info": "500ms",
  "index.indexing.slowlog.threshold.index.warn": "1s"
}

Los logs lentos muestran el índice, fragmento, tiempo transcurrido y origen de la solicitud cuando está configurado para incluirlo. Úsalos para detectar consultas costosas repetidas, rangos de fechas amplios, búsquedas con muchos comodines y agregaciones en campos que no están mapeados para una agregación eficiente.

Un Flujo de Trabajo de Revisión Práctico

Comienza con el síntoma visible para el usuario y trabaja hacia atrás:

1. Verifica la salud del clúster y el índice afectado.
2. Busca logs de WARN y ERROR alrededor del momento del incidente.
3. Compara logs entre nodos usando node.name y cluster.uuid.
4. Sigue la primera advertencia repetida, no solo la excepción final.
5. Usa una API específica a continuación: allocation explain para fragmentos no asignados, logs lentos para solicitudes lentas y estadísticas de nodo para presión de recursos.

Por ejemplo, si Kibana muestra un índice en rojo, primero encuentra el fragmento no asignado, luego busca en los logs ese índice y número de fragmento. Si los logs mencionan watermarks de disco, soluciona la presión del disco antes de reenrutar cualquier cosa. Si mencionan un nodo faltante, recupera ese nodo o restaura desde una instantánea antes de considerar comandos de asignación arriesgados.

Conclusión

Comienza cada incidente de Elasticsearch encontrando la primera advertencia o error relevante, no el stack trace final más ruidoso. Usa los logs principales para fallos de nodo, descubrimiento, disco, memoria y fragmentos. Usa logs lentos cuando el clúster esté saludable pero búsquedas específicas o cargas de trabajo de indexación sean lentas.