Scripting Ruby dans Logstash

Elasticsearch vous permet d’indexer des données rapidement et en toute flexibilité. Essayez-le gratuitement dans le cloud ou exécutez-le en local pour découvrir à quel point l’indexation peut être simple.

Logstash est un pipeline de traitement de données qui ingère des données provenant de sources multiples, les transforme et les envoie vers les destinations de votre choix. Les plugins de filtrage sont essentiels pour ce processus ; ils effectuent des opérations spécifiques sur vos données lorsqu'elles passent par le pipeline.

Logstash comprend plusieurs filtres intégrés pour les tâches courantes telles que l'analyse, l'enrichissement et la modification des données. Mais parfois, vous rencontrerez des scénarios qui nécessiteront une logique personnalisée allant au-delà de ce que ces filtres standard peuvent fournir. C'est là qu'intervient le plugin Ruby filter.

Le plugin Ruby filter vous permet d'exécuter du code Ruby personnalisé directement dans votre pipeline Logstash. Lorsque les filtres standard ne suffisent pas, le filtre Ruby vous permet de gérer des transformations de données complexes, de mettre en œuvre une logique commerciale personnalisée ou d'intégrer des systèmes externes.

Dans ce blog, nous allons explorer comment utiliser les filtres Ruby, de l'utilisation basique à l'utilisation avancée.

Quand utiliser le filtre Ruby ?

En tant qu'architecte consultant d'Elastic, je vois souvent des clients utiliser Logstash pour le pipeline de traitement des données, même s'il ne s'agit pas aujourd'hui d'un moteur de traitement des données à la pointe de la technologie. Ils se heurtent souvent aux limites des filtres standard lorsqu'il s'agit de manipuler des données complexes ou d'appliquer une logique personnalisée. Dans ce cas, le filtre Ruby peut aider à surmonter ces difficultés.

Le filtre Ruby est utile lorsque les filtres standard de Logstash ne peuvent pas répondre à vos besoins spécifiques. Voici quelques cas d'utilisation courants :

• Manipulation de données imbriquées en profondeur: Modifier des structures JSON complexes, des tableaux dans des tableaux, ou restructurer dynamiquement des données en fonction de leur contenu.
• Traitement avancé des chaînes de caractères: Analyse et extraction de données structurées à partir de textes non structurés
• Mise en œuvre d'une logique d'entreprise complexe: Créer des transformations personnalisées qui nécessitent une logique conditionnelle, des boucles ou des calculs complexes.

Utilisation de base

Commençons par un exemple simple pour comprendre le fonctionnement du filtre Ruby.

Configuration du filtre Ruby

Lorsque vous créez un pipeline Logstash, vous devez placer le fichier de configuration dans le répertoire /etc/logstash/conf.d. Alternativement, vous pouvez utiliser l'option -f pour spécifier le chemin vers le fichier de configuration lorsque vous démarrez Logstash manuellement, afin que vous puissiez expérimenter vos pipelines facilement.

Le fichier de configuration doit avoir une extension .conf.

Pour utiliser le filtre Ruby, définissez un filtre ruby dans la section filter de votre fichier de configuration du pipeline Logstash (*.conf). Voici un exemple de base :

Ce filtre Ruby en ligne définit une instance de filtre Ruby dans votre configuration Logstash. Le paramètre code fournit le script Ruby en ligne que Logstash exécutera pour chaque événement traité par ce filtre. Dans ce script, il existe une variable event qui représente l'événement lui-même. L'objet événement contient les données originales envoyées à Logstash et tous les champs supplémentaires créés lors des étapes de filtrage de Logstash. Vous pouvez accéder à ces champs via l'API Logstash Event telle que event.get() et event.set(). Dans cet exemple de code, event.set('new_field', 'Hello from Ruby!') attribue à un nouveau champ nommé new_field la valeur de chaîne Hello from Ruby!. Vous pouvez ajouter tout autre code dans ce bloc code si nécessaire.

Notez que cet objet event n'est pas un objet de hachage Ruby habituel, bien qu'il agisse comme un conteneur de données de type clé-valeur. Consultez la documentation officielle pour en savoir plus sur l'API des événements.

Externaliser le script Ruby

