Analyse courante des logs Elasticsearch pour un dépannage efficace

L'analyse des logs Elasticsearch est généralement le moyen le plus rapide d'expliquer un cluster rouge, une demande d'indexation échouée ou une plainte de recherche lente. Lorsqu'un cluster comporte plusieurs nœuds, les logs vous indiquent quel nœud a vu la première défaillance, quel composant a réagi et si le problème est lié au disque, à la mémoire, à la découverte, à la sécurité ou à la récupération de shards.

Ce guide vous montre comment lire les logs Elasticsearch sans vous perdre dans le bruit. Vous apprendrez où les logs se trouvent généralement, quels champs sont importants, ce que signifient les messages d'erreur courants et quand passer du log serveur principal aux logs lents ou aux API d'allocation.

Comprendre la structure des logs Elasticsearch

Elasticsearch utilise Log4j 2 pour la journalisation. Les installations par paquet écrivent généralement les fichiers de log sous /var/log/elasticsearch/. Les déploiements conteneurisés envoient souvent les logs vers la sortie standard, où votre runtime de conteneur ou votre agent de journalisation les collecte. Selon votre version et votre log4j2.properties, vous pouvez voir des logs en texte brut, des logs JSON, ou les deux.

Type d'installation	Chemin de log typique
Paquet RPM/DEB Linux	/var/log/elasticsearch/
Docker	Sortie standard du conteneur
ZIP ou tarball	$ES_HOME/logs/

Les fichiers courants incluent le log serveur principal, les logs de dépréciation, les logs lents, et parfois les logs d'audit si l'audit de sécurité est activé.

Les entrées de log JSON incluent généralement des champs comme ceux-ci :

• @timestamp : Quand l'événement s'est produit.
• level : La sévérité, comme INFO, WARN, ou ERROR.
• component : La classe ou le sous-système Elasticsearch qui a enregistré le message.
• cluster.uuid : L'identifiant du cluster.
• node.name : Le nœud qui a généré la ligne de log.
• message : Le texte lisible de l'événement.

{
  "@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]"
}

Prioriser les messages par niveau de log

Filtrez d'abord pour WARN et ERROR, puis élargissez la recherche autour du même horodatage. Les lignes précédant la première ERROR expliquent souvent la cause mieux que la trace de pile finale.

Niveau	Ce que cela signifie généralement	Première action
ERROR	Une requête, un shard, un nœud ou un sous-système a échoué.	Enquêter immédiatement.
WARN	Elasticsearch a détecté une condition risquée.	Vérifier avant que cela ne devienne une panne.
INFO	Activité normale du cycle de vie.	Utiliser pour le contexte autour des avertissements et des erreurs.
DEBUG / TRACE	Détail de diagnostic approfondi.	Activer brièvement uniquement lorsque vous en avez besoin.

Évitez de laisser les nœuds de production en DEBUG ou TRACE. Une journalisation verbeuse peut consommer rapidement de l'espace disque et ajouter une surcharge évitable.

Dépannage des modèles de log courants

Les logs Elasticsearch disent rarement "la cause première est X" en une seule phrase claire. Cherchez un modèle : le premier avertissement, le nom du composant, l'index ou le shard affecté, et le message répété qui suit.

Échecs des vérifications de bootstrap

Elasticsearch effectue des vérifications de bootstrap dans les configurations réseau de type production. Ces vérifications détectent les paramètres hôte dangereux tels que des limites de descripteurs de fichiers basses, des limites de mémoire virtuelle basses ou des problèmes de verrouillage mémoire. Si une vérification requise échoue, le nœud refuse de démarrer.

Recherchez 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]

Corrigez le paramètre hôte, redémarrez le nœud et confirmez que le log de démarrage atteint le point où le nœud rejoint le cluster.

Échecs de liaison réseau et de découverte

Si le nœud démarre mais ne rejoint pas le cluster, recherchez BindException, master not discovered, discovery, et cluster.initial_master_nodes. Un BindException indique généralement un conflit d'adresse ou de port. Les messages de découverte pointent souvent vers de mauvais hôtes seed, un port de transport 9300 bloqué, des noms de cluster incompatibles ou des paramètres de sécurité qui empêchent les nœuds de se faire confiance.

