Page History

Voici la liste des routes disponibles dans ce module :

none

Info

Pour les routes nécessitant un UUID, vous pouvez utiliser cette p age pour trouver simplement vos UUID.

Panel

title	Sommaire

Table of Contents

maxLevel

2

style

Les routes suivantes sont mise 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.

Authentification

L'API du module broker-module-livedata est accessible à l'adresse suivante:

Code Block
http://<ip-broker>:<port-module>/

Les appels effectués à l'API demandent l'utilisation d'un token d'identification. Ce token est spécifié dans le fichier de configuration du module (/etc/shinken/modules/broker-module-livedata.cfg).

Il est fortement recommandé de changer ce token.

Ce token doit être ajouté en paramètre à chaque requête sous peine de recevoir une erreur 401 de la part de l'API.

Par exemple:

Code Block
http://192.168.1.59:50100/api/v1/host/408cd29ad37611e8810e0800277b7e16?token=ak5zv6t5s25r6g4

Chaque appel à l'API renvoie une réponse au format JSON.

Info

title	Remarque

Avec le module configuré en HTTP, une simple écoute du réseau permet de trouver le token. Il est fortement recommandé de passer en HTTPS afin d'éviter une interception du token.

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

Codes de retourExplications200

OK

401

Permission refusée (Mauvais token)

Retour du code 200

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

Exemple

Code Block

title	http://localhost:50100/api/v1/all-monitored-elements

{
   "clusters":[
      {
         "cluster_uuid":"ac169cd1fb5744999eaadc5da595f88b",
         "checks":[
         ]
      },
      {
         "cluster_uuid":"0dcad2b1667642d28c933de70915331e",
         "checks":[
            "0dcad2b1667642d28c933de70915331e-905374c0f6ed11e78cd83cf862f4613a",
            "0dcad2b1667642d28c933de70915331e-714f6a1b90b318bbcfffb1a71d6258af",
            "0dcad2b1667642d28c933de70915331e-8537fb11f6ed11e7bf9f3cf862f4613a",
            "0dcad2b1667642d28c933de70915331e-8700ea097f3eb219b0e61d871936bfe4"
         ]
      }
   ],
   "hosts":[
      {
         "host_uuid":"ac169cd1fb5744999eaadc5da595f88b",
         "checks":[
         ]
      },
      {
         "host_uuid":"0dcad2b1667642d28c933de70915331e",
         "checks":[
            "0dcad2b1667642d28c933de70915331e-905374c0f6ed11e78cd83cf862f4613a",
            "0dcad2b1667642d28c933de70915331e-714f6a1b90b318bbcfffb1a71d6258af",
            "0dcad2b1667642d28c933de70915331e-8537fb11f6ed11e7bf9f3cf862f4613a",
            "0dcad2b1667642d28c933de70915331e-8700ea097f3eb219b0e61d871936bfe4"
         ]
      }
   ]
}

GET /api/v1/host

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

Paramètres

Nom du paramètreRetourExemplehostgroup_name ( optionnel )

Liste des hôtes ayant pour nom de groupe la valeur du paramètre hostgroup_name.

Si plusieurs valeurs sont précisées, retourne les hôtes de chaque groupes.

hostgroup_name=gironde,aveyron Warning

Les valeurs de ces paramètres sont utilisées dans une URL.

Ainsi leur contenu doit être échappé (URL encodée) s'ils contiennent des caractères interdits dans une URL :

caractère interdit:/?#[]@!$&'()*+,;=%(espace)remplacement%3A%2F%3F%23%5B%5D%40%21%24%26%27%28%29%2A%2B%2C%3B%3D%25%20 ou +

Exemple: host_name=mon (hote) doit s'écrire hostgroup_name =mon+%28groupe%29

Pour plus d'information vous pouvez consulter : https://developer.mozilla.org/fr/docs/Glossary/percent-encoding et rfc3986

Réponse

Codes de retour

Codes de retourExplications200

OK

401

Permission refusée (Mauvais token)

Retour du code 200

hosts :
- host_uuid : text
- host_name : text
- checks :
  - check_uuid : text

Exemple

Appel simple à la route http://localhost:50100/api/v1/host

Code Block

title	http://localhost:50100/api/v1/host?token=ak5zv6t5s25r6g4

