Prétraitement de la valeur de l'élément

Vue d'ensemble

Le prétraitement vous permet d'appliquer des transformations aux valeurs d'élément reçues avant de les enregistrer dans la base de données. Ces transformations/étapes de prétraitement sont effectuées par le serveur Zabbix ou le proxy (si les éléments sont supervisés par un proxy).

Cette fonctionnalité prend en charge divers cas d'utilisation, tels que :

• convertir des octets en bits (par exemple, multiplier les valeurs de trafic réseau par « 8 ») ;
• calculer des statistiques par seconde pour des valeurs augmentant de manière incrémentielle ;
• appliquer des expressions régulières pour extraire ou modifier des valeurs ;
• exécuter des scripts personnalisés sur des valeurs ;
• ignorer les valeurs inchangées afin d'optimiser le stockage dans la base de données.

Une ou plusieurs étapes de prétraitement peuvent être configurées pour un élément. Ces étapes sont exécutées dans l'ordre dans lequel elles sont configurées.

Toutes les valeurs transmises au prétraitement sont initialement traitées comme des chaînes de caractères. La conversion vers le type de valeur souhaité (tel que défini dans la configuration de l'élément) est effectuée à la fin du pipeline de prétraitement. Cependant, certaines étapes de prétraitement peuvent déclencher des conversions plus tôt, si nécessaire. Pour des informations techniques détaillées, voir Détails du prétraitement.

Pour vous assurer que votre configuration de prétraitement fonctionne comme prévu, vous pouvez la tester.

Voir aussi : Exemples de prétraitement

Configuration

Les étapes de prétraitement sont définies dans l'onglet Prétraitement du formulaire de configuration de l'élément.

Cliquez sur Ajouter pour sélectionner une transformation prise en charge.

Le champ Type d'information s'affiche en bas de l'onglet lorsqu'au moins une étape de prétraitement est définie. Si nécessaire, il est possible de modifier le type d'information sans quitter l'onglet Prétraitement. Consultez Créer un élément pour obtenir une description détaillée des paramètres.

Transformations prises en charge

Toutes les transformations prises en charge sont répertoriées ci-dessous. Cliquez sur le nom d'une transformation pour afficher tous ses détails.

Si la case Personnaliser en cas d'échec est activée pour la transformation sélectionnée, vous pouvez la cocher et indiquer des options personnalisées de gestion des erreurs : Ignorer la valeur (ignorer la valeur), Définir la valeur sur (définir une valeur indiquée) ou Définir l'erreur sur (définir un message d'erreur indiqué). Si une étape de prétraitement échoue, l'élément ne deviendra pas non pris en charge lorsque l'option Ignorer la valeur ou Définir la valeur sur est sélectionnée.

Notez que pour les étapes de prétraitement Changement et Limitation, Zabbix doit mémoriser la dernière valeur afin de calculer ou de comparer la nouvelle valeur comme requis. Ces valeurs précédentes sont gérées par le gestionnaire de prétraitement. Si le serveur Zabbix ou le proxy est redémarré, ou si une modification est apportée aux étapes de prétraitement, la dernière valeur de l'élément correspondant est réinitialisée, ce qui entraîne les conséquences suivantes :

• pour les étapes Changement simple et Changement par seconde : la valeur suivante sera ignorée, car aucune valeur précédente ne permet de calculer le changement ;
• pour les étapes Ignorer les valeurs inchangées et Ignorer les valeurs inchangées avec pulsation : la valeur suivante ne sera jamais ignorée, même si elle aurait dû l'être selon les règles d'ignorance.

Expression régulière

Faites correspondre la valeur à l’expression régulière et remplacez-la par la sortie requise.

Paramètres :

• pattern - l’expression régulière ;
  
• output - le modèle de formatage de la sortie. Une séquence d’échappement \N (où N=1…9) est remplacée par le Nᵉ groupe correspondant. Une séquence d’échappement \0 est remplacée par le texte correspondant.

Commentaires :

• Si la valeur d’entrée ne correspond pas, l’élément devient non pris en charge ;
  
• L’expression régulière prend en charge l’extraction de 10 groupes capturés au maximum avec la séquence \N ;
  
• Consultez la section expressions régulières pour voir quelques exemples existants.

Remplacer

Recherchez la chaîne de recherche et remplacez-la par une autre (ou par rien).

Paramètres :

• chaîne de recherche - la chaîne à rechercher et à remplacer, sensible à la casse (obligatoire) ;
  
• remplacement - la chaîne qui remplacera la chaîne de recherche. La chaîne de remplacement peut également être vide, ce qui permet effectivement de supprimer la chaîne de recherche lorsqu’elle est trouvée.

Commentaires :

• Toutes les occurrences de la chaîne de recherche seront remplacées ;
• Il est possible d’utiliser des séquences d’échappement pour rechercher ou remplacer des sauts de ligne, retours chariot, tabulations et espaces "\n \r \t \s" ; l’antislash peut être échappé sous la forme "\\" et les séquences d’échappement peuvent être échappées sous la forme "\\n" ;
• L’échappement des sauts de ligne, retours chariot et tabulations est effectué automatiquement lors de la découverte de bas niveau.

Supprimer

Supprime les caractères spécifiés au début et à la fin de la valeur.

Suppression à droite

Supprime les caractères spécifiés à la fin de la valeur.

Suppression à gauche

Supprime les caractères spécifiés du début de la valeur.

XML XPath

Extraire une valeur ou un fragment de données XML à l'aide de la fonctionnalité XPath.

Commentaires :

• Pour que cette option fonctionne, le serveur Zabbix (ou le proxy Zabbix) doit être compilé avec la prise en charge de libxml ;
  
• Les espaces de noms ne sont pas pris en charge.

Exemples :

number(/document/item/value) #extraiera '10' de <document><item><value>10</value></item></document>
number(/document/item/@attribute) #extraiera '10' de <document><item attribute="10"></item></document>
/document/item #extraiera '<item><value>10</value></item>' de <document><item><value>10</value></item></document>

JSONPath

Extraire une valeur ou un fragment de données JSON à l'aide de la fonctionnalité JSONPath.

CSV vers JSON

Convertissez les données d’un fichier CSV au format JSON.

Pour plus d’informations, voir : prétraitement CSV vers JSON.

XML vers JSON

Convertit les données au format XML en JSON.

Pour plus d'informations, consultez : Règles de sérialisation.

Valeur de parcours SNMP

Extraire la valeur à l'aide de l'OID/nom MIB spécifié et appliquer les options de formatage :

• Inchangée - renvoyer la chaîne hexadécimale sous forme de chaîne hexadécimale non échappée (notez que les indications d'affichage sont toujours appliquées) ;
  
• UTF-8 depuis une chaîne HEX - convertir la chaîne hexadécimale en chaîne UTF-8 ;
  
• MAC depuis une chaîne HEX - valider la chaîne hexadécimale comme adresse MAC et renvoyer une chaîne d'adresse MAC correcte (où les ' ' sont remplacés par ':') ;
  
• Entier depuis BITS - convertir les 8 premiers octets d'une chaîne de bits exprimée sous forme de séquence de caractères hexadécimaux (par exemple, « 1A 2B 3C 4D ») en entier non signé de 64 bits. Dans les chaînes de bits de plus de 8 octets, les octets suivants seront ignorés.

SNMP walk vers JSON

Convertit les valeurs SNMP en JSON.

Spécifiez un nom de champ dans le JSON et le chemin OID SNMP correspondant. Les valeurs des champs seront renseignées avec les valeurs du chemin OID SNMP spécifié.

Commentaires :

• Des options de formatage des valeurs similaires à celles de l'étape Valeur SNMP walk sont disponibles ;
  
• Vous pouvez utiliser cette étape de prétraitement pour la découverte des OID SNMP.

Valeur obtenue via SNMP

Appliquer les options de formatage à la valeur obtenue via SNMP :

• UTF-8 depuis Hex-STRING - convertir la chaîne hexadécimale en chaîne UTF-8 ;
  
• MAC depuis Hex-STRING - valider la chaîne hexadécimale comme adresse MAC et renvoyer une chaîne d'adresse MAC correcte (où les ' ' sont remplacés par des ':') ;
  
• Entier depuis BITS - convertir les 8 premiers octets d'une chaîne de bits exprimée sous forme de séquence de caractères hexadécimaux (par exemple, "1A 2B 3C 4D") en un entier non signé de 64 bits. Dans les chaînes de bits de plus de 8 octets, les octets suivants seront ignorés.

Multiplicateur personnalisé

Multiplie la valeur par la valeur entière ou à virgule flottante spécifiée.

Commentaires :

• Utilisez cette option pour convertir les valeurs reçues en Ko, Mo/s, etc., en o, o/s. Sinon, Zabbix ne peut pas définir correctement les préfixes (K, M, G, etc.).
  
• Notez que si le type d'information de l'élément est Numérique (non signé), les valeurs entrantes comportant une partie fractionnaire seront tronquées (c'est-à-dire que « 0.9 » deviendra « 0 ») avant l'application du multiplicateur personnalisé ;
  
• Si vous utilisez un multiplicateur personnalisé ou stockez la valeur en tant que Variation par seconde pour des éléments dont le type d'information est défini sur Numérique (non signé) et que la valeur calculée résultante est en réalité un nombre à virgule flottante, la valeur calculée est tout de même acceptée comme correcte : sa partie décimale est supprimée et la valeur est stockée sous forme d'entier ;
  
• Formats pris en charge : notation scientifique, par exemple 1e+70 ; macros utilisateur et macros LLD ; chaînes contenant des macros, par exemple {#MACRO}e+10, {$MACRO1}e+{$MACRO2}. Les macros doivent être résolues en un nombre entier ou à virgule flottante.

Modification simple

Calcule la différence entre la valeur actuelle et la valeur précédente.

Commentaires :

• Cette étape peut être utile pour mesurer une valeur qui augmente constamment ;
  
• Évaluée comme value-prev_value, où value correspond à la valeur actuelle et prev_value à la valeur reçue précédemment ;
  
• Une seule opération de modification par élément (« Modification simple » ou « Modification par seconde ») est autorisée ;
• Si la valeur actuelle est inférieure à la valeur précédente, Zabbix ignore cette différence (ne stocke rien) et attend une autre valeur.

Variation par seconde

Calcule la vitesse de variation de la valeur par seconde (différence entre la valeur actuelle et la valeur précédente).

Commentaires :

• Cette étape est utile pour calculer la vitesse par seconde d'une valeur qui augmente constamment ;
  
• Comme ce calcul peut produire des nombres à virgule flottante, il est recommandé de définir le « Type d'information » sur Numérique (flottant), même si les valeurs brutes reçues sont des entiers. Cela est particulièrement pertinent pour les petits nombres dont la partie décimale est importante. Si les valeurs à virgule flottante sont grandes et peuvent dépasser la longueur du champ « float », auquel cas la valeur entière risque d'être perdue, il est en fait recommandé d'utiliser Numérique (non signé) et de supprimer ainsi uniquement la partie décimale.
  
• Évalué comme (value-prev_value)/(time-prev_time), où value correspond à la valeur actuelle ; prev_value à la valeur reçue précédemment ; time à l'horodatage actuel ; prev_time à l'horodatage de la valeur précédente ;
  
• Une seule opération de variation par élément (« Variation simple » ou « Variation par seconde ») est autorisée ;
• Si la valeur actuelle est inférieure à la valeur précédente, Zabbix ignore cette différence (ne stocke rien) et attend une autre valeur. Cela permet notamment de fonctionner correctement avec le bouclage (dépassement) des compteurs SNMP 32 bits.

Booléen en décimal

Convertit la valeur du format booléen au format décimal.

Commentaires :

• La représentation textuelle est convertie en 0 ou 1. Ainsi, « TRUE » est stocké sous la forme 1 et « FALSE » sous la forme 0. Toutes les valeurs sont comparées sans tenir compte de la casse. Les valeurs actuellement reconnues sont, pour TRUE : true, t, yes, y, on, up, running, enabled, available, ok, master ; pour FALSE : false, f, no, n, off, down, unused, disabled, unavailable, err, slave. De plus, toute valeur numérique non nulle est considérée comme TRUE et zéro comme FALSE.

Octal en décimal

Convertit la valeur du format octal au format décimal.

Hexadécimal en décimal

Convertit la valeur du format hexadécimal au format décimal.

JavaScript

Saisissez le code JavaScript dans l’éditeur modal qui s’ouvre lorsque vous cliquez dans le champ du paramètre ou sur l’icône en forme de crayon à côté.

Commentaires :

• La longueur disponible pour le code JavaScript dépend de la base de données utilisée ;
  
• Pour plus d’informations, voir : Prétraitement JavaScript.

Dans la plage

Définissez une plage dans laquelle une valeur doit se trouver en spécifiant les valeurs minimale et maximale (incluses).

Commentaires :

• Les valeurs numériques sont acceptées (y compris un nombre quelconque de chiffres, une partie décimale facultative et une partie exponentielle facultative, ainsi que les valeurs négatives) ;
  
• La valeur minimale doit être inférieure à la valeur maximale ;
  
• Au moins une valeur doit être présente ;
  
• Les macros utilisateur et les macros de découverte de bas niveau peuvent être utilisées.

Correspond à l'expression régulière

Spécifiez une expression régulière à laquelle une valeur doit correspondre.

Ne correspond pas à l'expression régulière

Spécifiez une expression régulière à laquelle une valeur ne doit pas correspondre.

Vérifier la présence d'une erreur dans le JSON

Vérifier la présence d'un message d'erreur au niveau de l'application situé à l'emplacement JSONPath. Arrêter le traitement si l'opération réussit et que le message n'est pas vide ; sinon, continuer le traitement avec la valeur qui précédait cette étape de prétraitement.

Commentaires :

• Ces erreurs de service externe sont signalées à l'utilisateur telles quelles, sans ajouter d'informations sur l'étape de prétraitement ;
  
• Aucune erreur ne sera signalée en cas d'échec de l'analyse d'un JSON non valide.

Vérifier la présence d'une erreur dans le XML

Vérifie la présence d'un message d'erreur au niveau de l'application situé à l'emplacement XPath. Arrête le traitement si l'opération réussit et que le message n'est pas vide ; sinon, poursuit le traitement avec la valeur qui précédait cette étape de prétraitement.

Commentaires :

• Ces erreurs de service externe sont signalées à l'utilisateur telles quelles, sans ajouter d'informations sur l'étape de prétraitement ;
  
• Aucune erreur ne sera signalée en cas d'échec de l'analyse d'un XML non valide.

Vérifier une erreur à l’aide d’une expression régulière

Vérifier la présence d’un message d’erreur au niveau de l’application à l’aide d’une expression régulière. Arrêter le traitement si la vérification réussit et que le message n’est pas vide ; sinon, poursuivre le traitement avec la valeur qui précédait cette étape de prétraitement.

Paramètres :

• pattern - l’expression régulière ;
  
• output - le modèle de formatage de la sortie. Une séquence d’échappement \N (où N=1…9) est remplacée par le Nᵉ groupe correspondant. Une séquence d’échappement \0 est remplacée par le texte correspondant.

Commentaires :

• Ces erreurs de service externe sont signalées à l’utilisateur telles quelles, sans ajouter d’informations sur l’étape de prétraitement.

Vérifier la valeur non prise en charge

Vérifiez si aucune valeur d'élément n'a pu être récupérée. Indiquez comment l'échec doit être traité, en fonction de l'inspection du message d'erreur renvoyé.

Paramètres :

• scope - sélectionnez la portée du traitement de l'erreur :
  any error - toute erreur ;
  error matches - uniquement l'erreur qui correspond à l'expression régulière spécifiée dans pattern ;
  error does not match - uniquement l'erreur qui ne correspond pas à l'expression régulière spécifiée dans pattern
  
• pattern - l'expression régulière à utiliser pour rechercher une correspondance avec l'erreur. Si any error est sélectionné dans le paramètre de portée, ce champ n'est pas affiché. Lorsqu'il est affiché, ce champ est obligatoire.
  

Commentaires :

• Normalement, l'absence d'une valeur ou l'échec de sa récupération entraîne le passage de l'élément à l'état non pris en charge. Cette étape de prétraitement vous permet de modifier ce comportement.
• Cette étape de prétraitement vérifie uniquement si aucune valeur d'élément n'a pu être récupérée. Elle ne vérifie pas, par exemple, si le type de la valeur récupérée (par exemple, une chaîne) correspond au type d'information de l'élément (par exemple, numérique) ; pour plus de détails, consultez Exemples de prétraitement. En cas de non-correspondance des types, l'élément peut tout de même passer à l'état non pris en charge après l'exécution de toutes les étapes de prétraitement. Pour vérifier une non-correspondance des types, vous pouvez utiliser, par exemple, l'étape de prétraitement Custom multiplier ; consultez Exemples de prétraitement.
• La capture des groupes d'expressions régulières est prise en charge dans les champs Set value to ou Set error to. Utilisez \N (où N=1…9) pour récupérer le Nième groupe correspondant ; utilisez \0 pour récupérer le texte correspondant ;
• Ces étapes sont toujours exécutées en premier parmi les étapes de prétraitement et sont placées au-dessus de toutes les autres après l'enregistrement des modifications apportées à l'élément ;
• Plusieurs étapes Check for not supported value sont prises en charge, dans l'ordre spécifié. Une étape any error est automatiquement placée en dernière position dans ce groupe.

Ignorer les valeurs inchangées

Ignorer une valeur si elle n’a pas changé.

Commentaires :

• Si une valeur est ignorée, elle n’est pas enregistrée dans la base de données et le serveur Zabbix n’a aucune connaissance de la réception de cette valeur. Aucune expression de déclencheur ne sera évaluée ; par conséquent, aucun problème pour les déclencheurs associés ne sera créé/résolu. Les fonctions ne fonctionneront qu’en se basant sur les données réellement enregistrées dans la base de données. Comme les tendances sont construites à partir des données de la base de données, si aucune valeur n’est enregistrée pendant une heure, il n’y aura pas non plus de données de tendances pour cette heure.
  
• Une seule option de limitation peut être spécifiée par élément.

Ignorer les valeurs inchangées avec battement de cœur

Ignorer une valeur si elle n’a pas changé pendant la période définie (en secondes).

Commentaires :

• Les valeurs entières positives sont prises en charge pour spécifier le nombre de secondes (minimum : 1 seconde) ;
  
• Les suffixes de temps peuvent être utilisés (par exemple, 30s, 1m, 2h, 1d) ;
  
• Les macros utilisateur et les macros de découverte de bas niveau peuvent être utilisées ;
  
• Si une valeur est ignorée, elle n’est pas enregistrée dans la base de données et le serveur Zabbix n’a pas connaissance de la réception de cette valeur. Aucune expression de déclencheur ne sera évaluée ; par conséquent, aucun problème ne sera créé ou résolu pour les déclencheurs associés. Les fonctions fonctionneront uniquement à partir des données effectivement enregistrées dans la base de données. Comme les tendances sont générées à partir des données de la base de données, si aucune valeur n’est enregistrée pendant une heure, aucune donnée de tendance ne sera disponible pour cette heure.
  
• Une seule option de limitation peut être spécifiée par élément.

Modèle Prometheus

Utilisez la requête suivante pour extraire les données requises à partir des métriques Prometheus.

Consultez Vérifications Prometheus pour plus de détails.

Prometheus vers JSON

Convertissez les métriques Prometheus requises en JSON.

Voir Vérifications Prometheus pour plus de détails.

Prise en charge des macros

Les macros utilisateur et les macros utilisateur avec contexte sont prises en charge dans :

• les paramètres des étapes de prétraitement, y compris le code JavaScript ;
• les paramètres personnalisés de gestion des erreurs (champs Définir la valeur sur et Définir l’erreur sur).

Test

Voir le test du prétraitement.