Introduction

Dans cet article vous trouverez quelques commandes utiles pour avoir des informations rapidement sur votre cluster elasticsearch. Vous serez par exemple sur quel nœud se trouve votre index ou les shards de votre index, ou encore la taille de vos shards ou le nombre de segments pour chacun de vos shards. Il sera nécessaire de disposer des droits pour effectuer ces appels API.

Rappels

Avant de voir ces appels API, quelques rappels :

Un cluster elasticsearch est composé de nœuds où chaque nœud est une instance d’elasticsearch. Chaque nœud a un ou plusieurs rôle(s) dans le cluster (master, data, ingestion, …).
C’est dans les nœuds avec le rôle data que sont stockées les données. Elles sont stockées dans ce que l’on appelle un index.
Un index est composé de partitions (ou shards) distribuées sur le cluster. Ainsi les données d’un index peuvent se retrouver sur différents nœuds.
Un shard est une instance de Apache Lucene™.
Il existe 2 sortes de shards, les “primary shards” et les “replica shards”. Les primary shards sont la sauvegarde primaire des données. Les replica shards sont des copies des primary shards pour la redondance.
Les replicas d’un shard primaire doivent être sauvegardés sur un nœud différent de celui où se trouve le shard primaire. Si cela n’est pas possible (pas assez de nœud ou d’espace) le replica ne se crée pas, il aura le statut unassigned.
De cette manière, si un nœud tombe, les données sont toujours accessibles.
Au sein d’un shard, les données sont écrites sur des segments. Les segments sont immuables. Cela veut dire que lorsqu’un delete ou un update est opéré sur un document, un autre segment est créé avec le document dans le cas de l’update et le document original est étiqueté comme “deleted” sur l’autre segment, dans le cas de l’update et d’un delete. Cela signifie que l’on peut avoir plusieurs versions d’un document dans le cluster et donc de l’espace disque est pris. Mais elasticsearch a des mécanismes pour réécrire les segments sans considérer les documents étiquetés deleted et ainsi libérer de l’espace disque.
La donnée stockée s’appelle un document et il s’agit d’un JSON.

Les requêtes GET

Vous pouvez exécuter ces appels de la manière dont vous le souhaitez, avec le navigateur, avec des curl, postman, kibana, etc.

Information générale sur le cluster :

1 – Cluster : http://localhost:9200/_cluster/health/

Permet d’avoir des informations générales sur le cluster et sa santé (son statut). Le nombre de nœuds, le nombre de nœuds data, le nombre de shards actifs, “unassigned”, …

2 – Cluster : http://localhost:9200/_cluster/settings?include_defaults=true&flat_settings=true

Permet de connaître les paramètres de configuration du cluster, les paramètres dit “transient”, dit “persistent” et les paramètres par défaut.

Parmi tous les paramètres il y a par exemple « cluster.routing.allocation.disk.watermark.flood_stage » qui indique à partir de quel pourcentage d’espace disque occupé, il arrête les opérations en écriture sur un index et le passe en mode read-only-allow-delete, c’est-à-dire qu’on peut uniquement lire l’index ou supprimer des documents de l’index pour libérer de l’espace disque.

3 – Cluster : http://localhost:9200/_cluster/state

Permet d’avoir des informations sur l’état du cluster.

4 – Noeud : http://localhost:9200/_cat/allocation?v

Indique la répartition des shards sur les nœuds data, l’espace qu’ils prennent sur les nœuds ainsi que l’espace disponible sur les nœuds. Cet appel donne également le nombre de shards “unassigned”.

5 – Index : http://localhost:9200/_cat/indices?v

Liste les index avec leur statut, leur état de santé, leur id, le nombre de partitions, de replicas, de documents, de documents “deleted” et la place qu’ils occupent sur le disque.

6 – Shard : http://localhost:9200/_cat/shards?v

Liste les shards primaires et les répliques avec leur statut, le nombre de documents qu’il possède, à quel index ils appartiennent, l’espace disque et sur quel nœud ils sont stockés.

7 – Shard : http://localhost:9200/_cat/shards?v&h=index,shard,prirep,state,unassigned.reason

Cette requête permet de donner la raison pour laquelle un shard est unassigned.

8 – Segment : http://localhost:9200/_cat/segments?v&h=index,shard,prirep,segment,docs.count,docs.deleted,size

Liste des segments par shard et index et pour chaque segment le nombre de documents, le nombre de documents étiquetés comme « deleted » et sa taille sur le disque.

9 – Merge de segments + Noeud : http://localhost:9200/_nodes/stats/indices/merge

Pour avoir des informations sur les merges de segments, pour chaque nœud du cluster. De plus, l’appel vous donne des informations sur les rôles que possède chaque nœud.

