Concept

Ces règles permettent, lors de l'import, de mettre en relation un champ de l'API VMware avec une propriété ou une donnée de Shinken en fonction du type de l'élément ( hôte, modèle d'hôte, etc. ).

  • Elles s'appliquent pour tous les types d’éléments présents dans l'interface de Shinken.

Elles peuvent être visualisées depuis l'onglet "Mapping vers les propriétés et les données de Shinken" de l'interface de la source.



Définition des règles de mapping

Pour ajouter une règle utilisateur d'application des modèles, il faut éditer le chemin suivant : 

/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

/etc/shinken-user/source-data/source-data-synchronizer-collector-vmware/configuration/mapping/user_mapping_rules_vm.json
/etc/shinken-user/source-data/source-data-synchronizer-collector-vmware/configuration/mapping/user_mapping_rules_esx.json

Comme pour les règles d'application des modèles, les règles de mapping sont écrites au format JSON.

La source VMware ne concerne que les hôtes, donc les fichiers sources commenceront toujours par "hosts".

Elles doivent respecter le format suivant :

  • Nom du champ de l'API VMware : nom de la propriété ou de la donnée Shinken


Une propriété est une information nécessaire au moteur Shinken.

  • Pour définir dans le mapping une propriété Shinken, il faut utiliser le nom de la clé d'import de Shinken ( visible dans l'aide des pages d'édition des éléments ),
  • La clé d'import de l'UUID des éléments ( introuvable dans l'interface ) est "uuid"


Une donnée est une valeur qui va être ajoutée en complément des propriétés.

  • Pour définir dans le mapping une donnée Shinken :
    • Il est recommandé d'utiliser la syntaxe "DATA" : "DATA(NOM_DE_LA_DONNEE_SHINKEN)".
    • Il faut que le nom de la donnée Shinken :
      • soit en majuscules
      • ne commence pas par un underscore.
      • ne contienne que des lettres, des chiffres, un underscore ( _ ) ou un tiret ( - ).

    • Si la syntaxe utilisant DATA(...) est à privilégier ,
      • pour assurer la compatibilité ascendante, il est toujours possible de créer une donnée dans Shinken en lui donnant un nom en majuscules commençant par un underscore ( ex : _NOM_DONNEE_SHINKEN ) et en l'associant au champ récolté par la source.
      • Cette syntaxe est cependant DÉPRÉCIÉE .

Forcer la valeur des propriétés

Il est possible d’ajouter le suffixe [FORCE] ( sans espace ) à la clé d’import d'un élément Shinken afin de forcer la valeur associée ( voir la page Forcer la valeur des noms des éléments et des propriétés de type liste (comme la propriété des modèles hérités) ).

Exemple :


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

Lorsqu’une propriété est marquée avec [FORCE], elle est traitée de la manière suivante par le mélange des sources :

  • La valeur est considérée comme prioritaire par rapport aux autres sources.
  • Si une autre source importe le même objet avec une valeur différente, cette dernière est ignorée.
  • En cas de conflit entre plusieurs valeurs forcées, la priorité de la source détermine la valeur conservée.

Ajouter [FORCE] à une clé d'import contenant une liste ( comme la propriété "members" servant à définir les membres d'un groupe d'utilisateurs ) aura pour effet de remplacer complètement la liste des autres sources par celle fournie avec l'option [FORCE].

Liste des clés d'import pouvant être forcées

Exemple de mapping dans le fichier "user_mapping_rules_vm.json"

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

Il existe 5 règles de mapping définies :

Clé VMwareClé ShinkenDescription du mapping
namehost_nameLa valeur VMware "name" deviendra le nom de l'hôte ( propriété host_name ).
shinken.ipAddressaddressLa valeur VMware "shinken.ipAddress" sera prise en compte comme adresse pour l'hôte ( propriété address ).
shinken.machine_typeDATA(MACHINE_TYPE)La valeur VMware "shinken.machine_type" deviendra une donnée nommée MACHINE_TYPE sur l'hôte.
config.product.osTypeDATA(OS_TYPE)La valeur VMware "config.product.osType" deviendra une donnée nommée OS_TYPE sur l'hôte.
shinken.tagsDATA(TAGS)

La valeur VMware "shinken.tags" deviendra une donnée nommée TAGS sur l'hôte. Vu que la valeur de shinken.tags est une liste dans l'API de VMware, la valeur de la donnée TAGS vaudra la liste des tags séparés par des virgules.

Exemple : La valeur de shinken.tags ['Linux','Bordeaux','France'] deviendra la valeur Linux,Bordeaux,France dans TAGS.

  • Il est possible d'ajouter des commentaires dans ce fichier.
    Toutes les lignes qui commencent par le caractère # seront considérées comme des commentaires.

  • La clé d'import Shinken n'est pas le nom affiché dans les pages des éléments, mais le nom de la propriété lors de l'import dans Shinken.
    Pour trouver le nom d'import d'une propriété, il est possible d'ouvrir l'aide d'une propriété dans une page d'édition d'un élément ( voir la page Éditer les Eléments ( hôte, clusters, checks, utilisateurs ... ) ( paragraphe "Informations contextuelles" ) ).

  • Retrouvez la liste complète des champs VMware collectés par la source sur la page Liste des champs collectés auprès des VCenters ou ESXis .

  • Les listes de l'API de VMware ( Par exemple : shinken.tags, shinken.tag_categories ) sont transformées en listes exploitables par Shinken.
    • Exemple : La valeur ['Linux','Bordeaux','France'] deviendra Linux,Bordeaux,France.

La propriété Shinken _SE_UUID ne peut pas être mappée.

Opérateurs pour les règles de mapping

Les opérateurs des règles de mapping permettent de transformer les données collectées afin de les adapter au format de Shinken et aux besoins de la supervision.

Opérateur VALUES pour les listes

La source VMware peut fournir des champs dont les valeurs sont des listes ( par exemple le champ "shinken.tags" ).

Pour faire correspondre une valeur de liste dans un champ de Shinken, il est possible d'utiliser l'opérateur : "VALUES".

Une VM possède la liste de tags suivants : LINUX, FR, DATACENTER_42

Le mapping suivant :

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

va permettre de créer un hôte avec comme données :

_MACHINE_TYPE LINUX
_DATACENTER   DATACENTER_42
  • MACHINE_TYPE contient la première valeur ( indice 0 ) de la liste.
  • DATACENTER se voit affecter les valeurs qui contiennent au moins DATACENTER.
Définition de l'utilisation de VALUES

La syntaxe de la condition dans "VALUES(condition)" est la suivante :

SignificationSyntaxeDescriptionExemple
Indexnombre

Récupère l'élément à l'index indiqué. L’index doit être un nombre appartenant à l’ensemble des entiers naturels, incluant 0.

Cette règle admet une seule exception afin de rendre possible le choix du dernier élément d’une liste, en utilisant l’index -1.

L’index 0 récupérera le premier élément de la liste, 1 le deuxième, 2 le troisième, etc.

VALUES(0)

Contient= texte La condition signifie que l'élément choisi doit CONTENIR le texte.

VALUES(=PROD)

Commence par=^ texte Si l'expression commence par le caractère "^", la condition signifie que l'élément choisi doit COMMENCER par le texte.

VALUES(=^PROD)

Termine par= texte $ Si l'expression se termine par le caractère "$", la condition signifie que l'élément choisi doit TERMINER par le texte.

VALUES(=PROD$)

Est strictement égal= ^ texte $ Si l'expression commence par "^" ET se termine par "$", la condition signifie que l'élément choisi doit être l'expression EXACTE.

VALUES(=^PROD$)

Inversion= !^ texte $

Ajouter un " ! " avant une autre expression provoque l'effet inverse de celle-ci :

• = ! texte --> L'élément choisi ne contient pas "texte"

• = ! ^ texte --> L'élément choisi ne commence pas par "texte"

• = ! texte $ --> L'élément choisi ne se termine pas par "texte"

• = !^ texte $ --> L'élément choisi n'est pas strictement égal à "texte"

VALUES(=!PROD)

  • Si aucun élément ne correspond à la condition, la donnée ne sera pas créée pour l’hôte.
  • Si plusieurs éléments correspondent à la condition ( par exemple avec VALUES(=DATACENTER) ), la donnée Shinken vaudra la liste des éléments trouvés séparés par une virgule.

Opérateur TRANSFORM pour les modifications de valeurs

L'opérateur TRANSFORM permet de modifier la valeur d'un champ VMware lors du mapping.

Son utilisation se fait avec la syntaxe suivante : champ_vmware>TRANSFORM(valeur_initiale=>nouvelle_valeur)

Une VM possède la donnée "config.product.osType" avec la valeur "linuxGuest". On souhaite que dans Shinken, cette donnée vaille "Linux".

Le mapping suivant :

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

va permettre de créer un hôte avec comme donnée : _OS_TYPE Linux

  • Il est possible de mettre plusieurs transformations dans un même opérateur en les séparant par des virgules :
    TRANSFORM(linuxGuest=>Linux, windowsGuest=>Windows)

  • Si la valeur VMware ne correspond à aucune transformation, la valeur initiale est conservée.

  • L'opérateur TRANSFORM peut être utilisé à la suite de l'opérateur VALUES :
    shinken.tags>VALUES(0)>TRANSFORM(linux=>Linux)

Opérateur CONCAT pour concaténer des champs

L'opérateur CONCAT permet de fusionner plusieurs champs VMware ou du texte fixe dans une seule propriété ou donnée Shinken.

Syntaxe : CONCAT(champ1, " texte ", champ2)

Surcharger une règle de mapping par défaut

Il est possible de surcharger les règles de mapping définies par défaut par l'application ( ex : le nom de l'hôte, son adresse IP, etc. ).

Pour cela, il suffit de créer, dans l'un des fichiers de mapping utilisateur ( 1 ), une règle possédant la même clé que celle à surcharger ( 5 ).

Avant :



Après :