For AI agents: the complete documentation index is available at https://docs.ovhcloud.com/fr/llms.txt, the full documentation bundle is available at https://docs.ovhcloud.com/fr/llms-full.txt, and this page is available as Markdown at https://docs.ovhcloud.com/fr/guides/manage-and-operate/observability/logs-data-platform/elastalert.md.

Alertes - Utiliser ElastAlert 2 avec Logs Data Platform

Voir en Markdown

Déployez en quelques minutes l'un des systèmes d'alerte les plus complets.

Objectif

ElastAlert 2 est un framework d'alerte conçu à l'origine par Yelp. Il est capable de détecter des anomalies, des pics, ou d'autres schémas intéressants. Il est prêt pour la production et constitue un standard bien connu de l'alerte dans l'écosystème Elasticsearch/OpenSearch. Leur devise est : « Si vous pouvez le voir dans vos tableaux de bord, ElastAlert 2 peut vous alerter dessus. » Dans ce document, vous apprendrez à déployer ce composant sur Logs Data Platform grâce à sa compatibilité avec OpenSearch via les alias et les index. Logs Data Platform vous permet également d'héberger les méta-index d'ElastAlert sur Logs Data Platform.

Prérequis

Notez que pour suivre ce tutoriel, vous devez au moins disposer de :

Accès à l'espace client OVHcloud

  • Lien direct :
  • Pour accéder à vos services : Identité, Sécurité & Opérations > Logs Data Platform > Sélectionnez la plateforme concernée

Préparation

Pour déployer ElastAlert, il est important que vous disposiez de données sur lesquelles vous pouvez voir des alertes. Si vous avez uniquement un flux Graylog, vous pouvez utiliser des alias pour activer l'API OpenSearch sur les données de votre flux. Voici comment procéder :

  1. Dans l'onglet Alias, cliquez sur le bouton Ajouter un alias.
  2. Choisissez un nom et définissez une description pour votre alias.
  3. Enregistrez l'entrée en cliquant sur le bouton Sauvegarder.
  4. Une fois l'alias créé, utilisez le menu ... à droite et sélectionnez l'option Attacher du contenu à l'alias.
  5. Définissez-y les flux de données que vous souhaitez associer à votre alias.
  6. C'est terminé.
Création d'un alias

Si vous disposez uniquement d'index, vous pouvez les utiliser directement dans la configuration d'ElastAlert.

En pratique

La configuration d'ElastAlert comporte trois étapes :

  • Installer ElastAlert et ses index de métadonnées.
  • Configurer le fichier de configuration principal.
  • Configurer les règles d'alerte.

Installation

L'installation d'ElastAlert peut se faire de différentes manières, comme décrit dans leur documentation. Vous pouvez soit utiliser l'image docker, soit installer les paquets python 3. Vous devez vérifier que votre version de Python est compatible avec ElastAlert. Consultez la documentation pour vérifier quelle version de Python est compatible. Veillez également à respecter tous les prérequis avant de tenter l'installation.

Vous pouvez soit installer la dernière version publiée d'ElastAlert 2 à l'aide de pip :

$ pip install elastalert2

soit d'abord cloner le dépôt ElastAlert2 pour obtenir les changements les plus récents :

$ git clone https://github.com/jertel/elastalert2.git

Puis installer le module :

$ pip install "setuptools>=11.3"
$ python setup.py install

En cas d'erreur concernant des paquets manquants, installez-les manuellement. Par exemple :

$ pip install setuptools_rust

L'étape suivante consiste à configurer les méta-index d'ElastAlert à l'aide de l'outil fourni elastalert-create-index. ElastAlert a besoin de 5 index pour fonctionner :

  • L'index generic contenant toutes les alertes actives.
  • L'index status contenant les requêtes exécutées pour déclencher les alertes.
  • L'index error avec toutes les erreurs rencontrées.
  • L'index silence indiquant si une alerte récurrente doit être déclenchée ou mise en sourdine.
  • L'index past avec toutes les alertes déclenchées et closes.

La commande suivante crée les index sur Logs Data Platform directement depuis l'API OpenSearch.

$ elastalert-create-index --host <ldp-cluster>.logs.ovh.com --port 9200 --username `<username>` --password <password> --ssl --index <username>-i-`<suffix>`