Exceptions du coupe-circuit

Les coupe-circuits arrêtent les requêtes qui utiliseraient trop de mémoire. La requête échouée renvoie une erreur, mais le nœud devrait rester actif.

Recherchez CircuitBreakingException ou 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]

Les causes courantes incluent les agrégations volumineuses, les requêtes qui renvoient trop de champs, l'indexation par lots lourde ou les données de champ chargées pour les champs de texte. Identifiez le modèle de requête, puis réduisez la taille de la requête, corrigez les mappings ou ajoutez de la capacité.

Avertissements de garbage collection

Le log principal d'Elasticsearch peut signaler de longues pauses de garbage collection JVM. Recherchez gc, JvmGcMonitorService, et overhead. Quelques avertissements lors d'un pic de charge peuvent être normaux. Des avertissements répétés associés à une latence de recherche croissante signifient généralement que le tas est sous pression.

Récupération de shard et corruption

Lorsqu'un shard ne parvient pas à s'allouer ou qu'un nœud détecte une mauvaise copie locale du shard, Elasticsearch enregistre l'index et le numéro du shard.

Recherchez shard failed, failed shard, failed to recover, ou le nom de l'index affecté :

[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 le message mentionne une corruption, ne supprimez pas les fichiers manuellement. Conservez les logs, vérifiez si une bonne réplique existe et utilisez les outils et API de récupération Elasticsearch plutôt que de modifier directement le chemin des données.

Seuils de disque

Elasticsearch modifie le comportement d'allocation des shards lorsque les nœuds franchissent les seuils de disque. Recherchez DiskThresholdMonitor, low disk watermark, high disk watermark, ou flood-stage disk watermark. Les valeurs par défaut peuvent varier selon la version et la configuration, alors confirmez vos paramètres de cluster avant d'agir :

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

Si un index devient en lecture seule après un événement de seuil critique, libérez d'abord de l'espace disque. Ensuite, supprimez le blocage uniquement après que le nœud est en toute sécurité en dessous du seuil :

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

Utiliser les logs lents pour les problèmes de performance

Pour les recherches lentes ou les opérations d'indexation, le log serveur principal est souvent trop large. Les logs lents suivent les opérations qui dépassent les seuils configurés. Configurez-les par index avec l'API des paramètres d'index.

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

Les logs lents montrent l'index, le shard, le temps écoulé et la source de la requête lorsqu'elle est configurée pour l'inclure. Utilisez-les pour repérer les requêtes coûteuses répétées, les plages de dates larges, les recherches avec beaucoup de jokers et les agrégations sur des champs qui ne sont pas mappés pour une agrégation efficace.

Un flux de travail de révision pratique

Commencez par le symptôme visible par l'utilisateur et remontez :

1. Vérifiez la santé du cluster et l'index affecté.
2. Recherchez les logs WARN et ERROR autour de l'heure de l'incident.
3. Comparez les logs entre les nœuds en utilisant node.name et cluster.uuid.
4. Suivez le premier avertissement répété, pas seulement l'exception finale.
5. Utilisez ensuite une API ciblée : explication d'allocation pour les shards non attribués, logs lents pour les requêtes lentes et statistiques de nœud pour la pression sur les ressources.

Par exemple, si Kibana montre un index rouge, trouvez d'abord le shard non attribué, puis recherchez dans les logs cet index et ce numéro de shard. Si les logs mentionnent des seuils de disque, corrigez la pression sur le disque avant de réacheminer quoi que ce soit. S'ils mentionnent un nœud manquant, récupérez ce nœud ou restaurez à partir d'un snapshot avant d'envisager des commandes d'allocation risquées.

À retenir

Commencez chaque incident Elasticsearch en trouvant le premier avertissement ou erreur pertinent, pas la trace de pile finale la plus bruyante. Utilisez les logs principaux pour les défaillances de nœud, de découverte, de disque, de mémoire et de shard. Utilisez les logs lents lorsque le cluster est sain mais que des recherches spécifiques ou des charges de travail d'indexation sont lentes.