Préambule 

Shinken est en ensemble de démons travaillant de manière autonome pour collecter les statuts des équipements supervisés. Mais dans certain cas, Shinken ne peut pas accéder aux équipements.

Le receiver permet alors de recevoir des messages de l’extérieur et de les transmettre aux démons concernés.


Principe de fonctionnement des modules de receiver d'écoute avec workers

Le module receiver-module-generic-endpoint est un module qui est utile pour servir de base au développement des modules:

  • qui fonctionne accrocher sur un receiver
  • qui peut être utilisé de 2 manières différentes :
    • Avec plusieurs workers
      • Ceci correspond à une attente particulière car dans ce cas, chaque worker n'aura qu'une partie des éléments sélectionnés pour être géré par ce receiver
        Les éléments sont divisés a par égale entre les workers.
      • Ex d'utilisation: si vous voulez que votre module se connecte à un bus de données ( sens de connexion worker => bus ) et que la charge de récupération soit réparti entre plusieurs processus
    • Avec 1 seul worker 
      • Dans ce cas, tous les hôtes sont présents dans le module et ce dernier peut recevoir n'importe quel message de l’extérieur associé à un hôte en étant sûr qu'il sera traité.

Ce module applique un filtre sur les hôtes qui vont être autorisés à recevoir des messages de l'extérieur

  • Dans la configuration du module, vous allez définir un modèle d'hôte que vont devoir avoir les hôtes pour être présent dans le module.
  • A l'initialisation du module, ce dernier ne disposera que des hôtes avec ce modèle.

Enfin, pour chaque hôte reçus aura a dans sa définition des données 

Mise en place du module d'exemple

Etape 1: Choisir le nom de votre module

Il faut un nom pour votre module. Le nom doit respecter:

  • uniquement des caractères ascii
  • en terme de caractères spéciaux, seuls - ou _ sont supportés
  • pas d'espaces
  • tout en lower case

Dans cette documentation on le nommera NOMduMODULE

Nous suivons maintenant pour tout nouveau module la convention suivante:

NOMduDEMON_module_NOMduMODULE


Etape 2: Copier le module dans son répertoire

Le module est installé via deux actions:

  • on met son code en place dans /var/lib/shinken/modules
  • on met sa configuration en place dans /etc/shinken/modules

Il faut donc:

  • copier le répertoire module en tant que /var/lib/shinken/modules/NOMduMODULE
  • copier le fichier receiver-module-generic-endpoint.cfg en tant que /etc/shinken/modules/NOMduMODULE.cfg 

Etape 3: Renommer le contenu du module et sa configuration avec notre nouveau nom


Il est important de renommer TOUTES les parties du module, si votre module a encore des classes ayant le même nom que le module generic, alors il y aura des problème d'import du code par le daemon et le résultat sera incorrect.

Dans le code livré par défaut, le nom du module est MODULE_CODE_NAME.

  • Éditez /var/lib/shinken/modules/NOMduMODULE/module.py en changeant toutes les occurrences de ReceiverGenericEndpoint en NOMduMODULE.
  • Éditez /etc/shinken/modules/NOMduMODULE.cfg en changeant toutes les occurrences de receiver_module_generic_endpoint en NOMduMODULE

Déclarez le module sur votre receiver

Pour que le module s'active il faut:

  • redémarrer le receiver afin qu'il charge le nouveau code (module.py)
  • rajouter votre module dans votre receiver (typiquement /etc/shinken/receivers/receiver-master.cfg)

Important: il faut que le module soit configuré pour recevoir les données d'inventaires des hôtes/clusters que sous souhaitez gérer via ce receiver. Pour cela il faut utiliser les paramètres suivants:

  • elements_sharding_enabled
    • mettre à 1 pour activer l'envoi des données d'inventaires vers le receiver
  • elements_sharding_filter_by_template
    • mettre le nom d'un template d'hôte qui va filtrer les hôtes à envoyer au receiver
  • elements_sharding_add_data_of_templates
    • mettre le nom d'un ou plusieurs templates d'hôtes où seront pris les DATA à exporter dans l'inventaire des hôtes

Notes pour le développement de votre module

Il est important de bien lire les commentaires dans le code d'exemple avant toute modification.

Le code est divisés en deux parties:

  • La classe du module en lui même, qui va être chargée par le processus receiver
  • La classe du worker qui va fonctionner dans le processus du worker

Le code du module

Le code dans le module va être très limité, car la seule méthode que vous pouvez modifier/surcharger est get_raw_stats qui est utilisée pour les checks de supervision et le healthcheck.

Il est important de:

  • ne pas surcharger la méthode __init__ du module
  • ne pas surcharger d'autres méthodes de la classe module autre que get_raw_stats et want_brok
  • toujours laisser l'appel au super au sein de get_raw_stats et seulement rajouter vos propres données au résultat sans modifier celle existantes.
  • want_brok: vous pouvez le surcharger pour filtrer les broks qu'on ne souhaite pas envoyer au worker.
  • tous les imports doivent être fait depuis shinkensolutions.api et pas shinken directement car seul shinkensolutions.api est considéré comme une API stable entre les versions
    • NOTE: en version v02.07.04 cet espace n'étant pas disponible, les imports dans shinken sont fournis à la place mais devront être migré dès le passage en v02.08.01.


