Page History

/etc/shinken-user/source-data/source-data-[nom de la source]/configuration/mapping/user_mapping_rules_vm.json
/etc/shinken-user/source-data/source-data-[nom de la source]/configuration/mapping/user_mapping_rules_esx.json

{
  "hosts": {
    "name": "host_name[FORCE]",
    "shinken.ipAddress" : "address"
  }
}

{
  "hosts": {
    "name": "host_name",
    "shinken.ipAddress" : "address",
    "shinken.machine_type": "DATA(MACHINE_TYPE)",
    "config.product.osType": "DATA(OS_TYPE)",
	    "shinken.tags": "DATA(TAGS)",
  }
}

{
  "hosts": {
       "shinken.tags>VALUES(0)": "DATA(MACHINE_TYPE)",
      "shinken.tags>VALUES(=DATACENTER)": "DATA(DATACENTER)", 
   }
}

_MACHINE_TYPE LINUX
_DATACENTER    DATACENTER_42

Grâce à l'opérateur TRANSFORM il est possible de transformer du texte.

• Exemple : L'API VMWare fournie la valeur "Préproduction" et l'on veut transformer cette valeur en "PREPROD" à la place.

La syntaxe de TRANSFORM est la suivante :

TRANSFORM(transformation1,transformation2,transformation3)

• TRANSFORM permet d'indiquer plusieurs transformations, ces dernières sont séparées par des virgules.
• Attention à ne pas mettre d'espace avant ou après une virgule, autrement, il sera pris en compte dans la transformation.
• Il n'y a actuellement pas de limite sur le nombre de transformations autorisées.

Pour écrire une transformation, il faut séparer le texte à transformer par "=>" du texte désiré ( désigné ci-après par le mot "séparateur" ) : TEXTE1=>TEXTE2

Voici un exemple de syntaxe avec 2 transformations :

TRANSFORM(BORDEAUX=>BDX,PARIS=>PAR)

TRANSFORM permet également de supprimer du texte en laissant vide la partie à droite du séparateur ( => ) censée contenir la modification à apporter au texte.

TRANSFORM(DEAUX=>,IS=>)

Exemple avec une machine possédant les tags suivants :

• Production_Bordeaux
• Production_Paris

Et le mapping suivant :

{
  "hosts": {
     "shinken.tags_by_category.ENV>VALUES(=Bordeaux)>TRANSFORM(Production=>Prod,Bordeaux=>bdx)": "DATA(TRANSFORM_OPERATION)",
  }
}

La donnée TRANSFORM_OPERATION contiendra donc la valeur suivante :

• Prod_bdx

Lorsque l'opérateur TRANSFORM est appelé sur une liste de valeurs ( Exemple : shinken.tags ), il va appliquer la ou les transformations demandées sur chaque élément de la liste individuellement.

Exemple avec une machine possédant les balises ( tags ) suivantes :

• CentOS
• Alma
• macOS

• Production_Bordeaux
• Preproduction_Bordeaux

Et le mapping suivant :

{
  "hosts": {
     "shinken.tags_by_category.ENV>VALUES(=production)>TRANSFORM(Production=>Prod,Preproduction=>Preprod,Bordeaux=>bdx)": "DATA(TRANSFORM_OPERATION)",
  }
}

La donnée TRANSFORM_OPERATION contiendra donc les valeurs suivantes :

• Prod_bdx,Preprod_bdx

Maintenant, si l'on veut modifier chacun des tags de la catégorie "OS" pour le faire précéder de "OS_" :

• CentOS deviendrait OS_CentOS.
• Alma deviendrait OS_Alma.
• macOS deviendrait OS_macOS.

Dans ce cas, il faut employer $CURRENT$, ce mot-clé prendra la valeur de la balise en train d'être modifiée.

La règle de mapping pour effectuer cette opération est la suivante :

"shinken.tags_by_category.OS>TRANSFORM($CURRENT$=>OS_$CURRENT$)": "DATA(TRANSFORMED_OS)"

Il est possible de concaténer plusieurs valeurs de l'API VMWare pour former la valeur d'une propriété d'un élément de Shinken. Cela est possible grâce à l'opérateur : CONCAT.

Exemple : Une VM possédant les listes de tags suivantes :

Et les informations doivent être affichées de la manière suivante dans la donnée nommée _MACHINE_INFOS : "Production - Linux - Bordeaux"

La syntaxe se fera de la manière suivante dans le fichier de Mapping.

{
  "hosts": {
     "CONCAT($shinken.tags.OS>VALUES(0)$ - $shinken.tags.ENV>VALUES(0)$ - $shinken.tags.LOCATION>VALUES(0)$)": "DATA(MACHINE_INFOS)", 
   }
}

L'opérateur CONCAT peut aussi récupérer les valeurs de n'importe quel nom de champ.

Exemple : Avec le fichier de configuration de la source VMWare suivant :

{
  "hosts": {
    "name": "host_name",
    "shinken.ipAddress" : "address"
    "shinken.machine_type": "DATA(MACHINE_TYPE)",
    "CONCAT($name$ - $shinken.ipAddress$)": "DATA(MACHINE_INFOS)",
  }
}

et les valeurs :

• "name" valant : "Ubuntu-Preprod"
• "shinken.ipAddress" valant : "192.168.1.42"

La donnée MACHINE_INFOS vaudra : "Ubuntu-Preprod - 192.168.1.42"

Si un champ est vide, alors CONCAT ne fournira pas de valeur pour ce champ.

