Introduction

Le module broker-module-livedata met à disposition une API permettant de recevoir des informations sur un hôte, un cluster, un check attaché à un hôte ou un check attaché à un cluster. Il est possible de modifier certains paramètres dans la configuration (comme le port d'écoute et le token).



Configuration

Voici le fichier CFG de configuration présent dans : /etc/shinken/modules/broker-module-livedata.cfg

#===============================================================================
# broker module livedata
#===============================================================================
# Daemons that can load this module:
# - broker
# This module is an api getting information from the broker
#===============================================================================

define module {

    #======== Module identity =========
    # Module name. Must be unique
    module_name               broker-module-livedata

    # Module type (to load module code). Do not edit.
    module_type               broker_module_livedata

    #======== Listening address =========
    # host: IP address to listen to.
    #       note: 0.0.0.0 = all interfaces.
    host                      0.0.0.0
    # port to listen
    port                      8000

    # 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                   0
    ssl_cert                  /etc/shinken/certs/server.cert
    ssl_key                   /etc/shinken/certs/server.key
    token                     ak5zv6t5s25r6g4
}


Mise en marche du module

Pour mettre en marche votre module il vous faut l'ajouter à la listes des modules actifs sur le broker souhaité.

Pour se faire, rendez vous dans le fichier de configuration de votre broker à l'emplacement /etc/shinken/brokers/nom_de_votre_broker.cfg à la ligne suivante:

[...]
define broker {
[...]
    modules                   Simple-log, WebUI, Graphite-Perfdata, sla, Livestatus, broker-module-livedata
[...]
}

Redémarrez ensuite votre Arbiter pour que la configuration du Broker soit active.

service shinken-arbiter restart


Fonctionnement

L'accès à cette API est restreinte aux détenteurs d'un token généré dans la configuration (modifiable par l'utilisateur) du module.

Appeler l'API

Pour utiliser l'API il vous faut utiliser une adresse telle que : http://{ip_broker}:{port_module}/api/v1/host/408cd29ad37611e8810e0800277b7e16?token={token}

ou https://IP_DU_BROKER:PORT_DU_MODULE/api/v1/TYPE/UUID?token=TOKEN_DU_MODULE


Exemple pour un hôte avec le module sur le port 8000 du broker en localhost et "adt" comme token : 

http://localhost:8000/api/v1/host/408cd29ad37611e8810e0800277b7e16?token=adt


L'API vous renverra alors du json sous un format standardisé.

Routes de l'API (titre a changer)

GET /api/V1/host/{uuid}

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

Paramètres


ParamètreDescription
uuidRenseigner l'uuid de l'hôte recherché


Réponse

Codes de retour


Codes de retourExplications
200

OK

401

Permission refusée (Mauvais token)

500

L'élément n'est pas un hôte ou est introuvable


Retours du code 500

Le code 500 peut retourner deux messages différents :

"can't find host with this uuid"


"uuid is not a host"


Retour du code 401


"wrong token"


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

Exemple


{
 "status": "OK",
 "host_display_name": "localhost",
 "long_output": "",
 "host_name": "localhost",
 "context": "NOTHING",
 "status_since": 1540457802,
 "business_impact": 2,
 "output": "PING OK - Packet loss = 0%, RTA = 0.02 ms",
 "host_uuid": "408cd29ad37611e8810e0800277b7e16"
}


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

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

Paramètres


ParamètreDescription
uuidRenseigner l'uuid du check recherché, sachant qu'il correspond à {uuid_de_l'hôte}-{uuid_du_check}


Réponse

Codes de retour


Codes de retourExplications
200

OK

401

Permission refusée (Mauvais token)

500

L'élément n'est pas un check attaché à un hôte ou est introuvable


Retours du code 500

Le code 500 peut retourner deux messages différents :

"can't find a check on host with this uuid"


"uuid is not a check on host"


Retour du code 401


"wrong token"


Retour du code 200
  • check_uuid : text
  • check_name : text
  • check_display_name : textstatus : 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

Exemple


{
 "status": "OK",
 "host_display_name": "localhost",
 "check_name": "Broker Daemon Livedata - broker-master",
 "host_uuid": "408cd29ad37611e8810e0800277b7e16",
 "long_output": "",
 "host_name": "localhost",
 "context": "NOTHING",
 "output": "<span style=\"color:#2A9A3D;font-weight:bold;\">[OK]</span> The example works fine.<br/>",
 "business_impact": 2,
 "status_since": 1540457781.797493,
 "check_uuid": "022a505c849f840e110f2aba5e27597f",
 "check_display_name": "Broker Daemon Livedata - broker-master"
}


GET /api/V1/cluster/{uuid}

Cet appel permet de recevoir des informations sur un cluster.

Paramètres


ParamètreDescription
uuidRenseigner l'uuid du cluster recherché


Réponse

Codes de retour


Codes de retourExplications
200

OK

401

Permission refusée (Mauvais token)

500

L'élément n'est pas un cluster ou est introuvable


Retours du code 500

Le code 500 peut retourner deux messages différents :

"can't find cluster with this uuid"


"uuid is not a cluster"


Retour du code 401


"wrong token"


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

Exemple


{
 "status": "OK",
 "cluster_display_name": "localhost",
 "long_output": "",
 "cluster_name": "localhost",
 "context": "NOTHING",
 "status_since": 1540457802,
 "business_impact": 2,
 "output": "PING OK - Packet loss = 0%, RTA = 0.02 ms",
 "cluster_uuid": "408gfhfr7611e8810e0800277b7e16"
}


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

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

Paramètres


ParamètreDescription
uuidRenseigner l'uuid du check recherché, sachant qu'il correspond à {uuid_du_cluster}-{uuid_du_check}


Réponse

Codes de retour


Codes de retourExplications
200

OK

401

Permission refusée (Mauvais token)

500

L'élément n'est pas un check attaché à un cluster ou est introuvable


Retours du code 500

Le code 500 peut retourner deux messages différents :

"can't find check on cluster with this uuid"


"uuid is not a check on cluster"


Retour du code 401


"wrong token"


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
      • cluster_uuid : text
      • cluster_name : text
      • cluster_display_name : text

Exemple


{
 "status": "OK",
 "cluster_display_name": "localhost",
 "check_name": "Broker Daemon Livedata - broker-master",
 "cluster_uuid": "408gfhfr7611e8810e0800277b7e16",
 "long_output": "",
 "cluster_name": "localhost",
 "context": "NOTHING",
 "output": "<span style=\"color:#2A9A3D;font-weight:bold;\">[OK]</span> The example works fine.<br/>",
 "business_impact": 2,
 "status_since": 1540457781.797493,
 "check_uuid": "044a505c849f840e110f2aba5e27597f",
 "check_display_name": "Example cluster check"
}


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 tel que :





Checks attachés

Pour récupérer l'uuid d'un check attaché à un hôte ou à un cluster, il suffit de se rendre dans sa page de configuration sur l'UI de Configuration en y rajoutant l'uuid de l'hôte ou du cluster sur lequel il est attaché, suivit d'un tiret. Ou plus simplement dans l'UI de Visualisation.



Macros Shinken

Des macros sont également disponibles sur Shinken pour utiliser l'uuid d'un hôte/cluster/check.

MacroDescription
$HOSTUUID$Renvoie l'uuid de l'hôte ou du cluster
$SERVICEUUID$Renvoie l'uuid du check