Formation d'agents spéciaux

À titre de préparation, vous devez donc créer trois répertoires, tous situés sous ~/local/lib/python3/cmk_addons/plugins/<plug-in_family>. Le quatrième répertoire indiqué dans l’exemple ci-dessous est facultatif — il peut être utilisé pour une vérification basée sur un agent.

Quoi de mieux comme agent spécial minimal qu’une vérification locale fournissant un service « Hello World ! » ? Même un simple script shell générant deux lignes de sortie peut le faire :

N'oubliez pas : le fichier doit être rendu exécutable :

Cela attribuera les autorisations nécessaires :

Une règle minimale est désormais créée :

L'name fait référence au nom de l'agent spécial, auquel est attribué le préfixe agent_. Un agent configuré de cette manière sera disponible dans Other integrations. Cependant, son modèle de configuration ne contient aucune entrée en raison de l'elements={} vide.

Cette configuration combine l'agent spécial à exécuter avec les paramètres obtenus via l'interface graphique et les paramètres par défaut. Ces paramètres deviennent désormais des paramètres d'appel. L'name fait à nouveau référence au nom de l'agent spécial, auquel est ajouté le préfixe agent_.

Cela fournit les exigences de base pour l'agent spécial. Vous pouvez, bien sûr, ajouter des informations supplémentaires à tout moment.

Une fois les fichiers créés, vérifiez d'abord si Checkmk peut les valider :

Ensuite, redémarrez le serveur web du site :

Si vous souhaitez que la nouvelle règle soit immédiatement visible dans la recherche, vous devrez redémarrer la base de données en mémoire Redis :

Si vous ouvrez maintenant Setup > Agents > Other integrations, vous devriez voir la nouvelle entrée « Hello special! » dans la section « Custom integrations ».

Si celle-ci est manquante, vérifiez d'abord si vous avez bien stocké tous les fichiers à l'emplacement indiqué. Si vous recherchez d'autres sources d'erreur possibles, vous pouvez le faire facilement dans les éditions commerciales via l'administration des paquets d'extension Checkmk. Sinon, nous avons répertorié les sources d'erreur les plus importantes et les solutions possibles dans le chapitre Dépannage.

Comme dans l'exercice précédent, créez d'abord les répertoires requis — cette fois-ci sous le nom ometemp au lieu de hellospecial.

Maintenant que des données réelles doivent être traitées, vous devrez également réfléchir au langage de programmation et au prétraitement, par exemple. Notre exercice interroge une API publique et reçoit des données JSON. Cela pourrait être effectué dans le shell à l’aide d’une commande curl. Cependant, comme Checkmk est fourni avec un environnement Python bien équipé, il est judicieux de l’utiliser.

La décision suivante concerne le traitement des données. Par exemple, vous pouvez simplement transmettre les données JSON à la sortie de l’agent ou les convertir en format de tableau dans l’agent spécial. En pratique, vous prendrez généralement cette décision en fonction de votre environnement de travail : La « répartition des tâches » a-t-elle été prise en compte lors du développement de votre contrôle ? Les données préparées simplifient-elles le développement du plug-in de contrôle basé sur l’agent associé ? Ou rendent-elles même celui-ci superflu ? Ce dernier cas de figure se présente si les données peuvent être préparées de manière à pouvoir être analysées par un plug-in de contrôle existant.

Notre exemple se contente de transférer la réponse JSON. L'analyse s'effectue ensuite dans le plug-in de contrôle basé sur un agent. La longitude et la latitude sont saisies à l'aide des arguments de ligne de commande --latitude et --longitude. Pour faciliter la lecture des arguments de ligne de commande, nous utilisons la bibliothèque argparse. Comme Open-Meteo prend en charge la latitude et la longitude encodées dans l'URL, une URL avec des espaces réservés suffit. Essayez cette URL dans le navigateur en remplaçant les paramètres par vos propres coordonnées de latitude et de longitude.

La section de l'agent ometemp ne contiendra que l'objet JSON reçu. Testez l'agent spécial en l'appelant depuis la ligne de commande.

Votre sortie sur la ligne de commande devrait désormais ressembler à ceci :

L'étape suivante consiste à configurer les règles pour l'agent. Une fois cette opération terminée, cette règle s'affichera dans Setup > Agents > Other integrations, dans le groupe « Environmental ».

L'agent spécial a ainsi été créé. Après avoir vérifié l'état du site via cmk-validate-plugins, redémarrez le serveur web du site :

Une règle pourrait désormais être créée à partir de cet agent spécial à l'aide d'Add rule: Open-Meteo temperature. Cette règle n'aura toutefois pas encore beaucoup d'utilité, car elle ne contient actuellement que les deux champs permettant de saisir la longitude et la latitude.

Ensuite, nous étendons le nouvel agent spécial afin qu’il ne contienne pas seulement la longitude et la latitude, mais qu’il les traite également. Notre objectif final est d’obtenir les valeurs de température actuelles pour notre emplacement. La configuration suivante combine donc l’agent spécial à exécuter avec les paramètres obtenus depuis l’interface graphique — c’est-à-dire depuis notre section de règles existante — et les paramètres issus des normes.