Vous devez porter attention aux points suivants :

  • Le <ldp-cluster> doit être celui qui vous a été attribué (à retrouver sur la page Home du LDP Manager).
  • <username> est le nom d'utilisateur utilisé pour se connecter à l'API ou aux interfaces de Logs Data Platform (Graylog ou OpenSearch Dashboards).
  • <password> est le mot de passe associé. Vous pouvez utiliser des jetons à la place du couple nom d'utilisateur/mot de passe pour vos identifiants.
  • Le --index est le paramètre le plus important ici, car vous devez respecter la convention de nommage des index de Logs Data Platform. Utilisez la forme présentée <username>-i- comme nom de base pour vos méta-index. <suffix> peut être personnalisé avec n'importe quels caractères alphanumériques.

Cette commande vous posera différentes questions :

Verify TLS certificates? t/f: t
Enter optional OpenSearch URL prefix (prepends a string to the URL of every request):
Name of existing index to copy? (Default None)
Reading Elastic 8 index mappings:
Reading index mapping 'es_mappings/8/silence.json'
Reading index mapping 'es_mappings/8/elastalert_status.json'
Reading index mapping 'es_mappings/8/elastalert.json'
Reading index mapping 'es_mappings/8/past_elastalert.json'
Reading index mapping 'es_mappings/8/elastalert_error.json'
New index logs-**-*****-i-***** created
Done!

Cela crée alors 5 index et y applique le mapping. Il ne vous reste plus qu'à créer le fichier de configuration d'ElastAlert et quelques règles.

Fichier de configuration ElastAlert.

Créez un répertoire de configuration (par exemple /opt/elastalert/) et un répertoire de règles avant de poursuivre (comme /opt/elastalert/rules). Ce répertoire de règles sera utilisé dans la configuration ci-dessous. Voici un exemple de fichier config.yml que vous pouvez utiliser pour votre configuration dans votre répertoire de configuration :

rules_folder: /opt/elastalert/rules
run_every:
  minutes: 5
buffer_time:
  hours: 6
es_host: <ldp-cluster>.logs.ovh.com
es_port: 9200
use_ssl: True
verify_certs: True
es_username: `<username>`
es_password: <password>
writeback_index: `<username>`-i-`<suffix>`
alert_time_limit:
  days: 2

Vous pouvez retrouver toutes les options disponibles ici.

  • rules_folder est l'emplacement d'où ElastAlert chargera les fichiers de configuration des règles. Il tentera de charger chaque fichier .yaml présent dans le dossier. Sans règles valides dans ce dossier, ElastAlert ne démarrera pas.
  • run_every définit la fréquence à laquelle ElastAlert interroge OpenSearch.
  • buffer_time est la taille de la fenêtre de requête, s'étendant en arrière à partir du moment où chaque requête est exécutée.
  • es_host est l'adresse d'un cluster OpenSearch où ElastAlert stocke les données sur son état, les requêtes exécutées, les alertes et les erreurs. Chaque règle peut également utiliser un hôte OpenSearch différent pour ses requêtes.
  • es_port est le port correspondant à es_host.
  • use_ssl : indique s'il faut se connecter à es_host en utilisant TLS. TLS est obligatoire sur notre plateforme.
  • verify_certs indique s'il faut vérifier les certificats TLS. Notre plateforme utilise des certificats validés par la plupart des systèmes d'exploitation et navigateurs.
  • es_username est le nom d'utilisateur utilisé pour se connecter aux API OpenSearch.
  • es_password est le mot de passe utilisé pour se connecter aux API OpenSearch. N'oubliez pas que vous pouvez utiliser des jetons à la place de ces identifiants.
  • writeback_index est le nom de l'index dans lequel ElastAlert stocke les données. Utilisez le même nom que celui utilisé pour configurer les index avec elastalert-create-index.
  • alert_time_limit est la fenêtre de nouvelle tentative pour les alertes échouées.

Configuration des règles

Dans cet exemple, nous allons créer une règle frequency.yml qui envoie un e-mail si le champ user avec la valeur Oles apparaît plus de 3 fois en moins de 4 heures, et utilise le logger de débogage debug.

name: Example frequency rule