10 – Merge de segments : http://localhost:9200/_cat/thread_pool/force_merge?v&h=node_name,name,queue,active,rejected

Information sur les force_merge en cours sur les différents nœuds. Nous verrons à la fin de l’article 2 requêtes pour opérer des force_merge sur un index.

Information générale sur un index donné :

11 – Index : http://localhost:9200/nom_index/_settings

Pour voir les paramètres d’un index donné.

12 – Index : http://localhost:9200/nom_index /_mapping

Pour voir le mapping d’un index donné.

13 – Index : http://localhost:9200/_cat/segments/nom_index?v&h=shard,prirep,segment,docs.count,docs.deleted

Comme pour la requête précédente sur les segments, elle permet de récupérer des informations sur les segments mais pour un index spécifique.

14 – Index : http://localhost:9200/_cat/indices/nom_index ?v&h=index,merges.current,merges.current_docs,merges.total,merges.total_docs,docs.deleted&format=json

Comme indiqué dans les paramètres de la requête, elle permet de récupérer certaines valeurs sur un index donné concernant les merges des segments. L’appel permet de connaître le nombre de documents étiquetés “deleted” et qui prennent de l’espace sur le cluster.

Requêtes POST

Pour libérer de la place sur votre cluster vous pouvez supprimer des index, mais vous pouvez aussi vous intéresser au segments qui stock des documents obsolètes. A l’aide de l’appel API n°14 vous pouvez savoir combien de documents occupent de la place inutilement sur un index et estimer l’espace disque que vous pourriez récupérer. Avec l’appel API n°13 vous saurez combien de segments vous possédez pour votre index et pour chacun le nombre de documents stockés et le nombre de documents à supprimer.

⚠️ Il faut éviter ces appels sur des index où il y a des écritures en cours.

curl -X POST 'http://localhost:9200/nom_index/_forcemerge?only_expunge_deletes=true'

Cet appel permet de réduire le nombre de documents à supprimer en forçant la réécriture de segments en enlevant les documents dit “deleted”.

curl -X POST 'http://localhost:9200/nom_index/_forcemerge?max_num_segments=1'

Cet appel permet de forcer le nombre de segment par shard d’un index à 1 segment.

Lorsqu’il y a des problèmes d’espace dans votre cluster, vos index peuvent se mettre dans un état de lecture ou suppression uniquement (read_only_allow_delete=true). Vous pouvez vérifier cet état avec l’appel n°11 vu précédemment.

curl -X PUT "http://localhost:9200/nom_index/_settings?pretty" -H 'Content-Type: application/json' -d '{"index.blocks.read_only_allow_delete": null}'

Cet appel permet de rendre de nouveau un index un écriture.

Quelques points de vigilance

Avant de conclure, il est essentiel de rappeler que la capacité disque n’est qu’un indicateur parmi d’autres. La stabilité d’un cluster Elasticsearch dépend fortement de la manière dont les shards et les segments sont dimensionnés et distribués. Une configuration inadaptée peut rapidement dégrader les performances :

Sur‑allocation de shards : surcharge du cluster, augmentation du coût de gestion des métadonnées, pression excessive sur le master, et overhead CPU/mémoire inutile.
Sous‑allocation de shards : impossibilité de répartir la charge lors d’un scale‑out, saturation des nœuds existants, et limitation de la parallélisation des opérations.
Segments trop nombreux : augmentation de la latence due aux merges, pression sur l’I/O, et impact direct sur les temps de recherche et d’indexation.

Pour maintenir un cluster performant, certaines bonnes pratiques opérationnelles doivent être systématiquement appliquées :

Éviter les shards trop petits (< 50 Mo) qui multiplient les structures internes et augmentent le coût de gestion, et les shards trop volumineux (> 50 Go) difficiles à déplacer, répliquer ou restaurer.
Surveiller les watermarks disque (low, high, flood‑stage) afin d’anticiper les réallocations forcées et les blocages d’écriture.
Maintenir un équilibre cohérent des replicas pour garantir la résilience tout en évitant les déséquilibres de charge entre nœuds.
Planifier des opérations de maintenance lorsque cela est pertinent, telles que force merge, shrink, reindex ou allocation filtering, afin de réduire la fragmentation et stabiliser le cluster.

Ces bonnes pratiques, combinées aux API présentées plus haut, permettent d’anticiper les risques structurels et d’assurer un fonctionnement optimal du cluster sur le long terme.

Conclusion

Dans cet article nous avons vu quelques appels API pour avoir des informations rapidement sur l’état de votre cluster elasticsearch et plus particulièrement sur le stockage. Exécuter ces appels à votre tour pour vous familiariser avec et anticiper les besoins en ressource disque de votre cluster.

Documentation :

D’autres articles sur le blog :