Les valeurs de longitude et de latitude, que vous pouvez généralement spécifier, sont désormais transférées vers le dictionnaire nommé params. Parallèlement, l’objet host_config contient tous les paramètres spécifiques à l’hôte qui doivent être utilisés ici. Par exemple, host_config.primary_ip_config.address vous donne accès à l’adresse IP principale, et host_config.name contient le nom d’hôte.

Lors du transfert vers l'agent spécial, notez que l'appel est effectué via un shell. La liste des paramètres d'appel ne peut donc contenir que des chaînes de caractères. Les paramètres deviennent alors des paramètres d'appel qui se retrouvent dans la liste command_arguments.

Par souci d'exhaustivité, nous présentons également ici le plug-in de vérification basé sur un agent. Le développement de ces plug-ins est décrit en détail dans l'article consacré aux plug-ins de vérification basés sur un agent.

Une différence par rapport à l’exemple mentionné dans l’article réside dans le transfert du JSON renvoyé par l’API REST : Le plug-in de vérification reçoit toujours la section de l’agent sous la forme d’une liste bidimensionnelle (« liste de listes ») de chaînes de caractères. Tout d’abord, nous utilisons la fonction `itertools` pour transformer cette liste bidimensionnelle en une liste unidimensionnelle. Nous concaténons ensuite ce tableau résultant avec des espaces, ce qui convertit l’intégralité de la section agent en une seule chaîne de caractères. Enfin, nous veillons à remplacer les guillemets simples par des guillemets doubles afin de pouvoir charger la chaîne directement en tant qu’objet avec `json.loads()`.

Il est toujours recommandé d'effectuer une validation à l'aide de la commande « cmk-validate-plugins » si vous avez apporté des modifications à des éléments exécutés dans le cadre des processus Checkmk. Dans cet article, cela concerne notamment les règles, la configuration des appels et les plug-ins de vérification.

Si vous n'avez apporté des modifications qu'à la configuration des appels et à l'agent spécial lui-même, il suffit de générer une nouvelle configuration pour le noyau de surveillance et de le redémarrer. Pour ce faire, utilisez la commande suivante :

Si vous avez également modifié des règles ou des plug-ins de contrôle, générez d'abord la configuration du noyau de surveillance, puis redémarrez l'ensemble du site :

Les scripts décrits dans cet article pour l'agent spécial, la configuration des règles et la configuration des appels, lorsqu'ils sont utilisés en combinaison avec ce plug-in de vérification, devraient désormais vous fournir un service fonctionnel dans Checkmk :

Si le service Check_MK passe soudainement à l'état « WARN » ou « CRIT » après l'activation de son agent spécial, consultez l'Summary associée.

Si l’Summary indique une connexion avec le nouvel agent spécial, vérifiez les propriétés de l’hôte. La valeur Configured API integrations and Checkmk agent doit être sélectionnée pour le paramètre Checkmk agent / API integrations.

Si votre agent spécial n'apparaît pas (ou n'apparaît plus) dans Checkmk sous « Setup > Agents > Other integrations », il se peut qu'il y ait une erreur dans la configuration de la règle (rulesets/special_agent.py).

Si vous utilisez l'une des éditions commerciales, vous verrez peut-être apparaître un avertissement rouge lorsque vous essayez de modifier la règle ou d'en créer une nouvelle. Suivez le lien vers la page du rapport d'erreur. La cause possible du problème y sera affichée.

Consultez ensuite les descriptions d'erreur :

Par exemple, vous obtiendrez un résultat similaire à celui-ci :

Vérifiez la syntaxe de votre fichier d'rulesets/special_agent.py. Vérifiez si toutes les bibliothèques requises ont été prises en compte et si toutes les variables ont été importées. Vérifiez si toutes les indentations sont correctes et vérifiez l'ensemble de la syntaxe.

Il peut également y avoir un problème dans la configuration de l'appel ou dans l'agent spécial lui-même. Cela se manifeste, par exemple, par l'affichage d'un avertissement jaune lors de l'Activate changes.

Vérifiez le fichier d'server_side_calls/special_agent.py en suivant les informations fournies dans le message d'erreur. Si cela ne résout pas l'erreur, vous pouvez rechercher à nouveau les messages d'erreur sur la ligne de commande :

Après un court instant, vous obtiendrez un résultat similaire à celui-ci (ici abrégé pour plus de clarté) :

Les dernières lignes du résultat sont particulièrement intéressantes : Dans le fichier server_side_calls/special_agent.py, une tentative d'accès à un élément du dictionnaire params qui n'existe pas est en cours.

Une autre source d'erreur peut être que le plug-in de vérification ne génère aucune donnée. Cela peut également être vérifié en ligne de commande :

Si vous recevez ici un message d'erreur au lieu d'une chaîne contenant les données de mesure actuelles, utilisez ce message d'erreur pour corriger le problème.