Pour les transformations simples, le code Ruby en ligne est pratique. Mais pour une logique complexe ou des fonctions réutilisables, il est recommandé de déplacer le code dans un script Ruby externe. Cela permet d'améliorer la maintenabilité et de conserver une configuration propre du pipeline Logstash.

Tout d'abord, créez un script Ruby et enregistrez-le sous my_ruby_script.rb. Le script doit définir une méthode filter qui traite l'événement. Elle prend en argument un objet événement qui représente l'événement en cours de traitement. La méthode filter doit renvoyer un tableau d'événements à émettre. Pour supprimer l'événement, renvoyer un tableau vide.

Par exemple, le script suivant lit la rubrique message, calcule sa longueur et stocke le résultat dans une nouvelle rubrique appelée message_length.

Ensuite, définissez la configuration du filtre Ruby pour qu'il fasse référence au script à l'aide de l'option path. Cela indique à Logstash de charger et d'exécuter le script externe. Lors de l'utilisation de scripts externes, assurez-vous que le fichier existe et que les autorisations sont correctes.

Maintenant, chaque événement est transmis à la méthode filter dans my_ruby_script.rb et est traité par elle.

Cette approche vous permet de gérer plus efficacement une logique complexe, ce qui facilite les tests, le débogage et la réutilisation de votre code Ruby.

Utilisation avancée

Dans cette section, nous allons explorer quelques exemples avancés d'utilisation du filtre Ruby dans Logstash. Ces exemples montrent comment effectuer des transformations de données, enrichir des événements et mettre en œuvre une logique personnalisée à l'aide de Ruby.

Manipulation de structures de données imbriquées

Un événement Logstash est la structure de données centrale que Logstash traite. Il peut contenir différents champs, y compris des structures de données imbriquées telles que des tableaux et des hachages. Le filtre Ruby permet de manipuler facilement ces structures imbriquées.

Le filtre Ruby peut gérer des structures de données imbriquées, telles que des hachages et des tableaux, ce qui permet de modifier ou d'ajouter des champs dans ces structures. Cette fonction est utile lorsqu'il s'agit de traiter des formats de données complexes tels que JSON.

Cet exemple inclut un objet JSON imbriqué dans les données d'entrée. Le filtre Ruby modifie les données imbriquées en ajoutant une nouvelle paire clé-valeur. Ce type de manipulation des données imbriquées n'est pas possible avec les filtres Logstash standard, ce qui fait du filtre Ruby une option pratique pour les structures de données complexes.

Diviser un événement unique en plusieurs événements

Les filtres Ruby peuvent également être utilisés pour diviser un événement unique en plusieurs événements. Ceci est utile lorsque vous avez un événement unique contenant un tableau d'éléments et que vous souhaitez créer des événements distincts pour chaque élément.

Notez que ni le pipeline d'acquisition d'Elasticsearch ni les processeurs de Beats/Elastic Agent ne prennent en charge le fractionnement des événements. C'est l'un des cas d'utilisation les plus importants pour Logstash.

Avec filtre divisé

Vous pouvez utiliser le filtre split pour diviser un événement en plusieurs événements sur la base d'un champ spécifié. Toutefois, si vous devez effectuer des transformations ou des opérations logiques supplémentaires pendant le fractionnement, vous pouvez utiliser le filtre Ruby en combinaison avec le filtre de fractionnement.

Dans l'exemple suivant, nous avons un flux RSS sous la forme d'une seule ligne de texte XML. Il contient plusieurs éléments <item>. Le filtre Ruby est utilisé pour extraire les éléments <item> du XML et les stocker dans un nouveau champ appelé items. Le filtre de division est ensuite utilisé pour diviser l'événement en plusieurs événements sur la base du champ items.

Le résultat sera le suivant :

Comme vous l'avez peut-être remarqué, le filtre ruby n'est pas indispensable dans ce cas. Le filtre split peut être utilisé pour diviser l'événement en plusieurs événements sur la base du champ items, et le filtre mutate peut être utilisé pour supprimer les champs inutiles. Toutefois, si vous devez effectuer des transformations ou des opérations logiques supplémentaires pendant le fractionnement, vous pouvez utiliser le filtre Ruby.

Utiliser un script Ruby en ligne