Le code dans le worker

Le code dans le worker est celui où sera votre code métier ainsi que votre boucle principale d'actions.

Ici encore certaines règles s'appliquent afin s'assurer une stabilité dans le temps:

  • ne pas surcharger la méthode __init__ de la classe worker
  • toujours laisser l'appel au super au sein de get_raw_stats et seulement rajouter vos propres données au résultat sans modifier celle existantes.
  • tous les imports doivent être fait depuis shinkensolutions.api et pas shinken directement car seul shinkensolutions.api est considéré comme une API stable entre les versions
    • NOTE: en version v02.07.06 cet espace n'étant pas disponible, les imports dans shinken sont fournis à la place mais devront être migrès dès le passage en v02.08.01.

Les méthodes que vous pouvez surcharger sont multiples.

Méthodes surchargeables concernant le fonctionnement global du worker:

  • init_worker_before_main: (init_worker en version v02.07.06) cette fonction vous permet de récupérer les paramètres de votre module dans le fichier .cfg sous forme de string comme propriétés de l'objet module_configuration. 
  • worker_main: (obligatoire) c'est la boucle principale de votre worker. Si elle s'arrêt, le worker s'arrête également et le module est mis en erreur.


    • ATTENTION: toutes les autres méthodes (exceptées init_worker_before_main qui est appelées avant le worker_main) sont faites dans des threads différents. Vous devez donc faire attention à l'accès concurrents de vos données.


  • get_raw_stats: vous pouvez la surcharger pour retourner les stats de votre module, qui seront récupérées par le get_raw_stats que vous avez surchargés dans la classe module.

Les méthodes concernant l'inventaires des hôtes:

  • callback__a_new_host_added: appelé avec l'uuid d'un hôte qui vient d'être rajouté
  • callback__a_host_updated: appelé avec l'uuid d'un hôte qui vent d'être modifié
  • callback__a_new_realm_added: appelé lorsqu'un royaume vient d'être fini d'être chargé 
    • et donc tous les appels des callback__a_new_host_added/callback__a_host_updated sont déjà effectués
  • callback__a_realm_updated: appelé lorsqu'un royaume vient d'être fini d'être mis à jour
    • et donc tous les appels des callback__a_new_host_added/callback__a_host_updated sont déjà effectués

Envoi des ordres/commandes vers shinken depuis le worker

Dans le worker il est possible actuellement d'effectuer les actions suivantes:

  • pousser un résultat vers les schedulers
  • créer une prise en compte d'un élément
  • créer une période de maintenance


Envoyer des retours de sondes

Pour pousser un résultat d'hôte/cluster vers les schedulers il faut créer un objet PROCESS_HOST_CHECK_RESULT avec comme arguments:

  • le nom de l'hôte
  • le code retour (0 ou 2 pour un hôte)
  • le texte de output

Pour pousser un résultat de check  vers les schedulers il faut créer un objet PROCESS_SERVICE_CHECK_RESULT avec comme arguments:

  • le nom de l'hôte
  • nom du check
  • le code retour (0 , 1, 2 ou 3 pour un check)
  • le texte de output

Prendre en compte une erreur:

Pour créer une prise en compte d'élément hôte/cluster il faut créer un objet ACKNOWLEDGE_HOST_PROBLEM:

  • le nom de l'hôte
  • le nombre 1
  • 1 ou 0 suivant si vous souhaitez qu'une notification soit envoyée
  • le nombre 1
  • le nom de l'auteur
  • un commentaire

Pour créer une prise en compte d'élément check il faut créer un objet ACKNOWLEDGE_SVC_PROBLEM:

  • le nom de l'hôte
  • le nom du check
  • le nombre 1
  • 1 ou 0 suivant si vous souhaitez qu'une notification soit envoyée
  • le nombre 1
  • le nom de l'auteur
  • un commentaire

Créer une période de maintenance:

Pour créer une période de maintenance d'élément hôte/cluster il faut créer un objet SCHEDULE_HOST_DOWNTIME:

  • le nom de l'hôte
  • le temps epoch du démarrage
  • le temps epoch de la fin
  • le chiffre 1
  • le chiffre 0
  • le chiffre 0
  • le nom de l'auteur
  • un commentaire

Pour créer une période de maintenance d'élément hôte/cluster il faut créer un objet SCHEDULE_SVC_DOWNTIME:

  • le nom de l'hôte
  • le nom du check
  • le temps epoch du démarrage
  • le temps epoch de la fin
  • le chiffre 1
  • le chiffre 0
  • le chiffre 0
  • le nom de l'auteur
  • un commentaire