Exemple, avec les mêmes données que l'exemple précédent, sauf que "name" n'a aucune valeur, la donnée MACHINE_INFOS vaudra : "  - 192.168.1.42"

Comme pour l'opérateur TRANSFORM évoqué plus haut, il est également possible d'appliquer une opération de concaténation sur une liste, à l'aide de l'opérateur CONCAT_ON_ALL.

De la même manière que lorsque l'opération TRANSFORM est appliquée sur une liste, il est possible d'utiliser $VALUE$ avec CONCAT_ON_ALL pour récupérer la valeur de l'élément sur lequel l'opération est en train d'être effectuée.

Exemple :

Une VM possédant les listes de tags suivantes :

• Alma
• CentOS

Et le fichier de mapping suivant :

{
  "hosts": {
    "name": "host_name",
    "shinken.ipAddress" : "address"
    "shinken.machine_type": "DATA(MACHINE_TYPE)",
  }
}

Si on l'on souhaite associer le nom de la machine à chaque OS et le mettre dans une donnée spécifique ( ex MACHINE_OS ), on peut ajouter la règle suivante au fichier de mapping :

"shinken.tags_by_category.OS>CONCAT_ON_ALL($name$ has OS: $CURRENT$)": "DATA(MACHINE_OS)"

Cela génèrera une liste d'éléments qui sera présente dans la data "_MACHINE_OS" :

MyHost has OS Alma,MyHost has OS CentOS

Il n'est actuellement pas possible d'utiliser le CONCAT_ON_ALL dans les autres opérateurs, mais cela sera possible dans une prochaine version.

"CONCAT($shinken.tags_by_category.ENV>CONCAT_ON_ALL($name$ has tag  $CURRENT$)$)": "DATA(CONCAT_ON_ALL_IN_ANOTHER_RULE)"

Ne fonctionne pas

{
  "hosts": {
     "config.product.osType>TRANSFORM(linuxGuest=>Linux)": "DATA(OS_TYPE)"
   }
}

L'opérateur MANY_FIELDS_BY_REGEX permet de mapper plusieurs champs récoltés par la source à importer dans Shinken à l'aide d'une expression régulière en une seule règle.

Couramment, le mapping entre les champs récoltés par la source et les propriétés de Shinken est exhaustif. Cependant, lors de la récupération des données, il est possible d'avoir un grand nombre de champs différents à importer dans Shinken.

Dans ce cas, le fonctionnement habituel ne suffit plus, c'est pour cela que les règles de mapping peuvent désormais faire appel à des expressions régulières.

Une expression régulière est une formule qui sert à rechercher ou reconnaître des motifs dans du texte.

Par exemple :

• Trouver toutes les clés qui commencent par "EXTRAINFO-" et qui sont en deux parties séparées par un tiret ( - ).
  • ( Pour une aide à propos des expressions régulières, voir la page : Guide des expressions régulières )

Pour les utiliser dans le mapping, il faut les écrire sous le format suivant dans la colonne "Propriétés dans Excel" :

MANY_FIELDS_BY_REGEX(EXPRESSION)

où "EXPRESSION" est l'expression régulière.

Il est possible de récupérer les groupes matchés dans l'expression régulière ( voir la page suivante pour une aide sur les groupes dans les expressions régulières :  Guide des expressions régulières - groupe ) pour construire le nom de la donnée dans Shinken. Pour ce faire, il faut utiliser "$" suivi du numéro du regroupement ( $1, $2, $3, etc. )

{
  "hosts": {
     "MANY_FIELDS_BY_REGEX(runtime\\.([0-9A-Za-z_]+))": "DATA(RUNTIME_$1)",
  }
}

Avec cette expression régulière, la valeur de toutes les colonnes dont le nom :

• $1 correspond à la partie capturée par les premières parenthèses.

Les mappings peuvent être surchargés en créant un mapping avec le nom de la clé que l'on veut désactiver.

• Pour le champ en question, au lieu de choisir une propriété Shinken ( ou donnée ), il faut utiliser le mot-clé "disable "

{
  "hosts":{
    "shinken.machine_type" : "disable",
    "config.product.fullName" : "display_name"
  }
}

Pour visualiser la liste des mapping définie pour cette source, il faut se rendre dans l'onglet "Mapping vers les propriétés de Shinken". 

Dans cet onglet, se trouve le chemin des fichiers de définition des règles mapping des utilisateurs pour l'ESXi et les Machines virtuelles du serveur ESXi ( 1 ). 

 Un message d'avertissement apparaîtra si un des fichiers n'existe pas.

Dans l'entête de la liste, se trouve également le bouton de rafraîchissement de la liste des mappings ( 2 ).

• Ce bouton permet de rafraîchir la liste des mappings sans devoir redémarrer le Synchronizer.
• Il faudra relancer un import pour réappliquer les nouveaux mapping sur les éléments importés.

Image Removed

La liste des mappings ( 3 ) comporte à la fois les mappings définis par l'utilisateur ( ligne bleue ) et les mappings par défaut ( ligne grise ).

La liste affiche pour chaque mapping une série de colonnes :

Certaines des règles de mapping définies par "Défaut" ont une valeur définie dans les champs "Clé de la source" et la "Description", mais aucune valeur dans les champs " Clé Shinken" et " Nom de propriété dans l'interface ".

• Cela signifie que ces mappings ne seront liés à aucune propriété Shinken.
• Elles sont volontairement listées ici pour être vus, et faciliter la création de son propre mapping ( afin de ne pas partir d'une feuille blanche ).

Ces mappings peuvent être surchargés dans l'un des fichiers de mapping utilisateur ( 1 ).