Vous pouvez également utiliser un script Ruby en ligne pour diviser un événement unique en plusieurs événements en utilisant la méthode event.clone et la méthode new_event_block variable, telle que new_event_block.call(new_event). Cela vous permet de créer de nouveaux événements basés sur l'événement original tout en préservant ses données.

Voici un exemple d'utilisation du filtre Ruby pour diviser un événement unique en plusieurs événements. L'entrée et la sortie sont les mêmes que dans l'exemple précédent.

Utiliser un script Ruby externe

Vous pouvez également utiliser un script Ruby externe pour diviser un événement unique en plusieurs événements.

Fichier de configuration :

Le script Ruby doit être externalisé en tant que split_event.rb:

N'oubliez pas que la méthode filter doit renvoyer un tableau d'événements. Vous pouvez renvoyer plusieurs événements en clonant un objet événement entrant et en l'ajoutant au tableau, ou vous pouvez renvoyer un seul événement sous la forme d'un tableau à un seul élément.

Cela vous permet de diviser un événement unique en plusieurs événements.

Exécuter des commandes externes et analyser leurs résultats

Le plugin Logstash exec input vous permet d'exécuter des commandes externes et leur sortie sera un événement de Logstash. La sortie de la commande sera stockée dans le champ message de l'événement.

Habituellement, la sortie des commandes système est lisible par l'homme, mais n'est pas structurée en JSON ou dans d'autres formats que Logstash peut facilement analyser. Pour ce faire, vous pouvez utiliser le filtre Ruby pour analyser la sortie et en extraire les informations.

Voici un exemple d'utilisation du plugin d'entrée exec pour exécuter la commande ps -ef, qui répertorie tous les processus en cours d'exécution sur un système de type Unix. La sortie sera analysée par le filtre Ruby afin d'extraire les informations pertinentes sur chaque processus.

Cet exemple utilise le plugin d'entrée exec pour exécuter la commande ps -ef toutes les 60 secondes. Le filtre Ruby traite la sortie, en extrayant les champs pertinents tels que UID, PID, PPID, l'utilisation du CPU (C), l'heure de démarrage (STIME), TTY, le temps total du CPU (TIME), et la commande (CMD) exécutée. Cela fonctionne bien dans mon environnement macOS, mais il se peut que vous deviez ajuster les motifs des expressions rationnelles pour qu'ils correspondent au format de sortie de la commande ps -ef sur votre système.

Utiliser les bibliothèques intégrées

Le plugin de filtrage Ruby vous permet d'utiliser des bibliothèques Ruby intégrées, qui peuvent s'avérer très utiles pour diverses tâches. Par exemple, vous pouvez utiliser la bibliothèque json pour analyser les chaînes JSON ou la bibliothèque date pour manipuler les dates.

Voici un exemple d'utilisation de la bibliothèque json pour analyser une chaîne JSON stockée dans un champ :

Pour éviter d'avoir besoin de la bibliothèque à chaque fois, vous devriez externaliser votre code Ruby afin d'utiliser l'instruction require au début de votre script de filtrage Ruby. Cela chargera la bibliothèque une fois et la rendra disponible pour une utilisation dans votre script.

Pour vérifier quelles sont les bibliothèques disponibles dans votre environnement, vous pouvez dresser la liste des bibliothèques intégrées en exécutant le code suivant dans le filtre Ruby :

Note : Les bibliothèques intégrées ne sont pas officiellement supportées par Logstash, et leur comportement peut changer ou elles peuvent ne pas être disponibles dans les versions futures. Utilisez-les à vos risques et périls.

Conclusion

Le filtre Logstash Ruby vous permet de personnaliser et d'étendre les capacités de vos pipelines Logstash. Dans ce billet, nous avons couvert les bases de l'utilisation du filtre Ruby et fourni des exemples d'utilisation avancée.

En tirant parti du filtre Ruby, vous pouvez effectuer des tâches de traitement de données complexes qui nécessitent une logique personnalisée ou des manipulations avancées. Que vous travailliez avec des structures de données imbriquées, que vous fractionniez des événements ou que vous analysiez et convertissiez du texte complexe/non structuré en JSON structuré, le filtre Ruby offre la flexibilité nécessaire pour répondre à vos besoins spécifiques.

Nous espérons que ce guide vous a apporté les connaissances et l'inspiration nécessaires pour explorer tout le potentiel du filtre Logstash Ruby. Bonne lecture !