Page History

Description

Le module broker-module-livedata permet de mettre à disposition sur le Broker une API HTTP permettant d'accéder aux informations d'un hôte, d'un cluster ou d'un check.

Cette API peut être utilisée pour accéder rapidement aux informations d'éléments supervisés pour ensuite les intégrer dans des outils externes ( outil de ticketing, récolte de données, etc... ).

Activation du module

Le module broker-module-livedata est un module qui peut être activé seulement sur un démon Broker.

L'activation du module s'effectue en ajoutant le module dans le fichier de configuration du Broker concerné.

Pour ce faire,

ouvrer le fichier de configuration de votre Broker à l'

emplacement /etc/shinken/brokers/nom_

du_

broker.

cfg, et ajouter le nom de votre module de type "broker-module-livedata"

Configuration

La configuration du module se trouve par défaut dans le fichier suivant: /etc/shinken/modules/broker-module-livedata.cfg

Configuration de l'interface et du port d'écoute

Par défaut, le port de l'API rendue disponible par le module "broker-module-livedata" est 50100. Ce port peut être changé via le paramètre "port" dans le fichier de configuration du module: /etc/shinken/modules/broker-module-livedata.cfg.

En plus du port, il est également possible de configurer l'interface réseau sur laquelle est mise à disposition l'API. Si par exemple l'API ne doit être accessible seulement via un réseau local, il est possible de n'écouter les requêtes que sur cette interface réseau.

Cette modification de configuration se fait via le paramètre "host" du fichier de configuration du module: /etc/shinken/modules/broker-module-livedata.cfg. Dans l'exemple suivant, l'API ne sera disponible que sur l'interface avec l'adresse 192.168.1.27:Exemple: par défaut, nous livrons un module dont le nom est "broker-module-livedata":

define modulebroker {
    [...]
    hostmodules                      192.168.1.27
    [...]
}

L'API du module est par défaut mise à disposition sur toutes les interfaces: le paramètre "host" est à 0.0.0.0

Pour prendre en compte le changement de configuration, il faut ensuite redémarrer l'Arbiter:

service shinken-arbiter restart

Activation du SSL

L'API du module est accessible via HTTP. Si pour des raisons de sécurité, cette API doit être accessible via HTTPS, il faut passer le paramètre "use_ssl" à 1 dans le fichier de configuration du module:

define module {
    [...]
    # HTTPs part, enable if you want to set the visualisation interface listen in HTTPs mode
    # disabled by default. Set your own certificates. Set your own token, it is usefull to get access to the API
    use_ssl                   1
    ssl_cert                  /etc/shinken/certs/server.cert
    ssl_key                   /etc/shinken/certs/server.key


    Simple-log, WebUI, Graphite-Perfdata, sla, broker-module-livedata
    [...]
}

Pour prendre en compte le changement de configuration, il faut ensuite redémarrer l'Arbiter:

service shinken-arbiter restart

Authentification

Utilisation

Les routes suivantes sont mises à disposition par l'API. Chaque appel doit contenir dans ses paramètres le token d'identification décrit dans la section précédente.

GET /api/v1/all-monitored-elements

Cet appel permet de recevoir la liste des uuids de tous les hôtes et clusters ainsi que de leurs checks.

Réponse

Codes de retour

Retour du code 200

• hosts : 
  • host_uuid : text
  • checks :
    • check_uuid : text
• clusters :
  • cluster_uuid : text
  • checks :
    • check_uuid : text

Exemple

GET /api/v1/host

Cet appel permet de recevoir la liste des uuids de tous les hôtes ainsi que de leurs checks.

Réponse

Codes de retour

Retour du code 200

• hosts : 
  • host_uuid : text
  • checks :
    • check_uuid : text

Exemple

GET /api/v1/host/{uuid}

Cet appel permet de recevoir des informations sur un hôte.

Paramètres

Réponse

Codes de retour

Retour du code 200

• host_uuid : text
• host_name : text
• host_display_name : text
• status : text
  • OK
  • WARNING
  • CRITICAL
  • UNKNOWN
  • MISSING-DATA
  • SHINKEN-INACTIVE
