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/, et ajouter le nom de votre module de type "broker-module-livedata"
Exemple: par défaut, nous livrons un module dont le nom est "broker-module-livedata":
define broker {
[...]
modules Simple-log, WebUI, Graphite-Perfdata, sla, broker-module-livedata
[...]
} |
Pour prendre en compte le changement de configuration, redémarrer l'Arbiter:
service shinken-arbiter restart |
Configuration
La configuration du module se trouve par défaut dans le fichier /etc/shinken/modules/broker-module-livedata.cfg
- Vous trouverez aussi systématiquement un exemple dans /etc/shinken-user-example/configuration/daemons/broker/modules/broker-module-livedata/broker-module-livedata-example.cfg
Exemple de fichier de configuration
#================================================================================
# broker-module-livedata
#================================================================================
# Daemon that can load this module:
# - broker
# This module provides REST API to fetch information on monitored elements
#================================================================================
define module {
# ┌─────────────────────────────────────────────────────────────────────────────────────────────────────┐ #
# │ ────────────────────────────────────── MODULE IDENTITY ────────────────────────────────────── │ #
# └─────────────────────────────────────────────────────────────────────────────────────────────────────┘ #
# ─── Module name [ Must be unique ] [ MANDATORY ] ───
# ─── ───
module_name broker-module-livedata
# ─── Module type [ Do not edit ] [ MANDATORY ] ───
# ─── ───
module_type broker_module_livedata
# ┌─────────────────────────────────────────────────────────────────────────────────────────────────────┐ #
# │ ────────────────────────────────────────── GENERAL ────────────────────────────────────────── │ #
# └─────────────────────────────────────────────────────────────────────────────────────────────────────┘ #
# ─── API version this module provides ───
# ───
# Default : 1 => API_V1 ───
# ... : 2 => API_V2 ───
# ───
broker_module_livedata__api_version 2
# ─── Language (only used for the MISSING DATA status) ───
# ───
# Default : en => English ───
# ... : fr => French ───
# ───
# broker_module_livedata__lang en
# ┌─────────────────────────────────────────────────────────────────────────────────────────────────────┐ #
# │ ─────────────────────────────────── LISTENING PARAMETERS ──────────────────────────────────── │ #
# └─────────────────────────────────────────────────────────────────────────────────────────────────────┘ #
# ─── IP address to listen to ───
# ───
# Default : 0.0.0.0 ( all interfaces ) ───
# ───
# broker_module_livedata__listening_address 0.0.0.0
# ─── Port to listen to ───
# ───
# Default : 50100 ───
# ───
# broker_module_livedata__listening_port 50100
# ┌─────────────────────────────────────────────────────────────────────────────────────────────────────┐ #
# │ ───────────────────────────────────── HTTPS PARAMETERS ────────────────────────────────────── │ #
# └─────────────────────────────────────────────────────────────────────────────────────────────────────┘ #
# ─── Enable this parameter if you want to receive API REST calls in HTTPs mode ───
# ───
# Default : 0 => Disable ───
# ... : 1 => Enable ───
# ───
# broker_module_livedata__use_ssl 0
# ─── Certificate file ───
# ───
# Default : /etc/shinken/certs/server.cert ───
# ───
# broker_module_livedata__ssl_cert /etc/shinken/certs/server.cert
# ─── Key file ───
# ───
# Default : /etc/shinken/certs/server.key ───
# ───
# broker_module_livedata__ssl_key /etc/shinken/certs/server.key
# ┌─────────────────────────────────────────────────────────────────────────────────────────────────────┐ #
# │ ────────────────────────────────── BROKS GETTER PARAMETERS ────────────────────────────────── │ #
# └─────────────────────────────────────────────────────────────────────────────────────────────────────┘ #
# ─── These parameters allow some internal tuning in broks management in broker-module-livedata ───
# ─── Late broks sets catchup ───
# ───
# ... : 0 => Disable ───
# Default : 1 => Enable ───
# ───
# broker_module_livedata__broks_getter__activate_late_set_catchup 1
# ─── Take extra broks sets to manage if more than this parameter sets are waiting ───
# ───
# Default : 10 ───
# ───
# broker_module_livedata__broks_getter__nb_late_set_allowed_before_catchup 10
# ─── Stop taking extra broks sets in catchup when we reach this number of broks ───
# ───
# Default : 200000 ───
# ───
# broker_module_livedata__broks_getter__catchup_broks_managed_by_module_in_a_catchup_loop 200000
# ─── Continue catchup if too much late broks sets remains after ───
# ───
# ... : 0 => Disable ───
# Default : 1 => Enable ───
# ───
# broker_module_livedata__broks_getter__catchup_run_endless_until_nb_late_set_allowed_reached 1
# ─── Take the lock as soon as getter thread has some broks to manage ───
# ───
# Default : 0 => Disable ───
# ... : 1 => Enable ───
# ───
# broker_module_livedata__broks_getter__include_deserialisation_and_catchup_in_lock 0
# ┌─────────────────────────────────────────────────────────────────────────────────────────────────────┐ #
# │ ───────────────────────────────────── API V1 PARAMETERS ───────────────────────────────────── │ #
# └─────────────────────────────────────────────────────────────────────────────────────────────────────┘ #
# ─── Token used to authenticate API REST calls on this module ───
# ───
# Default : change_me ───
# ───
# broker_module_livedata__token change_me
# ┌─────────────────────────────────────────────────────────────────────────────────────────────────────┐ #
# │ ───────────────────────────────────── API V2 PARAMETERS ───────────────────────────────────── │ #
# └─────────────────────────────────────────────────────────────────────────────────────────────────────┘ #
# ───────────────────── Usage Logs ──────────────────────────────────────────────────────────────────────
# ─── REST API call can be logged in a specific log file ───
# ───
# Default : 0 => Disable ───
# ... : 1 => Enable ───
# ───
# broker_module_livedata__rest_api_log__enable 0
# ─── File name of the REST API usage logs ───
# ─── This file will always be in directory : ───
# ─── /var/log/shinken/brokers/modules/broker-module-livedata_API-REST ───
# ─── The log file will be daily rotated up to 7 days ───
# ───
# Default : api_v2.log ───
# ───
# broker_module_livedata__rest_api_log__file_name api_v2.log
# ─── Usage logs verbosity ───
# ───
# Default : NORMAL ───
# ... : VERBOSE ───
# ───
# broker_module_livedata__rest_api_log__level NORMAL
# ────────────────── Performance Logs ───────────────────────────────────────────────────────────────────
# ─── Log a warning in broker logs when request to api takes longer than this number of seconds ───
# ───
# Default : 3 ───
# ───
# broker_module_livedata__perf_log__log_call_of_X_seconds_is_an_warning 3
# ─── Log an error in broker logs when request to api takes longer than this number of seconds ───
# ───
# Default : 6 ───
# ───
# broker_module_livedata__perf_log__log_call_of_X_seconds_is_an_error 6
# ───────────────────── Statistics ──────────────────────────────────────────────────────────────────────
# ─── Maximum time to keep performance statistics, after that time they will be removed ───
# ─── All "keeping_last_minutes" parameter will have the value of keeping_last_X_minutes__default, ───
# ─── if they are not set ───
# ───
# Default : 60 ───
# ───
# broker_module_livedata__running_statistics__keeping_last_X_minutes__default 60
# ─── time to keep performance statistics computed in the running loop of the module ───
# ───
# Default : 60 ───
# ───
# broker_module_livedata__running_statistics__keeping_last_X_minutes__running_loop 60
# ─── time to keep performance statistics computed concerning requests ───
# ───
# Default : 60 ───
# ───
# broker_module_livedata__running_statistics__keeping_last_X_minutes__requests 60
# ─── The number of requests per second is stored over X hours ───
# ───
# Default : 24 ───
# ───
# broker_module_livedata__running_statistics__keeping_request_count_per_second_during_X_hours 24
# ┌─────────────────────────────────────────────────────────────────────────────────────────────────────┐ #
# │ ────────────────────────────────────────── MODULES ────────────────────────────────────────── │ #
# └─────────────────────────────────────────────────────────────────────────────────────────────────────┘ #
# ─── Extra modules can extend scope of broker-module-livedata, adding extra functionalities ───
# ─── this parameter contains coma separated list of submodule names, available submodules are ───
# ───
# ... : livedata-module-event-manager-reader ( allowing to query events from ───
# event container ) ───
# ... : livedata-module-sla-provider ( allowing to query SLA of elements ) ───
# ───
# modules
} |
Détails des sections composant le fichier de configuration
Identification du module
...
# ┌─────────────────────────────────────────────────────────────────────────────────────────────────────┐ #
# │ ────────────────────────────────────── MODULE IDENTITY ────────────────────────────────────── │ #
# └─────────────────────────────────────────────────────────────────────────────────────────────────────┘ #
# ─── Module name [ Must be unique ] [ MANDATORY ] ───
# ─── ───
module_name broker-module-livedata
# ─── Module type [ Do not edit ] [ MANDATORY ] ───
# ─── ───
module_type broker_module_livedata
... |
Il est possible de définir plusieurs instances du module broker_module_livedata, le paramètre module_name permet d'identifier une instance donnée.
| Nom | Type | Unité | Défaut | Commentaire | |
|---|---|---|---|---|---|
| Texte | --- | broker-module-livedata | Nous vous conseillons de choisir un nom en fonction de l'utilisation du module pour que votre configuration soit simple à maintenir. Doit être unique. Les caractères autorisés sont les lettres, les chiffres, les caractères _ et - et le nom fourni doit commencer par une lettre | |
| Texte | --- | broker_module_livedata | Ne peut être modifié. |
Version de l'API REST ( V1 / V2 )
# ─── API version this module provides ───
# ───
# Default : 1 => API_V1 ───
# ... : 2 => API_V2 ───
# ───
broker_module_livedata__api_version 2 |
Le module broker-module-livedata peut servir une des deux versions d'API disponibles.
Il est possible de choisir cette version via le paramètre broker_module_livedata__api_version.
Deux choix sont actuellement disponibles :
| Nom | Type | Unité | Défaut | Commentaire | |
|---|---|---|---|---|---|
| Entier | --- | 1 | Valeurs possibles
|
Langue
# ─── Language (only used for the MISSING DATA status) ───
# ───
# Default : en => English ───
# ... : fr => French ───
# ───
# broker_module_livedata__lang en |
Quand le module broker-module-livedata ne reçoit plus de mise à jour pour le statut de certains éléments ( hôtes, clusters, checks ), il modifie
- leur statut à Données Manquantes ,
- leur résultat avec un texte générique expliquant le manque d'information.
- La langue de ce texte générique est définie par le paramètre broker_module_livedata__lang.
| Nom | Type | Unité | Défaut | Commentaire | |
|---|---|---|---|---|---|
| Texte | --- | en | Les langues disponibles sont
|
Adresse et port d'écoute
# ┌─────────────────────────────────────────────────────────────────────────────────────────────────────┐ # # │ ─────────────────────────────────── LISTENING PARAMETERS ──────────────────────────────────── │ # # └─────────────────────────────────────────────────────────────────────────────────────────────────────┘ # # ─── IP address to listen to ─── # ─── # Default : 0.0.0.0 ( all interfaces ) ─── # ─── # broker_module_livedata__listening_address 0.0.0.0 # ─── Port to listen to ─── # ─── # Default : 50100 ─── # ─── # broker_module_livedata__listening_port 50100 |
Le port et l'adresse d'écoute du module broker-module-livedata sont paramétrables via les options suivantes:
| Nom | Type | Unité | Défaut | Commentaire | |
|---|---|---|---|---|---|
| Texte | Adresse IP | 0.0.0.0 | Adresse IP sur laquelle le module doit se mettre en écoute. | |
| Entier | Port | 50100 | Port d'écoute du module. |
Activation du SSL
define module {
[...]
broker_module_livedata__use_ssl 1
broker_module_livedata__ssl_cert /etc/shinken/certs/server.cert
broker_module_livedata__ssl_key /etc/shinken/certs/server.key
[...]
} |
Le module broker-module-livedata peut, au choix, servir le protocole http ou https sur le port configuré ci-dessus.
Le mode https se configure avec les paramètres suivants :
| Nom | Type | Unité | Défaut | Commentaire | |
|---|---|---|---|---|---|
| Booléen | --- | 0 | Paramètre activant le mode SSL ( https ). Valeurs:
Par défaut le module fonctionne en mode http sur le port configuré ci-dessus. | |
| Texte | --- | /etc/shinken/certs/server.cert | Chemin du fichier contenant le certificat. | |
| Texte | --- | /etc/shinken/certs/server.key | Chemin du fichier contenant la clé du certificat. |
Absorption des broks ( information de supervision venant des Schedulers )
Ces paramètres sont dédiés au fonctionnement interne au module, il est fortement recommandé de ne pas les modifier sans votre support dédié. |
Le fonctionnement du thread de récupération des broks peut être configuré via certains paramètres, afin de modifier son "agressivité".
Pendant la mise à jour des données de supervision, le module ne peut pas répondre aux requêtes HTTP qu'il reçoit.
Principe de l'algorithme d'absorption des broks :
- Attente de broks à traiter
- Récupération de broks en retard ( fonctionnalité de rattrapage )
- Désérialisation des broks
- Entrée en session critique ( les requêtes à l'API sont bloquées )
- Traitement des broks
- Libérer la session critique et attendre de nouveaux broks, ou continuer l'absorption de broks ( en cas de retard important, on repart à l'étape 1. en restant sur la session critique )
| Nom | Type | Unité | Défaut | Commentaire | |
|---|---|---|---|---|---|
| Booléen | --- | 1 | Utilisation de la fonctionnalité de rattrapage pour absorber des broks en retard :
| |
| Nombre | Nombre de broks set | 10 | Nombre de brok set en attente toléré. Au-dessus de ce nombre, les brok set sont immédiatement récupérés par l'algorithme de rattrapage pour être traités immédiatement. | |
| Nombre | Nombre de broks | 200000 | Nombre maximal de broks que l'algorithme de rattrapage récupère avant de lancer le traitement. | |
| Booléen | --- | 1 | Après traitement des broks, si le nombre de brok set en retard est trop élevé,
| |
| Booléen | --- | 0 | Dans le cas où vous voulez disposer d'un maximum de temps CPU pour traiter les broks en retard, vous pouvez activer ce paramètre afin de bloquer les requêtes à l'API dès la phase 2 ( Récupération de broks en retard ) puis une fois les broks rattrapés passés en Phase 5 ( Traitement des broks ). Deux valeurs possibles pour ce paramètre :
|
Paramètres spécifiques de l'API V1
Configuration de l'authentification
Afin de sécuriser l'utilisation de l'API du module, un token est nécessaire pour chaque requête. Ce token peut être défini dans la configuration en modifiant le paramètre broker_module_livedata__token.
| Nom | Type | Unité | Défaut | Commentaire | |
|---|---|---|---|---|---|
| Texte | --- | change_me | Chaîne de texte utilisée pour chaque requête au module * |
Cette valeur est utilisée en paramètre d'URL de type GET . Si elle contient des caractères interdits dans une URL, ils devront être échappés (URL encodés) lors de son utilisation pour une requête
Pour plus d'information, vous pouvez consulter : https://developer.mozilla.org/fr/docs/Glossary/percent-encoding et rfc3986 Exemple: pour le token ch@nge_me il faudra utiliser l'url http://broker-module-livedata:50100/api/v1/all-monitored-elements?token=ch%40nge_me |
Exemple
define module {
[...]
broker_module_livedata__token ch@nge_me
[...]
}
|
Paramètres spécifiques de l'API V2
Configuration des logs
L'API REST V2 du module broker-module-livedata permet, optionnellement, d'enregistrer toutes les requêtes qui sont faites via des logs d'utilisation.
De plus, pour suivre le bon fonctionnement du module, des logs de performance permettent de tracer les requêtes lentes.
define module {
[...]
broker_module_livedata__rest_api_log__enable 1
broker_module_livedata__rest_api_log__file_name api_v2.log
broker_module_livedata__rest_api_log__level VERBOSE
broker_module_livedata__perf_log__log_call_of_X_seconds_is_an_warning 5
broker_module_livedata__perf_log__log_call_of_X_seconds_is_an_error 10
[...]
}
|
Logs d'utilisation
La fonctionnalité de logs d'utilisation est définie plus en détails sur la page suivante.
Ces logs sont enregistrés dans un fichier spécifique, les paramètres de configuration sont les suivants :
| Nom | Type | Unité | Défaut | Commentaire | |
|---|---|---|---|---|---|
| Booléen | --- | 0 | Par défaut, les logs d'utilisation sont désactivés. Valeurs possibles :
| |
| Texte | --- | api_v2.log | Nom du fichier qui stockera les logs d'utilisation. Ce fichier sera dans le dossier /var/log/shinken/brokers/modules/broker-module-livedata_API-REST Le journal fera l'objet d'une rotation quotidienne jusqu'à 7 jours. | |
| Texte | --- | NORMAL | Valeurs possibles :
|
Logs de performance
Les logs de performance sont enregistrés dans le fichier de logs du Broker.
Leur format est détaillé sur la page suivante.
Les paramètres suivants permettent d'influer sur leur génération :
| Nom | Type | Unité | Défaut | Commentaire | |
|---|---|---|---|---|---|
| Entier | secondes | 3 | Si le temps d'exécution d'une requête dépasse cette durée, un log de niveau WARNING sera généré dans le fichier des logs du Broker | |
| Entier | secondes | 6 | Si le temps d'exécution d'une requête dépasse cette durée, un log de niveau ERROR sera généré dans le fichier des logs du Broker |
Gestion de statistiques pour la supervision du module
define module {
[...]
broker_module_livedata__running_statistics__keeping_last_X_minutes__default 60
broker_module_livedata__running_statistics__keeping_last_X_minutes__running_loop 60
broker_module_livedata__running_statistics__keeping_last_X_minutes__requests 60
broker_module_livedata__running_statistics__keeping_request_count_per_second_during_X_hours 24
[...]
}
|
Pour limiter la quantité de données à garder, les paramètres suivants sont disponibles :
| Nom | Type | Unité | Défaut | Commentaire | |
|---|---|---|---|---|---|
| Entier | minutes | 60 | Valeur par défaut pour les deux paramètres suivants, si vous ne le définissez pas explicitement. | |
| Entier | minutes | 60 | Intervalle de temps sur lequel on conserve les mesures de performance de la boucle principale du module. | |
| Entier | minutes | 60 | Intervalle de temps sur lequel on conserve les mesures de temps des requêtes traitées. | |
| Entier | heures | 24 | Nombre d'heures pendant lesquelles on conserve le nombre de requêtes par secondes. |
Sous modules
define module {
[...]
modules livedata-module-event-manager-reader, livedata-module-sla-provider
[...]
}
|
L'API REST V2 peut être enrichie via l'utilisation des sous modules du broker-module-livedata
Pour activer un sous module, il faut ajouter son nom dans le paramètre modules :
| Nom | Type | Unité | Défaut | Commentaire | |
|---|---|---|---|---|---|
| Texte | --- | Liste de noms de sous modules, séparés par des virgules. Par défaut, aucun sous module n'est activé |
Voici la liste des modules actuellement disponibles, pouvant s'attacher au module broker-module-livedata ( voir Module broker-module-livedata )
| Type de module | Configuration | Documentation | Description |
|---|---|---|---|
livedata-module-sla-provider | Le livedata-module-sla-provider | V2 - ( READ ) /api/v2/sla/ -- OPTIONNEL -- | Ajoute la possibilité de récupérer les données SLAs. |