{
	"hosts":[
      {
         "host_uuid":"ac169cd1fb5744999eaadc5da595f88b",
		 "host_name":"Bordeaux",
         "checks":[
         ]
      },
      {
         "host_uuid":"0dcad2b1667642d28c933de70915331e",
		 "host_name":"Paris",
         "checks":[
            "0dcad2b1667642d28c933de70915331e-905374c0f6ed11e78cd83cf862f4613a",
            "0dcad2b1667642d28c933de70915331e-714f6a1b90b318bbcfffb1a71d6258af",
            "0dcad2b1667642d28c933de70915331e-8537fb11f6ed11e7bf9f3cf862f4613a",
            "0dcad2b1667642d28c933de70915331e-8700ea097f3eb219b0e61d871936bfe4"
         ]
      },
	  {
         "host_uuid":"0dcad2b1667642d28c933de70915331f",
		 "host_name":"Bruges",
         "checks":[
            "0dcad2b1667642d28c933de70915331f-905374c0f6ed11e78cd83cf862f4613b",
            "0dcad2b1667642d28c933de70915331f-714f6a1b90b318bbcfffb1a71d6258ag",
            "0dcad2b1667642d28c933de70915331f-8537fb11f6ed11e7bf9f3cf862f4613b",
            "0dcad2b1667642d28c933de70915331f-8700ea097f3eb219b0e61d871936bfe5"
         ]
      }
   ]
}

Appel à la route http://localhost:50100/api/v1/host avec un filtre sur le hostgroup_name

Code Block

title	http://localhost:50100/api/v1/host?hostgroup_name=gironde&token=ak5zv6t5s25r6g4

{
	"hosts":[
      {
         "host_uuid":"ac169cd1fb5744999eaadc5da595f88b",
		 "host_name":"Bordeaux",
         "checks":[
         ]
      },
      {
         "host_uuid":"0dcad2b1667642d28c933de70915331f",
		 "host_name":"Bruges",
         "checks":[
            "0dcad2b1667642d28c933de70915331f-905374c0f6ed11e78cd83cf862f4613b",
            "0dcad2b1667642d28c933de70915331f-714f6a1b90b318bbcfffb1a71d6258ag",
            "0dcad2b1667642d28c933de70915331f-8537fb11f6ed11e7bf9f3cf862f4613b",
            "0dcad2b1667642d28c933de70915331f-8700ea097f3eb219b0e61d871936bfe5"
         ]
      }
   ]
}

GET /api/v1/host/{uuid}

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

Paramètres

ParamètreDescriptionuuidUUID de l'hôte

Réponse

Codes de retour

Codes de retourExplications200

OK

401

Permission refusée (Mauvais token)

404

Hôte introuvable

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

Code Block

title	http://localhost:50100/api/v1/host/408cd29ad37611e8810e0800277b7e16?token=ak5zv6t5s25r6g4

{
 "status": "OK",
 "host_display_name": "localhost",
 "raw_perf_data": "rta=0.021000ms;1000.000000;3000.000000;0.000000 pl=0%;100;100;0",
 "perf_data": [{"name": "rta", "min": 0, "max": null, "value": 0.021, "warning": 1000, "critical": 3000, "uom": "ms"}, {"name": "pl", "min": 0, "max": 100, "value": 0, "warning": 100, "critical": 100, "uom": "%"}],
 "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ètreDescriptionuuidUUID du check, sachant qu'il correspond à {uuid_de_l'hôte}-{uuid_du_check}

Réponse

Codes de retour

Codes de retourExplications200

OK

401

Permission refusée (Mauvais token)

404

Check introuvable

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

Code Block

title	http://localhost:50100/api/v1/check-on-host/408cd29ad37611e8810e0800277b7e16-022a505c849f840e110f2aba5e27597f?token=ak5zv6t5s25r6g4

{
 "status": "OK",
 "host_display_name": "localhost",
 "raw_perf_data": "livedata_nb_error_last_hour=0 livedata_average_response_time=0.000852610383715 livedata_nb_request_last_hour=84 livedata_error_percent=0.0",
 "perf_data": [{"name": "livedata_nb_error_last_hour", "min": null, "max": null, "value": 0, "warning": null, "critical": null, "uom": null}, {"name": "livedata_nb_request_last_hour", "min": null, "max": null, "value": 84, "warning": null, "critical": null, "uom": null},
 "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

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

Réponse

Codes de retour

Codes de retourExplications200

OK

401

Permission refusée (Mauvais token)

Retour

du

code 200

clusters :

cluster_uuid : text
checks :
- check_uuid : text

Exemple

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

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

Paramètres

ParamètreDescriptionuuidUUID du check, sachant qu'il correspond à {uuid_du_cluster}-{uuid_du_check}

Réponse

Codes de retour

Codes de retourExplications200

OK

401

Permission refusée (Mauvais token)

404

Check introuvable

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
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

Code Block

title	http://localhost:50100/api/v1/check-on-cluster/408gfhfr7611e8810e0800277b7e16-044a505c849f840e110f2aba5e27597f?token=ak5zv6t5s25r6g4

{
 "status": "OK",
 "cluster_display_name": "localhost",
 "cluster_uuid": "408gfhfr7611e8810e0800277b7e16",
 "check_name": "Broker Daemon Livedata - broker-master",
 "raw_perf_data": "livedata_nb_error_last_hour=0 livedata_average_response_time=0.000852610383715 livedata_nb_request_last_hour=84 livedata_error_percent=0.0",
 "perf_data": [{"name": "livedata_nb_error_last_hour", "min": null, "max": null, "value": 0, "warning": null, "critical": null, "uom": null}, {"name": "livedata_nb_request_last_hour", "min": null, "max": null, "value": 84, "warning": null, "critical": null, "uom": null},
 "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 de la page comme sur les screens suivants:

Panel
Image Removed

Panel
Image Removed

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

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é, suivi d'un tiret. Dans l'interface de Visualisation, il peut être trouvé directement dans l'URL en ouvrant le détail du check:

Panel
Image Removed

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

Exemple d'utilisation

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

Panel
Image Removed

L'URL externe de cet hôte amène directement sur le volet Graphiques de l'hôte en questionhttp://localhost:50100/api/v1/cluster?=ak5zv6t5s25r6g4

Code Block

title

token

{
	"clusters":[
      {
         "cluster_uuid":"ac169cd1fb5744999eaadc5da595f88b",
         "checks":[
         ]
      },
      {
         "cluster_uuid":"0dcad2b1667642d28c933de70915331e",
         "checks":[
            "0dcad2b1667642d28c933de70915331e-905374c0f6ed11e78cd83cf862f4613a",
            "0dcad2b1667642d28c933de70915331e-714f6a1b90b318bbcfffb1a71d6258af",
            "0dcad2b1667642d28c933de70915331e-8537fb11f6ed11e7bf9f3cf862f4613a",
            "0dcad2b1667642d28c933de70915331e-8700ea097f3eb219b0e61d871936bfe4"
         ]
      }
   ]
}

GET /api/v1/cluster/{uuid}

Cet appel permet de recevoir des informations sur un cluster.

Paramètres

ParamètreDescriptionuuidUUID du cluster

Réponse

Codes de retour

Codes de retourExplications200

OK

401

Permission refusée (Mauvais token)

404

Cluster introuvable

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

Code Block

title	http://localhost:50100/api/v1/cluster/408gfhfr7611e8810e0800277b7e16?token=ak5zv6t5s25r6g4

{
 "status": "OK",
 "cluster_display_name": "localhost",
 "raw_perf_data": "rta=0.021000ms;1000.000000;3000.000000;0.000000 pl=0%;100;100;0",
 "perf_data": [{"name": "rta", "min": 0, "max": null, "value": 0.021, "warning": 1000, "critical": 3000, "uom": "ms"}, {"name": "pl", "min": 0, "max": 100, "value": 0, "warning": 100, "critical": 100, "uom": "%"}],
 "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"
}

.

Page tree

Page History

Versions Compared

Old Version 14

New Version Current

Key

Authentification

GET /api/v1/all-monitored-elements

Réponse

Codes de retour

Retour du code 200

Exemple

GET /api/v1/host

Paramètres

Réponse

Codes de retour

Retour du code 200

Exemple

GET /api/v1/host/{uuid}

Paramètres

Réponse

Codes de retour

Retour du code 200

Exemple

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

Paramètres

Réponse

Codes de retour

Retour du code 200

Exemple

GET /api/v1/cluster

Réponse

Codes de retour

Exemple

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

Paramètres

Réponse

Codes de retour

Retour du code 200

Exemple

Obtenir un UUID

Hôtes et Clusters

Checks attachés

Macros Shinken

Exemple d'utilisation

GET /api/v1/cluster/{uuid}

Paramètres

Réponse

Codes de retour

Retour du code 200

Exemple