• status_since : epoch (en secondes)
• context : text
  • NOTHING
  • ACKNOWLEDGED
  • PARTIAL-ACKNOWLEDGED
  • INHERITED-ACKNOWLEDGED
  • DOWNTIME
  • PARTIAL-DOWNTIME
  • INHERITED-DOWNTIME
  • FLAPPING
  • PARTIAL-FLAPPING
  • DISABLED

• business_impact : 0, 1, 2, 3, 4, 5

• output : text

• long_output : text

• raw_perf_data : text, version texte de perf_data
• perf_data : liste de métriques au format :
  • value : number
  • uom : Unit Of Mesure / Unité de mesure
  • warning : valeur d'alerte
  • critical : valeur d'alerte critique
  • min : valeur minimale possible
  • max : valeur maximale possible

Exemple

GET /api/v1/check-on-host/{uuid}

Cet appel permet de recevoir des informations sur un check attaché à un hôte.

Paramètres

Réponse

Codes de retour

Retour du code 200

• check_uuid : text
• check_name : text
• check_display_name : text
• status : text
  • OK
  • WARNING
  • CRITICAL
  • UNKNOWN
  • MISSING-DATA
  • SHINKEN-INACTIVE
• status_since : epoch (en secondes)
• context : text
  • NOTHING
  • ACKNOWLEDGED
  • PARTIAL-ACKNOWLEDGED
  • INHERITED-ACKNOWLEDGED
  • DOWNTIME
  • PARTIAL-DOWNTIME
  • INHERITED-DOWNTIME
  • FLAPPING
  • PARTIAL-FLAPPING
  • DISABLED
• output : text
• business_impact : 0, 1, 2, 3, 4, 5
• long_output : text
• host_uuid : text
• host_name : text
• host_display_name : text
  
• raw_perf_data : text, version texte de perf_data
• perf_data : liste de métriques au format :
  • value : number
  • uom : Unit Of Mesure / Unité de mesure
  • warning : valeur d'alerte
  • critical : valeur d'alerte critique
  • min : valeur minimale possible
  • max : valeur maximale possible

Exemple

GET /api/v1/cluster

Cet appel permet de recevoir la liste des uuids de tous les clusters ainsi que de leurs checks.

Réponse

Codes de retour

Retour du code 200

clusters : 

• cluster_uuid : text
• checks :
  • check_uuid : text

Exemple

GET /api/v1/cluster/{uuid}

Cet appel permet de recevoir des informations sur un cluster.

Paramètres

Réponse

Codes de retour

Retour du code 200

• cluster_uuid : text
• cluster_name : text
• cluster_display_name : text
• status : text
• • OK
  • WARNING
  • CRITICAL
  • UNKNOWN
  • MISSING-DATA
  • SHINKEN-INACTIVE
• status_since : epoch (en secondes)
• context : text
• • NOTHING
  • ACKNOWLEDGED
  • PARTIAL-ACKNOWLEDGED
  • INHERITED-ACKNOWLEDGED
  • DOWNTIME
  • PARTIAL-DOWNTIME
  • INHERITED-DOWNTIME
  • FLAPPING
  • PARTIAL-FLAPPING
  • DISABLED
• business_impact : 0, 1, 2, 3, 4, 5
• output : text
• long_output : text
• raw_perf_data : text, version texte de perf_data
• perf_data : liste de métriques au format :
  • value : number
  • uom : Unit Of Mesure / Unité de mesure
  • warning : valeur d'alerte
  • critical : valeur d'alerte critique
  • min : valeur minimale possible
  • max : valeur maximale possible

Exemple

GET /api/v1/check-on-cluster/UUID

Cet appel permet de recevoir des informations sur un check attaché à un cluster.

Paramètres

Réponse

Codes de retour

Retour du code 200

Exemple

Obtenir un UUID

Hôtes et Clusters

Pour récupérer l'UUID d'un hôte ou d'un cluster il suffit de se rendre dans sa page de configuration sur l'UI de Configuration, ou de le sélectionner dans l'UI de Visualisation. Il se trouve alors dans l'URL de la page comme sur les screens suivants:

Il est aussi possible de récupérer les uuid directement par le biais des requêtes apis : all-monitored-elements, host et cluster.

Checks attachés

Données Shinken

Exemple d'utilisation

Ces données peuvent être utilisées par exemple dans les URL externes. Par exemple: