# Introduction à la pile ELK
Atelier de 14h dispensé pour le Master Information et Communication (Data Analytics et Stratégie de l'Information) à l'Université de Toulon.
Les objectifs de cet atelier sont :
- d'appréhender la pile ELK ;
- d'appréhender Docker et le principe de conteneurisation ;
- de maîtriser les bases de l'outil Kibana ;
- d'approfondir le concept d'intelligence des données.
Au sommaire :
[TOC]
### La pile ELK
L'acronyme « ELK » désigne une suite comprenant 3 projets open source : **Elasticsearch**, **Logstash** et **Kibana**. Au travers de ces trois outils, elle permet de rechercher, analyser et visualiser, en temps réel, des données issues de n’importe quelle source et sous n’importe quel format.
<div style="text-align:center">
<img src="https://i.imgur.com/oVyA4UE.png" />
</div>
- **Logstash** permet d’agréger, traiter et enrichir des données de sources diverses avant de les transmettre à une instance ElasticSearch ou tout autre type de stockage. Il offre une large gamme de plugins pour différents types d'entrées, de filtres, et de sorties, ce qui permet une personnalisation poussée du traitement des données. **Cette partie peut être substituée par un traitement directement dans un programme Python**.
- **ElasticSearch** est un moteur de recherche et d’analytique utilisé principalement pour la recherche plein texte et l’analyse de journaux et de métriques. Le fonctionnement d’ElasticSearch s’apparente à une base de données non relationnelle (NoSQL). Il utilise un modèle de données basé sur des documents JSON, ce qui le rend adaptable à divers types de données et est conçu pour être scalable, distribué et rapide pour les requêtes.
- **Kibana** est un outil de visualisation et d’exploration des données. Cet outil permet de créer une myriade de visualisations (tableaux, histogrammes, cartes choroplèthes, etc.) basées sur des données en temps réel en interrogeant l’instance ElasticSearch. Kibana offre également des fonctionnalités de dashboard interactif pour une exploration approfondie des données.
Les outils de la pile ELK utilisent [un vocabulaire spécifique](https://www.elastic.co/guide/en/elasticsearch/reference/current/_mapping_concepts_across_sql_and_elasticsearch.html) dont quelques mots sont définis ci-après :
- un **document** (équivalent en SQL : `row`) désigne une référence composée par une multitude de champs (`fields`) et qui compose un index ;
- un **index** (équivalent en SQL : `table`) qui désigne donc une collection de documents ;
- un **mapping** (équivalent en SQL : `schema`) désigne la description typologique d’un index. On y retrouve la liste des champs qui composent les documents, leur type, et peut aussi inclure des paramètres avancés pour la gestion des données.
La pile ELK est, à la base, très populaire dans le milieu de l'infogérance (analyse de logs) mais peut voir son usage être détourné pour, par exemple, servir de support pour de l'intelligence des données ou encore de l'informatique décisionnelle.
Cet atelier de narration des données portera principalement sur ces derniers aspects et traitera principalement de les outils Elasticsearch et Kibana. Au cours des différents exercices, vous serez en mesure d'apprécier la valeur ajoutée que ces outils peuvent apporter.
### Docker
<img style="float: right;" src="https://i.imgur.com/LTRnbdB.png" />
Docker est une plateforme de conteneurs très populaire qui permet de concevoir, tester et déployer des applications rapidement. Les conteneurs, souvent comparés à des machines virtuelles, sont en fait plus légers et plus efficaces. Un conteneur est une « enveloppe virtuelle » qui contient l'application et tout ce dont elle a besoin pour fonctionner (fichiers, librairies, environnement d’exécution, etc.), isolant ainsi l'application de l'environnement hôte. Cette isolation facilite la portabilité des applications car elles peuvent fonctionner de manière cohérente sur différents systèmes d'exploitation et infrastructures. Contrairement aux machines virtuelles qui nécessitent leur propre système d'exploitation, les conteneurs Docker partagent le même noyau de système d'exploitation que l'hôte tout en restant isolés les uns des autres, ce qui les rend plus légers et plus rapides à démarrer.
## Préparation
Pour installer ElasticSearch et Kibana, vous pouvez choisir d'utiliser [une méthode utilisant les conteneurs](#Installation-via-Docker) ou [une méthode « nature »](#Installation-«-nature-»). Il est préférable d'utiliser la méthode des conteneurs sauf si vous rencontrez des problèmes avec Docker.
### Installation via Docker
#### Installation de Git
##### Sous Windows
Rendez-vous sur [Git](https://gitforwindows.org/), téléchargez l'éxécutable puis suivez les instructions
##### Sous Mac OS
Ouvrez le terminal, puis, installez [Homebrew](https://brew.sh/) à l'aide de la commande ci-après :
```bat=
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
```
Homebrew est un gestionnaire de paquets, il permet d'installer énormément de logiciels en une ligne de commande.
Une fois Homebrew installé, installez Git à l'aide de la commande ci-après :
```bat=
$ brew install git
```
#### Installer Docker
Rendez-vous sur [Docker](https://www.docker.com/products/docker-desktop) et télechargez le fichier approprié selon votre système d'exploitation.
Lancez l'installateur et suivez les instructions pour installer Docker. Vous n'avez pas besoin de vous inscrire. Sautez le tutoriel lorsqu'il vous est proposé.
#### Installation des instances ElasticSearch et Kibana
:::warning
Attention, les commandes sont à rentrer ligne par ligne et non par bloc entier !
:::
Ouvrez votre terminal et clonez le répertoire GitHub [`docker-elk`](https://github.com/deviantony/docker-elk) :
```bat
git clone https://github.com/deviantony/docker-elk
````
Modifiez les lignes suivantes dans le fichier `elasticsearch.yml` dans `elasticsearch/config/` :
```yaml
xpack.license.self_generated.type: basic
xpack.security.enabled: false
```
Rendez-vous dans le répertoire cloné à l'aide de la commande `cd`, puis ordonnez à Docker de créer un groupe d'instance à partir des fichiers de configurations télechargés (il faut que Docker soit lancé et fonctionnel) :
:::spoiler Astuce (à la place de la commande ligne #1 ci-dessous) : sous Windows, il suffit de rentrer `cmd`...
<br />
... à la place du chemin au niveau du haut de la fenêtre de l'explorateur de fichiers (cf. capture d'écran ci-dessous) puis d'appuyer sur entrer.
:::
<br />
```bat=
cd docker-elk
docker-compose up setup
````
Puis, lancez les instances
```bat
docker-compose up
````
Vous devez alors patienter quelques minutes (ou plus) pour que cette étape se termine.
Une fois la commande terminée, vous pouvez accédez à Kibana en vous rendant à l'adresse suivante : http://localhost:5601. L'identifiant par défaut est `elastic` et le mot de passe `changeme`.
Notez que vous pouvez éteindre le conteneur « logstash-1 » étant donné que nous n'utiliserons pas cet outil lors de ce TP. Lorsque vous éteignez un conteneur, les opérations effectuées sur ce dernier sont sauvegardées donc n'ayez pas peur de quitter Docker, ou, d'éteindre votre ordinateur.
Pour la suite, rendez-vous directement à [la section découverte de l'interface Kibana](#D%C3%A9couverte-de-l%E2%80%99interface-Kibana).
---
### Installation « nature »
:::warning
La partie suivante est à effectuer seulement et seulement si vous ne parvenez pas à réaliser la partie précédente (Installation via Docker).
:::
#### Installation des instances ElasticSearch et Kibana
Dans un premier temps, rendez-vous sur Elastic et télechargez les archives appropriées selon votre système d'exploitation :
- ElasticSearch : https://www.elastic.co/fr/downloads/elasticsearch ;
- Kibana : https://www.elastic.co/fr/downloads/kibana.
Une fois le télechargement terminé, décompressez les archives.
Pour ElasticSearch puis Kibana :
- **pour ElasticSearch uniquement**, éditez le fichier `config/elasticsearch.yml` puis ajoutez la ligne ci-dessous en fin de fichier :
```yml
xpack.security.enabled: false
```
- lancez l'instance en exécutant le fichier binaire : double-cliquez sur le fichier `elasticsearch.bat` (sous Windows) ou `elasticsearch` (sous Mac OS) dans le répertoire `/bin` ou alors exécutez le binaire directement depuis un terminal (cf. aide ci-dessous).
Une fois les deux instances lancées, vous pouvez accédez à Kibana en vous rendant à l'adresse suivante : http://localhost:5601.
:::spoiler Aide pour lancer les instances depuis un terminal
###### Sous Windows :
Ouvrez un terminal PowerShell puis naviguez vers le dossier à l'aide de la commande `cd` (*ligne 1*, il faut adapter cette ligne à votre situation). Exécutez le binaire en précédant le nom du fichier à exécuter par `.\` (*ligne 2*)
Pour rappel, la comibaison de touches *SHIFT+clic droit* permet d'afficher un menu permettant d'ouvrir terminal directement dans le dossier courant sous Windows (« Ouvrir la fenêtre PowerShell ici »).
```=bash=
cd Downloads/elasticsearch-X.XX.X/bin
.\elasticsearch.bat
```
###### Sous Mac OS :
Ouvrez l'application Terminal puis naviguez vers le dossier à l'aide de la commande `cd` (*ligne 1*, il faut adapter cette ligne à votre situation). Exécutez le binaire en précédant le nom du fichier à exécuter par `./` (*ligne 2*).
```bash=
cd Downloads/elasticsearch-X.XX.X/bin
./elasticsearch
```
:::
<br />
:::warning
Attention, pour arrêter les instances, entrez la combinaison de touches *CTRL+c* dans la fenêtre de terminal, ne vous contentez pas de fermer cette dernière !
:::
## Découverte de l'interface Kibana
Pour découvrir l'interface Kibana, commencez par importer des données d'exemple fournies par l'outil. Pour ce faire, depuis [la page d'accueil](http://localhost:5601/app/home/#/), cliquez sur le lien « [Try sample data](http://localhost:5601/app/home#/tutorial_directory/sampleData) » (cf. image ci-dessous).
<div style="text-align:center">
<img src="https://i.imgur.com/S9CmsUk.png" />
</div>
Puis, déroulez le menu « Other sample data sets » en gris, en bas de la page.
Ajoutez ensuite les données « Sample eCommerce orders » à votre instance en cliquant sur le bouton « Add data ».
### Tour d'horizon de l'outil
#### Exploration des données
Commencez à vous familiariser avec le jeu de données précédemment importé en vous rendant sur l'onglet « [Discover](http://localhost:5601/app/discover#/) » du menu sur la gauche.
Sur cette interface, vous retrouverez deux éléments importants et communs à toutes les pages (cf. image ci-dessous) présentant des données : **le filtre « manuel »** et **le sélecteur de dates** qui permettent de filtrer les données utilisées dans l'affichage de la page.
<div style="text-align:center">
<img src="https://i.imgur.com/K8EO4Lp.png" />
</div>
##### Requêtage SQL
Sur le côté de l'onglet Discover, vous pouvez depuis peu utiliser des requêtes en utilisant la syntaxe [ES|QL](https://www.elastic.co/guide/en/elasticsearch/reference/current/esql-kibana.html) qui ressemble à la syntaxe SQL.
<div style="text-align:center">
<img src="https://hackmd.io/_uploads/SyobjozYp.png" />
</div>
#### Visualisations
Rendez-vous sur l'onglet « [Visualize Library](http://localhost:5601/app/visualize#/) » pour accéder à une liste de visualisations. Explorez les différentes visualisations basées sur les données d'exemple.
#### Tableaux de bords
Rendez-vous sur l'onglet « [Dashboard](http://localhost:5601/app/dashboards#/) » pour accéder à une liste de tableaux de bords. Sélectionnez le tableau de bord « [eCommerce] Revenue Dashboard ».
Les tableaux de bords permettent d'aggréger plusieurs visualisations et de filtrer de données (contrôles) sur lesquelles les visualisations vont se baser.
#### Canvas
Rendez-vous sur l'onglet « [Canvas](http://localhost:5601/app/canvas#/) » pour accéder à une infographie présentant les données d'exemple de manière dynamique.
#### Console « Dev Tools »
Rendez-vous sur l'onglet « [Dev Tools](http://localhost:5601/app/dev_tools#/console) » pour accéder à une console permettant des opérations plus techniques comme la recherche d'un document en particulier, la gestion des index, mappings, etc.
Vous trouverez ci-dessous un exemple à copier coller pour rechercher tous les documents correspondants au critère explicité.
```json
GET kibana_sample_data_ecommerce/_search
{
"query": {
"match": {
"customer_gender": "MALE"
}
}
}
```
Elasticsearch permet d'effectuer plusieurs types de requêtes :
- les filtres qui permettent de restreindre les résultats de recherche en fonction de certains critères, tels que la plage de temps ou les valeurs de champ spécifiques ;
- les agrégations qui permettent de regrouper les résultats de recherche en fonctions de certains critères, tels que les termes les plus fréquents ou les statistiques de champ.
Un exemple d'aggrégation pour obtenir le nombre de commandes par jour.
```json
GET kibana_sample_data_ecommerce/_search
{
"size": 0,
"aggs": {
"ip_over_time": {
"date_histogram": {
"field": "order_date",
"calendar_interval": "day"
}
}
}
}
```
## Exploration d'un jeu de données scientifiques
#### Données issues de HAL
[HAL](https://hal.archives-ouvertes.fr/) est la principale archive ouverte scientifique française. La plateforme est destinée au dépôt et à la diffusion d'articles scientifiques.
Le jeu de données [à télecharger](https://altab.fr/partage/M2/) comprend l'intégralité des notices liées à l'Université de Toulon et déposées depuis la création de la plateforme. Les champs décrivant un document (*fields*) sont décrits sur [la documentation de l'API HAL](https://api.archives-ouvertes.fr/docs/search/?schema=fields#fields).
#### Import du jeu de données
Pour importer un jeu de données conséquent, il faut utiliser des librairies tierces, pour ce faire, suivez ces 8 étapes :
- télechargez Node.js (20.11.0 LTS) depuis [le site officiel](https://nodejs.org/en/) puis installez le logiciel ;
- télechargez et dé-zippez l’archive « [hal-utln.zip](https://altab.fr/partage/M2/hal-utln2.zip) » ;
- ouvrez un terminal puis naviguez vers le dossier à l'aide de la commande `cd` (*ligne 1*, il faut adapter cette ligne à votre situation). Installez ensuite la librairie `elasticdump` (*ligne 2*). Importez alors le mapping (*ligne 3*) puis les données du jeu de données (*ligne 4*).
```bash=
cd Downloads/
npm install elasticdump -g
elasticdump --input=./hal-utln_mapping.json --output=http://elastic:changeme@localhost:9200/hal-utln --type=mapping
elasticdump --input=./hal-utln.json --output=http://elastic:changeme@localhost:9200/hal-utln --type=data
```
<br />
- rendez-vous ensuite sur l'onglet « [Stack Management](http://localhost:5601/app/management) » puis sur « [Data Views](http://localhost:5601/app/management/kibana/indexPatterns) » ;
- cliquez sur le bouton « Create data view » ;
- dans les champs « Name » et « Index pattern », entrez « hal-utln » ;
- dans le champ « Timestamp field », sélectionnez « submittedDate_tdate », le formulaire devrait correspondre à la capture d'écran ci-dessous ;
<div style="text-align:center; margin-bottom: 12px;">
<img src="https://i.imgur.com/n35FX3F.png" width="600" />
</div>
- cliquez sur le bouton « Save data view to Kibana ».
Le jeu de données est prêt à être exploité, passez aux [exercices](#Exercices--création-de-visualisations).
#### Erreurs possibles
##### Sous Windows
##### Erreur « [...] execution of running scripts is disabled on this system »
Si vous obtenez l'erreur contenant le message « [...] execution of running scripts is disabled on this system », exécutez la commande ci-dessous avant de reprendre la procédure :
```bash
Set-ExecutionPolicy unrestricted
```
##### Sous Mac OS
##### Erreur avec la commande `npm install elasticdump -g`
Si vous avez une erreur lorsque vous essayez d'exécuter la commande `npm install elasticdump -g`, précédez cette commande par `sudo` pour exécuter cette commande avec les droits d'administrateur.
```sh
sudo npm install elasticdump -g
```
#### Exercices : création de visualisations
Pour les questions suivantes, créez une visualisation répondant **le plus précisement et le plus clairement possible** aux souhaits des décideurs.
##### Gouvernance
« Je suis délégué à la science ouverte à l'Université de Toulon. La présidence de l'Université m'a demandé de connaître l'évolution dans le temps des dépôts sur la plateforme HAL ces 10 dernières années. »
##### Gouvernance
« La présidence de l'Université de Toulon m'a chargé d'établir un tableau présentant les revues dans lesquelles les chercheurs de l'Université de Toulon publient le plus sur les 10 dernières années. »
##### Gouvernance
« La présidence de l'Université de Toulon m'a chargé de dénombrer et d'identifier les références qui ne possède pas de [DOI](https://fr.wikipedia.org/wiki/Digital_Object_Identifier) sur les 10 dernières années. »
##### Collaboration internationale
« Je travaille au pôle dédié aux relations internationales de l'Université de Toulon et nous voulons développer nos partenariats européens. Pour ce faire, je souhaiterais connaître les pays avec lesquels les chercheurs de l'Université collaborent le plus au cours de ces 10 dernières années. »
##### Science ouverte
« Je suis délégué à la science ouverte à l'Université de Toulon. Je souhaite établir un état des lieux, sur les 10 dernières années, de la recherche toulonnaise d'un point de vue science ouverte. Il serait intéressant de voir la proportion des [types de revues](https://www.researchgate.net/profile/Anup-Das-4/publication/274007811/figure/tbl1/AS:613924907020310@1523382512832/Colour-codes-in-SHERPA-RoMEO_W640.jpg) qui publient les productions scientifiques et si ces dernières sont disponibles en libre accès ou non. »
#### Exercice : création d'un tableau de bord
Créez un tableau de bord présentant l'ensemble des visualisations précédement créées et ajoutez un sélecteur permettant de décliner les résultats par laboratoire.
#### Exercices : requêtage
Voici une liste de documents m'appartenant : https://api.archives-ouvertes.fr/search/?q=authIdHal_s:alaric-tabaries&fl=*, vous pourrez observer les champs et leurs valeurs et ainsi vous appuyer sur cela pour effectuer les requêtes.
Exécutez les requêtes (natif ou ES|QL) depuis la « Dev Tools » permettant d'afficher les informations suivantes :
- le `mapping` de l'index `hal-utln` ;
- les notices déposées après le 01/06/2023 (compris) ;
- le nombre de notices déposées en accès ouvert ;
- les notices où le champ `modifiedDate_tdate` existe ;
- le nombre de documents qui appartiennent au laboratoire IMSIC **ET** qui sont en accès ouvert ;
- le nombre de notices relevant des sciences de l'information et de la communication avec la répartition par année (indice : `aggs`).
## Développer autour de ELK
### Interconnecter Python et ElasticSearch
:::info
Si vous n'avez pas encore d'environnement de développement, jetez un oeil à [PyCharm Community Edition](https://www.jetbrains.com/fr-fr/pycharm/download/#section=windows).
:::
Vous pouvez requêter une instance ElasticSearch (insertion de données, interrogation, etc.) depuis votre code Python à l'aide du [du module Elasticsearch sur Python](https://elasticsearch-py.readthedocs.io/en/v7.15.2/).
Pour ce faire, créez un projet puis installez le module ElasticSearch à l'aide de PyPi :
```sh
pip install elasticsearch
```
Pour interroger l'instance ElasticSearch et obtenir des données qui correspondent à votre requête, il vous suffit de ré-utiliser l'extrait de code commenté ci-dessous.
Vous pouvez également utiliser [la syntaxe ES|QL](https://www.elastic.co/guide/en/elasticsearch/reference/current/esql-query-api.html) pour requêter.
```py=
from elasticsearch import Elasticsearch, helpers
# Connexion à l'instance ElasticSearch
es = Elasticsearch(hosts="http://elastic:changeme@localhost:9200/")
# Requête
request = {
"match_all": {}
}
# Interrogation de l'instance ElasticSearch
result = es.search(index="test", query=request)
for res in result["hits"]["hits"]:
print(res)
```
Pour insérer des données dans l'instance ElasticSearch, il vous suffit de ré-utiliser l'extrait de code commenté ci-dessous. Le premier bloc correspond à une insertion document par document alors que le second correspond à une insertion de masse.
```py=
from elasticsearch import Elasticsearch, helpers
# Connexion à l'instance ElasticSearch
es = Elasticsearch(hosts="http://elastic:changeme@localhost:9200/")
my_dict = {...}
# Insertion d'un document (ou dictionnaire en Python)
result = es.index(index="index-name", body=my_dict)
```
```py=
from elasticsearch import Elasticsearch, helpers
# Connexion à l'instance ElasticSearch
es = Elasticsearch(hosts="http://elastic:changeme@localhost:9200/")
list_dict = [
{...},
{...},
{...}
]
# Insertion d'une liste de documents (ou liste de dictionnaires en Python)
result = helpers.bulk(
es,
list_dict,
index="index-name",
)
```
## Évaluation
### Import du jeu de données
En suivant les mêmes étapes que [l'import précédent](#Import-du-jeu-de-données), télechargez et dé-zippez l’archive [« es_decathlon.zip »](https://altab.fr/partage/decathlon.zip) (disponible seulement le jour de l'évaluation) puis importez le.
:::warning
Pensez à remplacer `hal-utln` par `decathlon` dans les commandes. **Il n'est pas nécessaire d'éxecuter à nouveau la commande `npm install elasticdump -g` (ligne 2)** donc exécutez seulement **les lignes 3 et 4** adaptés à ce jeu de données.
:::
### Questionnaire
Le questionnaire est noté sur 10 points : 6 questions sur le cours, 5 questions sur le jeu de données précédemment importé. Merci de ne pas utiliser votre voisin(e), l'utilisation du support de cours est autorisée.
Pour la sélection des dates, basez-vous sur 00:00 comme heure.
Remplissez le questionnaire Google Forms disponible en cliquant [ici](https://docs.google.com/forms/d/e/1FAIpQLSe5CSfwxJ2edbgGCr6IFYY97xuos1fmNJJiL1ainp04M0yX0A/viewform?usp=sf_linkifc) (disponible seulement le jour de l'évaluation).
### Présentation
Vous devez présenter un tableau **le plus complet**, **le plus flexible**, **le plus clair** et **le plus simple d'utilisation** possible à destination du responsable du site e-commerce d'où proviennent les données. Cet utilisateur ne connaît pas l'outil Kibana.
Vous avez également la possibilité de créer un canvas au lieu d'un tableau de bord.
**Bonus : vous pouvez aussi créer vous même votre jeu de données (par exemple, à partir des données d'entreprises vues en atelier développement !).**
Votre tableau de bord est noté sur 10 points.
## Désinstaller les logiciels et librairies
Si vous souhaitez désinstaller les logiciels et librairies qui étaient nécessaires pour la réalisation de cet atelier, suivez les étapes ci dessous :
- supprimez les conteneurs Docker (depuis l'interface graphique, cliquez sur le bouton « corbeille » correspondant à l'instance) ;
- désinstallez Docker ;
- exécutez la commande `npm uninstall -g elasticdump` dans Terminal (Mac OS) ou PowerShell (Windows) ;
- désinstallez Node.js.
Sign in with Wallet
Connect another wallet