# (Required)
# Type of alert.
# the frequency rule type alerts when num_events events occur with timeframe time
type: frequency

# (Required)
# Index to search, wildcard supported
index:  <index-or-alias-to-check>

# (Required, frequency specific)
# Alert when this many documents matching the query occur within a timeframe
num_events: 3

# (Required, frequency specific)
# num_events must occur within this amount of time to trigger an alert
timeframe:
  hours: 4

timestamp_field: timestamp
timestamp_type: custom
timestamp_format: '%Y-%m-%d %H:%M:%S.%f'
timestamp_format_expr:  'ts[:23]'
timestamp_to_datetime_format_expr: 'ts[:23]'

# (Required)
# A list of OpenSearch filters used for find events
# These filters are joined with AND and nested in a filtered query
# For more info: https://opensearch.org/docs/latest/opensearch/query-dsl/index/
filter:
- term:
    user: "Oles"

# (Required)
# The alert is used when a match is found
alert:
- "debug"

Nous ne détaillerons pas tous les paramètres puisque la plupart se comprennent d'eux-mêmes. Cependant, veuillez porter attention au paramètre index. Cet index ou alias est celui contenant les logs ou documents à partir desquels vous souhaitez être alerté.

Il est également important de personnaliser les paramètres de timestamp selon le timestamp de vos logs ou documents. Ici, nous personnalisons un timestamp custom sur le timestamp_field timestamp avec le format utilisé dans le pipeline de logs %Y-%m-%d %H:%M:%S.%f. Comme ce format peut comporter plus de 3 chiffres supplémentaires, nous devons les tronquer à l'aide de l'option timestamp_format_expr. Notez qu'Elastalert ne prend pas en charge les nanosecondes, c'est pourquoi l'option timestamp_to_datetime_format_expr tronque la chaîne de timestamp à 23 caractères, afin qu'elle puisse être parsée.

Lancer ElastAlert

Pour lancer ElastAlert, utilisez la commande suivante :

$ elastalert --config config.yml --debug

config.yml est le fichier de configuration principal décrit précédemment. L'option --debug est là pour s'assurer que tout fonctionne correctement. Vous pouvez la désactiver en production une fois qu'ElastAlert est entièrement configuré.

Pour tester votre alerte, vous pouvez utiliser la commande curl suivante en envoyant des logs vers notre endpoint OpenSearch :

$ curl -H 'Content-Type: application/json' -u '`<username>`:<password>' -XPOST https://<ldp-cluster>.logs.ovh.com:9200/ldp-logs/_doc -d '{ "X-OVH-TOKEN" : "<stream-token>" , "test_field" : "OVHcloud" , "user": "Oles", "short_message" : "Hello OpenSearch input", "host" : "OVHcloud_elastalert" }'

Si vous envoyez cet événement plus de 3 fois, le processus elastalert affiche l'alerte déclenchée.

user01@test:~/rules$ elastalert --config config.yml --debug
INFO:elastalert:Note: In debug mode, alerts will be logged to console but NOT actually sent.
To send them but remain verbose, use --verbose instead.
INFO:elastalert:Note: In debug mode, alerts will be logged to console but NOT actually sent.
To send them but remain verbose, use --verbose instead.
INFO:elastalert:1 rules loaded
INFO:elastalert:Starting up
INFO:elastalert:Disabled rules are: []
INFO:elastalert:Sleeping for 299.999899 seconds
INFO:elastalert:Queried rule Example frequency rule from 2024-08-06 04:03 EDT to 2024-08-06 10:03 EDT: 16 / 16 hits
INFO:elastalert:Skipping writing to ES: {'exponent': 0, 'rule_name': 'Example frequency rule', '@timestamp': '2024-08-06T14:03:25.155726Z', 'until': '2024-08-06T14:04:25.155713Z'}
INFO:elastalert:Alert for Example frequency rule at 2024-08-06T13:46:26.335Z:
INFO:elastalert:Example frequency rule

ElastAlert dispose de nombreuses intégrations pour les alertes, notamment Email, JIRA, OpsGenie, SNS, HipChat, Slack, MS Teams, PagerDuty, Zabbix, des commandes personnalisées et bien plus encore.

Aller plus loin

Cette page vous a-t-elle aidé ?