Version: 23.04

Stream Connectors

Centreon Broker fournit un Stream Connector. Si vous ne trouvez pas de connecteur approprié parmi ceux proposés, ce Stream Connector répondra certainement à vos besoins. Son principe est d’exposer une partie de l’API Centreon Broker par le biais de l’interpréteur Lua et l’utilisateur n’a plus qu’à la remplir selon ses besoins.

Centreon Broker exposé

Voici le code Lua minimal acceptable pour fonctionner comme Stream Connector :

  function init(conf)
  end

  function write(d)
    return true
  end

Nous recommandons de placer les scripts Lua dans le répertoire /usr/share/centreon-broker/lua. S’il n’existe pas, nous pouvons le créer. Faites juste attention à ce que ce répertoire soit accessible à l’utilisateur centreon-broker. Si un Stream Connector est composé de plusieurs fichiers (un script principal et un module par exemple), vous pouvez les placer dans ce répertoire. Si une bibliothèque dynamique (fichier \*.so) est utilisée par un script Lua, placez-la dans le répertoire /usr/share/centreon-broker/lua/lib.

Lorsque Centreon Broker démarre, il initialise tous les connecteurs configurés. Pour le Stream Connector, il charge le script Lua, contrôle sa syntaxe et vérifie que les fonctions init() et write() existent.

Centreon Broker vérifie également si une fonction filter(category, element) existe.

Examinons ces fonctions. La fonction init est appelée lorsque le connecteur est initialisé. L’argument fourni à cette fonction est une table Lua contenant les informations données par l’utilisateur dans l’interface de configuration de l'output de Broker. Par exemple, si une adresse IP est fournie avec le nom address et la valeur 192.168.1.18, alors cette information sera accessible via conf["address"].

La fonction write() est appelée chaque fois qu’un événement est reçu d’un collecteur par le biais de Broker. Cet événement est configuré pour être envoyé à ce connecteur. Cette fonction a besoin d’un argument qui est l’événement traduit sous forme de table Lua.

La fonction write() doit retourner une valeur booléenne True si les événements sont traités et False dans le cas contraire.

Si cette fonction ne renvoie pas une valeur booléenne, Broker déclenche une erreur.

Le SDK Lua de Broker

Pour simplifier la vie du développeur Lua, plusieurs objets sont proposés et directement disponibles pour le script.

L’objet broker_log

broker_log:set_parameters(level, filename) permet à l’utilisateur de définir un niveau de journal et un nom de fichier. Le niveau est un nombre entier compris entre 1 et 3, du plus important au moins important. Le nom du fichier doit contenir le chemin d’accès complet. Et le fichier doit être accessible à centreon-broker. Si cette méthode n’est pas appelée, les journaux seront écrits dans les journaux de centreon Broker.
broker_log:info(level, content) écrit une information de journal si le niveau donné est inférieur ou égal à celui configuré. Le contenu est le texte à écrire dans les journaux.
broker_log:warning(level, content) fonctionne comme log_info mais écrit un avertissement.
broker_log:error(level, content) fonctionne comme log_info mais écrit une erreur.

Voici un exemple :

  function init(conf)
    -- Here, we allow all logs with level 3 and set the output to
    -- /tmp/test.log.
    broker_log:set_parameters(3, "/tmp/test.log")
  end

  function write(d)
    -- For each entry, we write the key and the value.
    for k,v in pairs(d) do
      broker_log:info(3, k .. " => " .. tostring(v))
    end
    return true
  end

Ici, lorsque la fonction init est exécutée, l’objet broker_log est paramétré avec un niveau max 3 et un fichier de sortie /tmp/test.log.

Ensuite, à chaque appel de write(), les événements reçus sont enregistrés comme des informations. Nous obtenons un résultat comme celui-ci :

  Fri Jan 26 08:31:49 2018: INFO: service_id => 21
  Fri Jan 26 08:31:49 2018: INFO: type => 0
  Fri Jan 26 08:31:49 2018: INFO: host_id => 13
  Fri Jan 26 08:31:49 2018: INFO: element => 1
  Fri Jan 26 08:31:49 2018: INFO: comment_data =>

Pour utiliser une méthode en Lua, le séparateur entre l’objet et la méthode est : ; broker_log est un objet puisqu’il contient des informations telles que le niveau maximum ou le fichier de destination.

Le socket TCP de Broker

Un socket TCP de base est disponible dans le SDK Broker. Voici un exemple simple :

  local socket = broker_tcp_socket.new()
  socket:connect("10.40.1.2", 9002)
  socket:write(message)
  answer = socket:read()
  socket:close()

Dans cet exemple, le premier appel est broker_tcp_socket.new(). Il crée un nouveau socket en appelant la fonction new() stockée dans la table broker_tcp_socket.
L’étape suivante est un appel à la méthode connect qui nécessite deux arguments : une chaîne indiquant une adresse IP ou un nom d’hôte auquel se connecter et le port à utiliser.
L’étape suivante est un appel à la méthode write qui écrit une chaîne dans le socket. L’appel de la méthode est terminé lorsque l’intégralité du message est envoyée.
La méthode read reçoit une chaîne comme résultat.
Lorsque l’utilisateur a fini d’utiliser le socket, il peut le fermer avec la méthode close().

Cet objet socket fournit également une méthode get_state() qui renvoie une chaîne de caractères :

unconnected : le socket n’est pas connecté
hostLookup: le socket effectue une recherche de nom d’hôte
connecting: le socket a commencé à établir une connexion
connected: une connexion est établie
closing: le socket est sur le point de se fermer (des données peuvent encore être en attente d’écriture).

La table broker

Plusieurs fonctions sont disponibles dans cette table. Ces fonctions ne sont pas des méthodes, broker est juste une table qui les contient. On peut trouver ici :

json_encode(object) qui convertit un objet Lua en json. Le json est retourné sous forme de chaîne par la fonction.
json_decode(json) qui convertit une chaîne json en objet Lua. L’objet est directement retourné par la méthode. Une deuxième valeur est également retournée. Elle n’est définie que lorsqu’une erreur s’est produite et contient une chaîne décrivant l’erreur.
parse_perfdata(str) qui prend comme argument une chaîne contenant des perfdata. Un deuxième argument booléen est disponible. Si sa valeur est true, la table retournée est plus grande et donne tous les détails sur les métriques ainsi que les seuils « warning » et « critical ». En cas de succès, il retourne une table contenant les valeurs récupérées à partir des perfdata. En cas d’échec, il renvoie un objet nil et une chaîne de description de l’erreur.
url_encode(text) qui convertit le texte de la chaîne de caractères en une chaîne encodée en URL.
stat(filename) qui appelle la fonction stat système sur le fichier. En cas de succès, nous obtenons une table contenant diverses informations sur le fichier (voir l’exemple ci-dessous). Sinon, cette table est nil et une deuxième valeur retournée est donnée et contient un message d’erreur.
md5(str) qui calcule le MD5 de la chaîne str et le renvoie sous forme de chaîne.
bbdo_version() qui renvoie la version BBDO configurée dans Centreon Broker.

  local obj = {
    a = 1,
    b = 2,
    c = { 'aa', 'bb', 'cc' }
  }
  local json = broker.json_encode(obj)
  print(json)

qui renvoie

  { "a": 1, "b": 2, "c": [ 'aa', 'bb', 'cc' ] }

Un deuxième exemple est le suivant :

  local json = { "a": 1, "b": 2, "c": [ 'aa', 'bb', 'cc' ] }
  local obj, err = broker.json_decode(json)

  for i,v in pairs(obj) do
    print(i .. " => " .. tostring(v))
  end