Développement de modules complémentaires de vérification basés sur des agents

Depuis la version 2.0.0 de Checkmk, une nouvelle API Check a été développée pour la programmation des plug-ins de vérification. Dans la version 2.4.0 de Checkmk, l’API Check V2 est la version actuelle. Dans cet article, nous vous montrerons comment utiliser l’API Check version 2 pour la programmation des plug-ins. Vous trouverez des informations sur la migration vers l’API Check version 2 à la fin de cet article, dans le chapitre « Migration ».

Vous pouvez accéder à tout moment à la documentation de l'API Check via l'interface utilisateur de Checkmk : Help > Developer resources > Plug-in API references. Dans la nouvelle fenêtre de navigateur, sélectionnez « Agent based ("Check API") > Version 2 » dans la barre de navigation de gauche :

Vous y trouverez non seulement la documentation de l’API Check dans toutes les versions prises en charge, mais également la documentation de toutes les autres API pertinentes pour la création de plug-ins de contrôle. Dans cet article, nous utilisons non seulement l’API Check, mais également l’API Rulesets V1 lors de la création d’un ensemble de règles et l’API Graphing V1 lors de la création de définitions de métriques.

Si vous souhaitez programmer des plug-ins de vérification, vous aurez besoin des éléments suivants :

La première étape avant d'écrire un programme de plug-in est la recherche ! Cela signifie qu'il faut déterminer comment obtenir les informations dont vous avez besoin pour la surveillance.

Pour l'exemple choisi, nous partons du fait que le serveur Checkmk est également l'hôte. Cela signifie qu'au départ, il suffit de récupérer les données d'état via Livestatus, c'est-à-dire les données organisées en tables que Checkmk conserve en mémoire vive concernant les hôtes et les services surveillés.

Connectez-vous en tant qu'utilisateur du site et interrogez les informations sur les groupes d'hôtes à l'aide de la commande suivante :

La première ligne de la sortie contient les noms des colonnes de la table hostgroups interrogée. Le point-virgule sert de séparateur. Les lignes suivantes contiennent ensuite le contenu de toutes les colonnes, également séparées par des points-virgules.

La sortie est déjà relativement confuse dans ce petit exemple et contient des informations qui ne sont pas pertinentes pour notre cas. En général, vous devriez laisser l'interprétation des données à Checkmk. Cependant, un filtrage préalable sur l'hôte peut réduire le volume de données à transférer si toutes ne sont pas réellement nécessaires. Dans ce cas, limitez donc la requête aux colonnes pertinentes (Columns), aux noms des groupes d'hôtes (name) et aux hôtes de ces groupes (members) :

L'interface Livestatus attend que toutes les commandes et tous les en-têtes soient placés sur des lignes distinctes. Les sauts de ligne nécessaires sont indiqués par \n.

Dans cet exemple, il existe actuellement trois groupes d'hôtes : deux groupes pour les emplacements et un pour le groupe « check_mk ». Ce dernier contient un hôte appelé localhost.

Le groupe d'hôtes « check_mk » est une fonctionnalité spéciale au sein des groupes d'hôtes. Vous ne l'avez pas créé vous-même. Et vous ne pouvez pas ajouter activement un hôte à ce groupe. D'où vient donc ce groupe d'hôtes ? Comme, par définition, chaque hôte dans Checkmk doit appartenir à un groupe, Checkmk attribue par défaut chaque hôte que vous n'affectez pas spécifiquement à un groupe au groupe « spécial » check_mk. Dès que vous avez affecté un hôte à l'un de vos propres groupes d'hôtes, Checkmk le retire du groupe check_mk. Il n'est pas non plus possible de réaffecter un hôte au groupe d'hôtes check_mk.

Ce sont précisément ces propriétés du groupe « check_mk » qui sont utilisées dans notre exemple : Étant donné que chaque hôte doit être affecté à un emplacement, le groupe d’hôtes « check_mk » doit être vide. S’il n’est pas vide, une action est requise, c’est-à-dire que les hôtes qu’il contient doivent être affectés aux groupes d’hôtes et donc à leurs emplacements respectifs.

Jusqu’à présent, en tant qu’utilisateur du site, vous avez utilisé la commande lq pour afficher les informations. Cela est utile pour comprendre les données.

Cependant, pour récupérer ces données depuis le serveur Checkmk, la nouvelle commande doit être intégrée à l’agent Checkmk sur l’hôte surveillé. Théoriquement, vous pourriez désormais modifier directement l’agent Checkmk dans le fichier `/usr/bin/check_mk_agent` et y inclure cette partie. Cette méthode présenterait toutefois l’inconvénient que votre nouvelle commande disparaîtrait à nouveau lors de la mise à jour du logiciel de l’agent, car ce fichier sera écrasé pendant la mise à jour.

Il est donc préférable de créer un plug-in d'agent. Pour cela, il vous suffit d'un fichier exécutable contenant la commande et situé dans le répertoire /usr/lib/check_mk_agent/plugins/.

Et il y a encore une chose importante : Les données ne peuvent pas être simplement affichées. Vous aurez toujours besoin d'un en-tête de section. Il s'agit d'une ligne spécialement formatée qui contient le nom du nouveau plug-in d'agent. Cet en-tête de section permet à Checkmk de reconnaître ultérieurement où commencent les données du nouveau plug-in d'agent et où se terminent celles du plug-in précédent. C'est plus simple lorsque le plug-in d'agent, l'en-tête de section et le plug-in de vérification portent le même nom — même si cela n'est pas obligatoire.

Vous devrez donc tout d’abord choisir un nom significatif pour votre nouveau plug-in de vérification. Ce nom ne peut contenir que des lettres minuscules (uniquement a-z, sans trémas ni accents), des traits de soulignement et des chiffres, et doit être unique. Évitez les conflits de noms avec les plug-ins de vérification existants. Si vous souhaitez connaître les noms déjà existants, vous pouvez les répertorier sur un site Checkmk via la ligne de commande à l’aide de la commande « cmk -L » :

La sortie ci-dessous n'affiche que les premières lignes d'une très longue liste. Grâce à l'utilisation de préfixes, l'affectation de nombreux plug-ins de vérification est déjà facilement identifiable ici. L'utilisation de préfixes est donc également recommandée pour vos propres plug-ins de vérification. À noter que la deuxième colonne indique comment le plug-in de vérification concerné obtient ses données.

Un nom approprié pour le nouveau plug-in de vérification de notre exemple est myhostgroups.

Vous disposez désormais de toutes les informations nécessaires pour créer le script du plug-in d'agent. Créez un nouveau fichier myhostgroups en tant qu'utilisateur root dans le répertoire /usr/lib/check_mk_agent/plugins/ :

Qu'est-ce que cela signifie exactement ?

La première ligne contient le « shebang » (abréviation de « sharp » et « bang », ce dernier étant l'abréviation du point d'exclamation), grâce auquel Linux reconnaît qu'il doit exécuter le script avec le shell spécifié.

Afin de garantir la flexibilité du script, deux variables sont ensuite introduites :

Utilisez la commande echo pour afficher l'en-tête de la section. Comme les colonnes du tableau sont séparées par un point-virgule, utilisez l'sep(59)e supplémentaire pour spécifier que le point-virgule est utilisé comme séparateur pour les données dans la sortie de l'agent. Le 59 correspond au code de caractère ASCII 59, le point-virgule. Sans cette e, le caractère espace (caractère ASCII 32) serait utilisé par défaut comme séparateur.

Pour pouvoir utiliser la commande lq, à laquelle vous avez accès en tant qu'utilisateur du site, dans un script exécuté par l'utilisateur root, faites-la précéder de su.

Une dernière chose est importante une fois que vous avez créé le fichier : rendez-le exécutable :

Vous pouvez tester le plug-in de l'agent directement en saisissant manuellement le chemin d'accès complet sous forme de commande :

Les groupes d'hôtes qui ne contiennent aucun hôte ne sont pas répertoriés ici.

Les tests et le dépannage constituent les tâches les plus importantes lors de la création d'un plug-in d'agent fonctionnel. Il est préférable de procéder en trois étapes :

Tester l'agent localement est très simple. À titre d'root, exécutez la commande « check_mk_agent » :

La nouvelle section doit apparaître quelque part dans la très longue sortie. Les plug-ins de l'agent sont générés par l'agent à la fin du traitement.

Vous pouvez faire défiler la sortie en ajoutant less (appuyez sur Spacebar pour faire défiler, / pour rechercher et Q pour quitter) :

Vous pouvez également rechercher les lignes qui vous intéressent dans la sortie. Par exemple, la commande « grep » avec l'option « -A » permet d'afficher quelques lignes supplémentaires après chaque occurrence. Cela vous permet de rechercher et d'afficher facilement la section souhaitée :

Le troisième et dernier test s'effectue ensuite directement depuis le site Checkmk. Ajoutez l'hôte à la surveillance (par exemple via localhost), connectez-vous en tant qu'utilisateur du site, puis récupérez les données de l'agent avec cmk -d :

Cela devrait produire le même résultat que la commande précédente.

Si cela fonctionne, votre agent est prêt. Et qu'avez-vous fait pour cela ? Vous avez créé un petit script sous le chemin /usr/lib/check_mk_agent/plugins/myhostgroups et l'avez rendu exécutable.

Tout ce qui suit se déroule désormais uniquement sur le serveur Checkmk : C'est là que vous écrivez le plug-in de vérification.

Pour vos propres plug-ins de vérification, vous trouverez le répertoire de base déjà préparé dans la hiérarchie local du répertoire du site. Il s'agit de ~/local/lib/python3/cmk_addons/plugins/. Ce répertoire appartient à l'utilisateur du site et est donc accessible en écriture pour vous.

Dans ce répertoire, les plug-ins sont organisés en familles de plug-ins, dont les noms de répertoires peuvent être définis librement. Par exemple, tous les plug-ins relatifs aux appareils Cisco sont stockés dans le dossier cisco, de même que tous les plug-ins relatifs à vos groupes d’hôtes sont stockés dans le dossier myhostgroups. Cette convention permet à tous les plug-ins appartenant à la même famille de partager du code — et est utilisée exactement de la même manière par les plug-ins fournis avec Checkmk.

Dans ce sous-répertoire <plug-in_family>, d’autres sous-répertoires aux noms prédéfinis sont ensuite créés selon les besoins pour les différentes API, par exemple agent_based pour l’API Check des plug-ins de contrôle basés sur des agents. Nous présenterons à notre tour d’autres sous-répertoires pour l’API Rulesets et l’API Graphing ultérieurement.

Créez les deux sous-répertoires pour le nouveau plug-in de vérification basé sur un agent, puis accédez-y pour travailler :

Vous pouvez modifier votre plug-in de vérification à l'aide de n'importe quel éditeur de texte installé sur le système Linux.

Créez ici le fichier « myhostgroups.py » pour le plug-in de contrôle. La convention veut que le nom du fichier reflète le nom de la section de l'agent. Il est obligatoire que le fichier se termine par « .py », car à partir de la version 2.0.0 de Checkmk, les plug-ins de contrôle sont toujours de véritables modules Python.

Un cadre de base exécutable (téléchargeable sur GitHub), que vous allez développer étape par étape ci-après, se présente comme suit :

Vous devez d'abord importer les fonctions et les classes requises pour les plug-ins de vérification à partir des modules Python. Pour notre exemple, nous n'importerons que ce qui sera nécessaire ou pourrait s'avérer utile dans la suite de cet article. Ici, `cmk.agent_based.v2` est utilisé pour spécifier que les modules de l'API Check V2 sont importés :

La fonction d'analyse a pour tâche d'« analyser » les données « brutes » de l'agent, c'est-à-dire de les analyser et de les découper, puis de les présenter sous une forme logiquement structurée, facile à traiter pour toutes les étapes suivantes.

Comme indiqué dans la section consacrée au test de l'agent, la section fournie par le plug-in de l'agent présente la structure suivante :

Checkmk divise déjà les lignes de la section fournie par le plug-in de l'agent en une liste de lignes en fonction du séparateur présent dans l'en-tête de la section (dans l'exemple ;) ; ces lignes sont à leur tour des listes de mots. La structure de données suivante est donc disponible dans Checkmk à la place des données brutes provenant du plug-in de l'agent :

Dans la liste interne, le premier élément contient le nom du groupe d'hôtes et le second les noms des hôtes appartenant au groupe.

Vous pouvez accéder à toutes ces informations, mais uniquement via leur position dans l'ensemble de données. Vous devrez donc toujours spécifier le nombre de crochets et le numéro de « séquence » du ou des contenus souhaités à l'intérieur de chaque crochet. Avec des volumes de données plus importants, cela devient de plus en plus complexe et il est de plus en plus difficile de garder une vue d'ensemble.

À ce stade, une fonction d’analyse offre des avantages évidents grâce à la structure qu’elle crée. Elle rend le code plus lisible, les accès sont plus performants et il est beaucoup plus facile de garder une vue d’ensemble. Elle transforme la structure de données fournie par Checkmk de telle sorte que vous pouvez accéder à chacune des valeurs individuelles par son nom (ou sa clé) à votre guise, sans avoir à parcourir à plusieurs reprises le tableau pour trouver ce que vous cherchez :

La convention veut que la fonction d'analyse porte le nom de la section de l'agent et commence par parse_. Elle reçoit string_table comme seul argument. Notez que vous n'êtes pas libre de choisir l'argument ici — il doit être nommé exactement ainsi.

Avec def, vous spécifiez en Python qu’une fonction doit être définie ci-dessous. parsed = {} crée le dictionnaire avec la structure de données améliorée. Dans notre exemple, nous allons parcourir chaque ligne, élément par élément. Le groupe d’hôtes suivi des membres du groupe d’hôtes est extrait de chaque ligne et assemblé en une entrée pour le dictionnaire.

Le dictionnaire est ensuite renvoyé avec `return parsed`.

Pour que toute cette procédure ait un effet, vous devez créer la nouvelle section d'agent avec la nouvelle fonction parse. C'est la seule façon pour qu'elle soit reconnue et prise en compte par Checkmk. Pour ce faire, créez la section d'agent en tant qu'instance de la classe AgentSection :

Il est important ici que le nom de la section corresponde exactement à l'en-tête de section dans la sortie de l'agent. À partir de ce moment, chaque plug-in de vérification qui utilise la section « myhostgroups » reçoit la valeur de retour de la fonction parse. En règle générale, il s'agira du plug-in de vérification du même nom. Mais d'autres plug-ins de vérification peuvent également s'abonner à cette section, comme nous le montrerons dans l'extension du plug-in de vérification.

À ce propos : si vous souhaitez en savoir plus, vous pouvez consulter la documentation de l’API Check à ce stade. Vous y trouverez une description détaillée de cette classe, ainsi que des classes, fonctions et objets qui seront utilisés plus loin dans cet article.

Pour que Checkmk reconnaisse qu’il existe un nouveau plug-in de contrôle, celui-ci doit être créé. Pour ce faire, il suffit de créer une instance de la classe CheckPlugin.

Vous devez toujours spécifier au moins quatre éléments :

Le nom de l'instance doit commencer par check_plugin_. Il se présente alors comme suit :

Il est préférable de ne pas essayer cela pour l'instant, car vous devez d'abord écrire les fonctions discover_myhostgroups et check_myhostgroups. Celles-ci doivent apparaître dans le code source avant la création de la section agent et du plug-in de vérification, comme décrit ci-dessus.

Une fonctionnalité particulière de Checkmk est la détection automatique des services à surveiller. Pour que cela fonctionne, chaque plug-in de vérification doit définir une fonction qui utilise la sortie de l'agent pour déterminer si un service de ce type ou quels services de ce type doivent être créés pour l'hôte en question.

La fonction de découverte est toujours appelée lorsqu’une découverte de services est effectuée pour un hôte. Elle décide alors si des services doivent être créés, et lesquels. Dans le cas standard, elle reçoit exactement un argument nommé section. Celui-ci contient les données de la section agent dans un format préparé par la fonction parse.

Par conséquent, implémentez la logique simple suivante : si la section agent myhostgroups existe, créez également un service adapté. Celui-ci apparaîtra alors automatiquement sur tous les hôtes sur lesquels le plug-in agent est déployé.

Pour les plug-ins de vérification qui ne créent qu’un seul service par hôte, aucune autre information n’est requise :

La fonction de découverte doit renvoyer un objet de type « service » pour chaque service à créer à l'aide de « yield » (et non de « return »). En Python, « yield » a la même fonction que « return » : les deux renvoient une valeur à la fonction appelante. La différence décisive réside dans le fait que « yield » mémorise où la fonction en est dans le traitement des données. L'appel suivant reprend après la dernière instruction « yield » — et ne recommence pas depuis le début. Cela signifie que non seulement le premier résultat est lu (comme ce serait le cas avec « return »), mais tous les résultats dans l’ordre (cet avantage prendra tout son sens plus loin dans notre exemple avec la découverte de services).

Vous pouvez maintenant passer à la fonction de vérification proprement dite, qui utilise la sortie actuelle de l'agent pour déterminer l'état que le service doit prendre et qui peut fournir des informations supplémentaires.

L'objectif de la fonction de vérification est de mettre en place une vérification permettant de déterminer si un groupe d'hôtes a été attribué à un hôte. Pour ce faire, elle vérifie si le groupe d'hôtes check_mk contient des hôtes. Si tel est le cas, le service doit recevoir l'état « CRIT ». Dans le cas contraire, tout est « OK », tout comme l'état du service.

Voici l'implémentation :

Et voici maintenant l'explication : La fonction `check_myhostgroups()` récupère d'abord la valeur associée à la clé `check_mk` et la stocke dans la variable `attr`. Ensuite, la variable `hosts` est liée à la valeur `members` si celle-ci existe. S'il n'y a pas de `members`, `hosts` reste vide.

Cette opération est suivie d’une requête if pour l’évaluation proprement dite :

Une fois la fonction de vérification créée, le plug-in de vérification est prêt.

Le plug-in de vérification ainsi que le plug-in d'agent sont disponibles sur GitHub.

Tout d'abord, assurez-vous que votre plug-in est syntaxiquement correct :

Les tests supplémentaires et l'activation du plug-in s'effectuent en ligne de commande à l'aide de la commande `cmk`. Commencez par tester la découverte de service avec l'option `-I`. L'ajout de l'option `v` (pour un mode détaillé) générera une sortie détaillée. L'option `--detect-plugins` limite l'exécution de la commande à ce plug-in de vérification et l'localhoste à cet hôte spécifique :

Comme prévu, la découverte de services reconnaît un nouveau service dans le plug-in de vérification myhostgroups.

Vous pouvez désormais tester la vérification contenue dans le plug-in de vérification :

En exécutant la vérification, l'état du service détecté précédemment sera déterminé.

Si tout s'est déroulé comme prévu, vous pouvez activer les modifications. Si ce n'est pas le cas, vous trouverez des informations utiles dans le chapitre consacré au dépannage.

Enfin, générez une configuration mise à jour du noyau de surveillance et redémarrez-le :

Dans la surveillance Checkmk, vous trouverez désormais le nouveau service Host group check_mk sur l'hôte localhost :

Félicitations pour la création réussie de votre premier plug-in Check!

Le premier module de vérification, récemment achevé, doit désormais être étendu étape par étape. Jusqu’à présent, le module agent ne fournissait que des informations sur les noms et les membres des groupes d’hôtes. Afin de pouvoir évaluer l’état des hôtes et des services qui y sont exécutés, par exemple, davantage de données sont nécessaires.

Dans le chapitre précédent, vous avez créé une vérification très simple qui crée un service sur un hôte. Cependant, il est également très courant qu’un seul contrôle sur un hôte donne lieu à plusieurs services.

L'exemple le plus courant est celui d'un service pour un système de fichiers sur un hôte. Le plug-in de vérification nommé « df » crée un service par système de fichiers sur l'hôte. Afin de distinguer ces services, le point de montage du système de fichiers (par exemple /var) ou la lettre du lecteur (par exemple C:) est intégré au nom du service. Il en résulte un nom de service tel que Filesystem /var ou Filesystem C:. Le mot /var ou C: est désigné ici par le terme « élément ». Nous parlons donc également d’un contrôle avec des éléments.

Si vous souhaitez créer une vérification avec des éléments, vous devez implémenter les fonctions suivantes :

Pour tester cela en pratique, vous allez créer un service distinct pour chaque groupe d'hôtes existant.

Étant donné que le plug-in de vérification myhostgroups créé au chapitre précédent pour vérifier le groupe standard check_mk devrait continuer à fonctionner, ce plug-in de vérification reste tel quel. Pour l'extension, créez le nouveau plug-in de vérification myhostgroups_advanced dans le fichier existant myhostgroups.py. — dans un premier temps, comme précédemment, en créant une instance de la classe CheckPlugin.

Vous trouverez ici l'ancien code et le nouveau code mis en évidence :

Afin de distinguer le nouveau plugin de vérification de l'ancien, on lui attribue un nom unique avec l'option « myhostgroups_advanced ». Le paramètre « sections » détermine les sections de la sortie de l'agent auxquelles le plugin de vérification est abonné. Ici, l'option « myhostgroups » est utilisée pour spécifier que le nouveau plugin de vérification utilise les mêmes données que l'ancien : la section du plugin de l'agent préparée par la fonction « parse ». Le nom du service contient désormais l'espace réservé %s. Le nom de l'élément sera inséré ultérieurement à cet endroit par Checkmk. Dans les deux dernières lignes, les noms de la nouvelle fonction de découverte et de la nouvelle fonction de vérification sont définis, ces deux fonctions devant encore être écrites.

Commençons par la fonction de découverte, qui a désormais pour tâche de déterminer les éléments à surveiller — celle-ci est également ajoutée à la fonction existante :

Comme précédemment, la fonction de découverte reçoit l’argument « section ». Les différents groupes d’hôtes sont parcourus dans une boucle. Tous les groupes d’hôtes présentent ici un intérêt — à l’exception de « check_mk », car ce groupe d’hôtes particulier a déjà été pris en charge par le plugin de vérification existant « myhostgroups ». Chaque fois qu’un élément est trouvé, il est renvoyé via « yield », ce qui crée un objet de type « Service », qui reçoit à son tour le nom du groupe d’hôtes en tant qu’élément.

Si l'hôte est surveillé ultérieurement, la fonction de vérification est appelée séparément pour chaque service — et donc pour chaque élément. Cela vous amène à la définition de la fonction de vérification pour le nouveau plug-in de vérification myhostgroups_advanced. La fonction de vérification reçoit l'argument item en plus de la section. La première ligne de la fonction se présente alors comme suit :

L'algorithme de la fonction de vérification est simple : Si le groupe d'hôtes existe, le service est défini sur « OK » et le nombre ainsi que les noms des hôtes du groupe sont répertoriés. Voici la fonction complète :

Le résultat de la vérification est fourni en renvoyant un objet de la classe Result via yield. Cela nécessite les paramètres state et summary. Ici, state définit l’état du service (dans l’exemple OK) et summary le texte qui s’affiche dans l’Summary du service. Ceci est purement informatif et n’est pas évalué davantage par Checkmk. Vous trouverez plus d’informations à ce sujet dans la section suivante.

Jusqu’ici, tout va bien. Mais que se passe-t-il si l’élément que vous recherchez n’est pas trouvé ? Cela peut se produire si un service a déjà été créé pour un groupe d’hôtes par le passé, mais que ce groupe d’hôtes a désormais disparu — soit parce que le groupe d’hôtes existe toujours dans Checkmk mais ne contient plus aucun hôte, soit parce qu’il a été complètement supprimé. Dans les deux cas, ce groupe d’hôtes ne sera plus présent dans la sortie de l’agent.

La bonne nouvelle : Checkmk s'en charge ! Si un élément recherché n'est pas trouvé, Checkmk génère automatiquement le résultat « UNKNOWN - Item not found in monitoring data » pour le service. C'est intentionnel et c'est une bonne chose. Si un élément recherché n'est pas trouvé, vous pouvez simplement exécuter Python à partir de cette fonction et laisser Checkmk faire son travail.

Checkmk sait seulement que l'élément qui était présent auparavant a désormais disparu. Checkmk ignore la raison de cette disparition — mais vous, vous la connaissez. Il est donc judicieux de ne pas garder cette information pour vous, mais d'intercepter cette condition dans la fonction de vérification et d'afficher un message utile.

Qu'est-ce qui a changé ? La condition d'erreur est désormais traitée en premier. Par conséquent, vérifiez dans la branche « if » si l'élément n'existe vraiment pas, définissez l'état sur « CRIT » et quittez la fonction avec « return ». Dans tous les autres cas, renvoyez « OK » comme auparavant.

Cela signifie que vous avez intégré la situation des groupes d'hôtes disparus dans la fonction de vérification. Au lieu de UNKNOWN, le service associé sera désormais CRIT et contiendra des informations sur la cause de l'état critique.

Cela achève la mise en place du nouveau plug-in de vérification en tant qu'extension de l'ancien. Le plug-in d'agent étendu et le fichier étendu pour les plug-ins de vérification sont à nouveau disponibles sur GitHub. Ce dernier contient le plug-in de vérification simple myhostgroups du chapitre précédent, la fonction d'analyse avancée et les composants du nouveau plug-in de vérification myhostgroups_advanced avec la création du plug-in de vérification, la fonction de découverte et la fonction de vérification. Notez que les fonctions doivent toujours être définies avant la création des plug-ins de vérification ou des sections d'agent afin d'éviter toute erreur due à des noms de fonction non définis.

Comme le nouveau plug-in de vérification myhostgroups_advanced fournit de nouveaux services, vous devez effectuer une découverte de services pour ce plug-in de vérification et activer les modifications afin de voir ces services dans la surveillance :

Procédez comme décrit dans le chapitre consacré au plug-in de vérification simple. N'exécutez pas les deux premières commandes pour myhostgroups, mais exécutez-les pour le nouveau plug-in de vérification myhostgroups_advanced.

Dans la surveillance de Checkmk, chaque service possède un état — OK, WARN, etc. — ainsi qu’une ligne de texte. Ce texte se trouve dans la colonne « Summary » — comme le montre la capture d’écran précédente — et a donc pour fonction de fournir un bref résumé de l’état du service. Le principe est que ce texte ne doit pas dépasser 60 caractères. Cela garantit un affichage concis du tableau sans sauts de ligne gênants.

Il existe également le champ « Details », dans lequel s’affichent tous les détails relatifs à l’état du service, y compris l’ensemble des informations du résumé. En cliquant sur le service, vous ouvrez la page du service, sur laquelle les deux champs « Summary » et « Details » apparaissent aux côtés de nombreux autres.

Lorsque vous appelez yield Result(...), vous pouvez déterminer quelles informations sont suffisamment importantes pour être affichées dans le résumé, et pour lesquelles il suffit qu’elles apparaissent dans les détails.

Dans notre exemple, vous avez toujours utilisé un appel du type suivant :

Cela signifie que le texte défini comme « summary » apparaît toujours dans l’Summary — ainsi que dans l’Details. Vous ne devriez donc l’utiliser que pour des informations importantes. Si un groupe d’hôtes contient de nombreux hôtes, la liste récapitulative peut devenir très longue — plus longue que les 60 caractères recommandés. Si une information est d’importance secondaire, vous pouvez utiliser « details » pour spécifier que son texte n’apparaisse que dans les détails :

Dans l'exemple ci-dessus, la liste des hôtes n'est donc affichée que dans l'Details. L'Summary n'affiche alors que le nombre d'hôtes dans le groupe :

Outre summary et details, il existe un troisième paramètre. Avec notice, vous spécifiez qu’un texte correspondant à un service dans l’OK n’est affiché que dans les détails — mais également dans le résumé pour tous les autres états. Cela permet de comprendre immédiatement, à partir du résumé, pourquoi le service n’est pas OK. Le paramètre notice n’est pas particulièrement utile si les textes sont liés de manière permanente aux états, comme dans notre exemple jusqu’à présent.

En résumé, cela signifie :

Afin d’éviter que le nombre de services sur un hôte n’augmente de manière excessive, plusieurs résultats partiels sont souvent regroupés au sein d’un même service. Par exemple, le service Memory sous Linux vérifie non seulement l’utilisation de la RAM et de l’espace d’échange, mais également la mémoire partagée, les tables de pages et toutes sortes d’autres éléments.

L'API Check fournit une interface très pratique à cet effet. Une fonction de vérification peut simplement générer un résultat avec yield aussi souvent que nécessaire. L'état global du service est alors basé sur le pire résultat partiel dans l'ordre suivant : OK → WARN → UNKNOWN → CRIT.

Dans l'exemple, utilisez cette option pour définir deux résultats supplémentaires pour chaque service des groupes d'hôtes, en plus du résultat existant. Ceux-ci évaluent le pourcentage d'hôtes dans l'état « UP » et de services dans l'état « OK ». Vous utilisez les colonnes supplémentaires du tableau des groupes d'hôtes précédemment défini dans la sortie de l'agent et la fonction d'analyse.

Développez maintenant la fonction de vérification par étapes, de haut en bas :

La branche « if » reste inchangée, c'est-à-dire que les nouveaux résultats partiels ne s'appliquent qu'aux groupes d'hôtes qui existent également. Vous définissez ensuite cinq variables pour les colonnes du tableau des groupes d'hôtes contenu dans la section. D'une part, cela améliore la lisibilité et, d'autre part, vous pouvez convertir les chaînes lues en nombres à l'aide de l'int()e pour les quatre colonnes qui doivent encore être utilisées pour le calcul.

Le seul résultat existant reste (presque) inchangé :

Seul l'accès dans la « F-String » Python à l'expression qui renvoie la valeur est désormais plus simple qu'auparavant, puisque l'attre figure déjà dans les définitions de variables.

Passons maintenant au cœur même de l'extension, à savoir la définition d'un résultat qui met en œuvre l'énoncé suivant : « Le service du groupe d'hôtes est WARN lorsque 90 % des hôtes sont UP, et CRIT lorsque 80 % des hôtes sont UP. » La convention ici est que la vérification passe à WARN ou CRIT dès que le seuil est atteint — et pas seulement lorsqu'il est dépassé. L'API Check fournit la fonction auxiliaire check_levels pour comparer une valeur déterminée avec des valeurs de seuil.

Dans la première ligne, le pourcentage est calculé à partir du nombre total et du nombre d'hôtes dans l'état « UP » et stocké dans la variable « hosts_up_perc ». La barre oblique simple (/) exécute une division en virgule flottante, ce qui garantit que le résultat est une valeur de type float. Ceci est utile car certaines des fonctions utilisées par la suite attendent une valeur de type float en entrée.

À la deuxième ligne, le résultat de la fonction check_levels est ensuite renvoyé sous la forme d’un objet de type Result, que vous trouverez dans la documentation de l’API. Cette fonction est alimentée par le pourcentage qui vient d’être calculé en tant que valeur (hosts_up_perc), les deux valeurs de seuil inférieures (levels_lower), une étiquette qui précède la sortie (label) et enfin par notice_only=True.

Le dernier paramètre utilise le paramètre notice déjà présenté dans la section précédente pour l’objet Result(). Avec notice_only=True, vous spécifiez que le texte du service n’est affiché dans l’Summary que si l’état n’est pas OK. Toutefois, les résultats partiels conduisant à un WARN ou à un CRIT seront dans tous les cas toujours visibles dans le résumé, quelle que soit la valeur de notice_only.

Enfin, vous définissez le troisième résultat de la même manière que le deuxième, qui évalue le pourcentage de services dans l'état « OK » :

Cela achève la fonction de vérification.

Le service d'un groupe d'hôtes évalue désormais trois résultats et affiche le pire état parmi ceux-ci dans la surveillance, comme dans l'exemple suivant :

Pas toujours, mais souvent, les vérifications traitent de chiffres — et ces chiffres sont très souvent des valeurs mesurées ou calculées. Dans notre exemple, le nombre d’hôtes dans le groupe d’hôtes (num_hosts) et le nombre d’hôtes dans l’état « UP » (num_hosts_up) sont les valeurs mesurées. Le pourcentage d’hôtes dans l’état « UP » (hosts_up_perc) est une valeur calculée à partir de ces valeurs. Si une telle valeur peut ensuite être affichée sur une période donnée, on parle également de métrique.

Grâce à son système de graphiques intégré, Checkmk dispose d’un composant permettant de stocker, d’évaluer et d’afficher ces valeurs. Ce composant est totalement indépendant du calcul des états « OK », « WARN » et « CRIT ».

Dans cet exemple, vous allez définir les deux valeurs calculées, « hosts_up_perc » et « services_ok_perc », en tant que métriques. Les métriques seront immédiatement visibles dans l’interface utilisateur graphique de Checkmk sans que vous ayez à intervenir. Un graphique est généré automatiquement pour chaque métrique.

Les métriques sont déterminées par la fonction de vérification et renvoyées en tant que résultat supplémentaire. La méthode la plus simple consiste à ajouter les informations relatives aux métriques à la fonction check_levels() dans l’appel.

Pour rappel, voici les lignes contenant l'appel à la fonction `check_levels()` de la section précédente :

Les deux nouveaux arguments de la métrique sont metric_name et boundaries :

Pour que tout reste simple et clair, utilisez comme nom de la métrique le nom de la variable dans laquelle le pourcentage est stocké en tant que valeur.

Vous pouvez utiliser boundaries pour fournir au système de graphiques des informations sur la plage des valeurs possibles. Cela fait référence à la plus petite et à la plus grande valeur possibles. Dans le cas d'un pourcentage, les limites de 0.0 et 100.0 ne sont pas trop difficiles à déterminer. Les nombres à virgule flottante et les entiers (qui sont convertis en interne en nombres à virgule flottante) sont autorisés, mais pas les chaînes de caractères. Si une seule limite de la plage de valeurs est définie, entrez simplement None pour l'autre, par exemple boundaries = (0.0, None).

Grâce à cette extension, la fonction check_levels renvoie désormais également un objet de type Metric via yield, en plus de Result.

Vous pouvez désormais définir la métrique services_ok_perc de la même manière. Les dernières lignes de la fonction de vérification ressembleront alors à ceci :

Grâce à la fonction de vérification étendue, les deux graphiques sont visibles dans la surveillance. Dans la liste des services, l'icône d's indique désormais qu'il existe des graphiques pour le service. Si vous passez la souris sur l'icône, les graphiques s'affichent en aperçu.

Vous trouverez un aperçu de tous les graphiques, y compris leurs légendes et bien plus encore, dans les détails du service.

Mais que faire si la valeur de la métrique souhaitée n’a pas été définie à l’aide de la fonction d’check_levels() ? Vous pouvez bien sûr définir une métrique indépendamment d’un appel de fonction. L’objet Metric(), que vous pouvez également créer directement via son constructeur, est utilisé à cette fin. La définition alternative d’une métrique pour la valeur hosts_up_perc se présente comme suit :

Les arguments de Metric() sont très similaires à ceux de l'appel de fonction présenté ci-dessus : Les deux premiers arguments, correspondant au nom de la métrique et à la valeur, sont obligatoires. De plus, il existe deux arguments facultatifs : levels pour les valeurs seuils WARN et CRIT, et boundaries pour la plage de valeurs.

Utilisez à présent l’option permettant de définir non seulement les deux valeurs calculées, mais toutes les valeurs mesurées comme métriques à l’aide de Metric() — dans notre exemple, les quatre valeurs mesurées issues du tableau du groupe d’hôtes. Limitez-vous aux deux spécifications obligatoires que sont le nom et la valeur de la métrique. Les quatre nouvelles lignes complètent l’extension de la fonction de vérification pour les métriques :

Cela augmente le nombre de graphiques par service, mais vous offre également la possibilité de combiner plusieurs métriques dans un seul graphique, par exemple. Nous présentons ces options et d’autres dans la section Personnalisation de l’affichage des métriques ci-dessous.

Dans le fichier d'exemple disponible sur GitHub, vous retrouverez l'intégralité de la fonction de vérification.

Pour créer un nouvel ensemble de règles, commencez par créer un nouveau sous-répertoire dans le répertoire de la famille de plug-ins ~/local/lib/python3/cmk_addons/plugins/myhostgroups/. Le nom rulesets est prédéfini pour ce sous-répertoire :

Dans ce répertoire, vous créez ensuite un fichier pour la définition de l'ensemble de règles. Le nom du fichier doit s'inspirer de celui du plug-in de vérification et, comme tous les fichiers de plug-in, il doit porter l'extension py. Pour notre exemple, le nom de fichier ruleset_myhostgroups.py convient.

Examinons étape par étape la structure de ce fichier. Tout d'abord, il y a quelques commandes d'importation :

Tout d'abord, les classes pour les textes sont importées.

La deuxième ligne effectue une sélection parmi les spécifications de formulaire, c'est-à-dire les éléments de base de l'interface graphique utilisés dans l'ensemble de règles, par exemple la sélection binaire (BooleanChoice), la sélection multiple (Dictionary, DictElement), la définition des valeurs seuils (SimpleLevel, LevelDirection, DefaultValue) et la saisie de nombres à virgule flottante (Float). Vous ne demandez ici que les éléments de formulaire logiques et laissez à Checkmk le soin de concevoir l'interface graphique.

La dernière ligne importe les spécifications de la règle, qui déterminent le domaine d'application de la règle dans Checkmk, c'est-à-dire ici la définition des paramètres de contrôle, l'affectation aux hôtes et aux éléments, ainsi que le stockage sous un sujet. Comme votre plugin de contrôle myhostgroups_advanced génère plusieurs services, importez ici HostAndItemCondition. Si votre contrôle ne génère pas de service, c'est-à-dire s'il ne comporte pas d'élément, importez plutôt HostCondition.

Voici maintenant les définitions proprement dites du formulaire permettant de saisir les paramètres de vérification. L'utilisateur doit pouvoir définir séparément les deux valeurs seuils pour WARN et CRIT, tant pour le nombre d'hôtes dans l'état UP que pour le nombre de services dans l'état OK :

Pour ce faire, créez une fonction qui génère le dictionnaire. Vous pouvez choisir librement le nom de la fonction ; il n'est requis que lors de la création de la règle ci-dessous. Le nom doit commencer par un trait de soulignement afin que la fonction ne soit pas visible au-delà des limites du module.

L'return Dictionary() est obligatoire. À l'intérieur de celle-ci, utilisez elements={} pour créer les éléments du dictionnaire, par exemple hosts_up_lower et services_ok_lower. Le formulaire de paramètres SimpleLevels est utilisé pour saisir des valeurs de seuil fixes. Dans ce formulaire, vous définissez d'abord l'titlee et les nombres à virgule flottante pour les valeurs à saisir (form_spec_template). Utilisez LevelDirection.LOWER pour spécifier que le statut changera si les valeurs tombent en dessous de ce niveau.

Enfin, vous pouvez utiliser prefill_fixed_levels pour fournir aux utilisateurs du jeu de règles des valeurs plutôt que de simples champs de saisie vides. Notez que ces valeurs affichées dans l'interface graphique ne sont pas les valeurs par défaut définies plus loin lors de la création du plug-in de vérification via check_default_parameters. Si vous souhaitez afficher dans l'interface graphique les mêmes valeurs par défaut que celles qui s'appliquent à la fonction de vérification, vous devez veiller à ce que les valeurs soient cohérentes aux deux endroits.

Enfin, créez le nouvel ensemble de règles à l'aide des éléments importés et définis par vos soins. Pour ce faire, créez une nouvelle instance de la classe `CheckParameters`. Le nom de cette instance doit commencer par `rule_spec_` :

Les explications suivantes s'appliquent :

Une fois que vous avez créé le fichier pour l'ensemble de règles, vous devez vérifier si tout fonctionne correctement jusqu'à présent — toujours sans connexion au plug-in de vérification. L'exécution de la commande cmk-validate-plugins confirmera alors que l'ensemble de règles lui-même est valide, mais vous avertira qu'il n'a encore aucun effet.

Pour rendre l'ensemble de règles visible, vous devez redémarrer les processus Python qui fournissent l'interface graphique. Pour ce faire, redémarrez le serveur web Apache :

Ensuite, le jeu de règles sera accessible dans Setup sur la page mentionnée ci-dessus. Toutefois, vous ne pourrez trouver la valeur par défaut à l'aide de la fonction de recherche dans l'Setup qu'après avoir redémarré Redis :

L'ensemble de règles que vous venez de définir se présentera ainsi dans l'interface graphique :

Dans la zone « Conditions », vous trouverez le champ de saisie « Host group name » défini via l’HostAndItemCondition pour restreindre la règle aux groupes d’hôtes.

Créez une règle et testez différentes valeurs, comme indiqué dans la capture d'écran ci-dessus. Si cela fonctionne sans erreur, vous pouvez désormais utiliser les paramètres de vérification dans la fonction de vérification.

L'ensemble de règles nouvellement créé est désormais connecté au plug-in de vérification provisoirement achevé au chapitre précédent. Pour que la règle prenne effet, vous devez autoriser le plug-in de vérification à accepter les paramètres de vérification et lui indiquer quelle règle doit être utilisée. Pour ce faire, ajoutez deux nouvelles lignes au fichier du plug-in de vérification lors de la création du plug-in de vérification myhostgroups_advanced :

Avec l'entrée « check_default_parameters », vous pouvez définir les valeurs par défaut qui s'appliquent tant qu'aucune règle n'a encore été créée. Lors de la conversion du plug-in de vérification pour les paramètres de vérification, cette ligne doit être présente. Dans le cas le plus simple, transmettez un dictionnaire vide {}.

Ensuite, entrez check_ruleset_name, c'est-à-dire le nom de l'ensemble de règles. De cette manière, Checkmk sait à partir de quel ensemble de règles les paramètres doivent être déterminés.

Checkmk va maintenant essayer de transmettre des paramètres à la fonction de vérification. Pour que cela fonctionne, vous devez étendre la fonction de vérification de manière à ce qu’elle attende l’argument params, qui est inséré entre item et section :

Si vous créez une vérification sans élément, l'item est omis et params se trouve au début.

Il est fortement recommandé de faire en sorte que le contenu de la variable params soit affiché avec print en premier lieu :

Lorsque le plug-in de vérification est exécuté, les lignes affichées (une pour chaque service) avec les valeurs définies par une règle ressembleront alors à ceci :

Personnalisez maintenant davantage votre fonction de vérification afin que les paramètres transmis puissent prendre effet. Récupérez les deux éléments du dictionnaire définis dans la règle portant le nom sélectionné à partir des paramètres :

Plus bas dans la fonction de vérification, les valeurs de seuil précédemment codées en dur "fixed", (90.0, 80.0) sont alors remplacées par les variables hosts_up_lower et services_ok_lower :

Si une règle a été configurée, vous pouvez désormais surveiller les groupes d'hôtes de l'exemple avec les valeurs de seuil définies via l'interface graphique. Toutefois, si aucune règle n'a été définie, cette fonction de vérification plantera, car les paramètres par défaut du plug-in de vérification n'auront pas été renseignés, et le plug-in générera une erreur « KeyError » en l'absence de règle.

Ce problème peut toutefois être résolu si les valeurs par défaut sont définies lors de la création du plug-in de vérification :

Vous devez toujours transmettre les valeurs par défaut de cette manière (et ne pas intercepter le cas de paramètres manquants dans le plug-in de vérification), car ces valeurs par défaut peuvent également s'afficher dans l'interface Setup. Par exemple, dans la découverte de services d'un hôte, sur la page Services of host, dans le menu Display, se trouve le commutateur Show check parameters.

Les modifications apportées au chapitre précédent affectent à la fois le cœur de surveillance et l’interface utilisateur graphique, ainsi que ses processus associés. Par conséquent, après avoir exécuté la commande « cmk-validate-plugins », vous devez d’abord régénérer la configuration, puis redémarrer le site :

Les procédures de création des ensembles de règles et des définitions de métriques sont très similaires. Commencez par créer un nouveau sous-répertoire portant le nom par défaut « graphing » dans le répertoire de votre famille de plug-ins « ~/local/lib/python3/cmk_addons/plugins/myhostgroups/ ».

Créez ensuite un fichier graphique dans ce répertoire, par exemple graphing_myhostgroups.py.

Tout d'abord, voici à nouveau quelques commandes d'importation :

Dans notre exemple, vous définissez maintenant votre propre métrique pour le pourcentage de services en état «OK». Pour ce faire, créez une instance de la classe Metric. Le nom de cette instance doit commencer par metric_

Voici l'explication :

Cette définition dans le fichier de graphiques garantit désormais que le titre, l'unité et la couleur de la métrique s'affichent correctement.

Tout comme pour la création d'un fichier de règles, le fichier de graphiques doit d'abord être lu avant que la modification ne soit visible dans l'interface graphique. Pour ce faire, redémarrez Apache sur le site :

Le graphique de la métrique ressemblera alors à ceci dans l'interface graphique de Checkmk :

Si vous souhaitez combiner plusieurs métriques dans un seul graphique (ce qui est souvent très utile), vous aurez besoin d'une définition de graphique que vous pourrez ajouter au fichier de graphiques créé dans la section précédente.

Dans notre exemple, les deux métriques num_services et num_services_ok doivent être affichées dans un seul graphique. Les définitions de métriques correspondantes sont créées de la même manière que dans la section précédente pour services_ok_perc et se présentent comme suit :

Ajoutez maintenant un graphique qui trace ces deux métriques sous forme de lignes. Cela s'effectue via une instance de la classe Graph, le nom de l'instance devant à nouveau commencer par un préfixe prédéfini (graph_) :

Le paramètre « minimal_range » décrit la plage minimale couverte par l'axe vertical du graphique, quelles que soient les valeurs réelles de la métrique. L'axe vertical sera étendu si les valeurs dépassent la plage minimale, mais il ne sera jamais plus petit.

Le résultat est le graphique combiné dans l'interface graphique de Checkmk :

Souhaitez-vous afficher un Perf-O-Meter pour une métrique dans la ligne de la liste des services ? Cela pourrait ressembler à ceci, par exemple :

Pour créer un tel Perf-O-Meter, vous aurez besoin d'une autre instance, cette fois-ci de la classe Perfometer, dont le nom commence par le préfixe perfometer_ :

Les Perf-O-Meters sont un peu plus complexes que les graphiques, car ils ne comportent pas de légende. Il est donc difficile d'afficher une plage de valeurs, en particulier lorsque des valeurs absolues sont affichées. Il est plus facile d'afficher un pourcentage. C'est également le cas dans l'exemple ci-dessus :

De plus, des options encore plus sophistiquées pour la mise en œuvre de métriques dans les Perf-O-Meters sont disponibles dans la documentation de l’API Graphing, par exemple avec les classes Bidirectional et Stacked, qui permettent d’afficher plusieurs Perf-O-Meters en un seul.

Le fichier de graphiques correspondant à ce chapitre est disponible sur GitHub. Ce fichier contient notamment les définitions des métriques pour les quatre valeurs mesurées et les deux valeurs calculées.

Les spécifications de temps absolues (horodatages) sont formatées selon le modèle render.date() ou render.datetime(). Les informations sont toujours fournies en temps Unix, c'est-à-dire en secondes à compter du 1er janvier 1970, 00:00:00 UTC — le début de l'époque Unix. Il s'agit également du format utilisé par la fonction Python time.time().

L'avantage de cette représentation est qu'elle facilite grandement les calculs, par exemple le calcul d'une plage horaire, lorsque les heures de début et de fin sont connues. La formule est alors simplement duration = end - start. Ces calculs fonctionnent indépendamment du fuseau horaire, des changements d'heure d'été ou des années bissextiles.

render.date() ne renvoie que la date ; render.datetime() ajoute l'heure. Le résultat est donné selon le fuseau horaire actuel dans lequel se trouve le serveur Checkmk qui exécute la vérification. Exemples :

Ne soyez pas surpris que render.datetime(0) ne renvoie pas 00:00 comme heure, mais 01:00. Cela s’explique par le fait que nous rédigeons ce guide d’utilisation dans le fuseau horaire de l’Allemagne — qui a une heure d’avance sur l’heure UTC standard (du moins pendant l’heure d’hiver, car le 1er janvier n’est pas en heure d’été).

Pour les plages horaires (ou durées), il existe également la fonction render.timespan(). On lui transmet une durée en secondes et elle la renvoie sous une forme lisible par l’utilisateur. Pour les durées plus longues, les secondes ou les minutes sont omises. Si vous disposez d’une durée dans un objet TimeDelta, utilisez la fonction total_seconds() pour lire le nombre de secondes sous forme de nombre à virgule flottante.

Une fréquence est en fait l'inverse du temps. L'unité canonique est le Hz, ce qui équivaut à 1 / s (l'inverse d'une seconde). Un exemple d'utilisation est la fréquence d'horloge d'un processeur :

En ce qui concerne la mémoire vive, les fichiers, les disques durs, les systèmes de fichiers et autres, l'unité canonique est l'octet. Comme les ordinateurs organisent généralement ces éléments par puissances de deux, par exemple en unités de 512, 1 024 ou 65 536 octets, il a été établi dès le début qu'un kilo-octet n'est pas égal à 1 000, et donc mille fois l'unité, mais à 1 024 (2 à la puissance 10) octets. C'est certes illogique, mais très pratique car cela donne généralement des nombres ronds. Le légendaire Commodore C64 disposait de 64 kilo-octets de mémoire et non de 65 536.

Malheureusement, à un moment donné, les fabricants de disques durs ont eu l’idée de spécifier la capacité de leurs disques par multiples de 1 000. Étant donné que la différence entre 1 000 et 1 024 est de 2,4 % pour chaque taille, et que celles-ci sont multipliées, un disque d’une taille de 1 Go (1 024 fois 1 024 fois 1 024) passe soudainement à 1,07 Go. Cela se vend mieux.

Cette confusion agaçante persiste encore aujourd’hui et continue de générer des erreurs. Pour y remédier, la Commission électrotechnique internationale (CEI) a défini de nouveaux préfixes basés sur le système binaire. En conséquence, aujourd’hui, un kilo-octet correspond officiellement à 1 000 octets et un kibi-octet à 1 024 octets (2 à la puissance 10). De plus, il convient de parler de mébi-octet, de gi-octet et de tébi-octet. Les abréviations sont alors KiB, MiB, GiB et TiB.

Checkmk se conforme à cette norme et vous aide, grâce à un certain nombre de fonctions de rendu personnalisées, à garantir que vous produisez toujours le résultat correct. Il existe par exemple la fonction « render.disksize() », spécialement conçue pour les disques durs et les systèmes de fichiers, qui produit son résultat en puissances de 1 000.

En ce qui concerne la taille des fichiers, il est souvent d'usage de préciser la taille exacte en octets sans arrondi. Cela présente l'avantage de vous permettre de voir très rapidement si un fichier a changé, même de façon minime, ou si deux fichiers sont (probablement) identiques. La fonction « render.filesize() » est utilisée à cet effet :

Si vous souhaitez afficher une valeur qui n'est pas la taille d'un disque dur ou d'un fichier, utilisez simplement la fonction générique render.bytes(). Vous obtiendrez ainsi le résultat sous la forme « classique » des puissances de 1024, selon la notation officielle :

Les professionnels des réseaux ont leurs propres termes et façons d'exprimer les choses. Et comme toujours, Checkmk s'efforce d'adopter la manière conventionnelle de communiquer dans chaque domaine. C'est pourquoi il existe trois fonctions de rendu différentes pour les débits de données et les vitesses. Ce qu'elles ont toutes en commun, c'est que les débits sont exprimés en octets par seconde, même si la sortie réelle est en bits !

render.nicspeed() représente la vitesse maximale d'une carte réseau ou d'un port de commutateur. Comme il ne s'agit pas de valeurs mesurées, il n'est pas nécessaire de les arrondir. Bien qu'aucun port ne puisse envoyer des bits individuels, les données sont exprimées en bits pour des raisons historiques.

Important : vous devez néanmoins également indiquer ici le nombre d'octets par seconde !

render.networkbandwidth() est destiné à une vitesse de transmission réellement mesurée sur le réseau. La valeur d'entrée est à nouveau exprimée en octets par seconde :

Lorsqu’aucun réseau n’est impliqué et que des débits de données sont tout de même générés, on utilise à nouveau les octets. Le cas le plus courant concerne les débits d’E/S des disques durs. On utilise pour cela la fonction « render.iobandwidth() », qui fonctionne avec des puissances de 1 000 dans Checkmk :

La fonction render.percent() représente un pourcentage — arrondi à deux décimales. Elle constitue une exception par rapport aux autres fonctions dans la mesure où elle ne transmet pas la valeur réelle — c'est-à-dire le rapport — mais le pourcentage réel. Par exemple, si quelque chose est à moitié plein, vous n'avez pas à transmettre 0.5 mais 50.

Comme il peut parfois être intéressant de savoir si une valeur est presque nulle ou exactement nulle, les valeurs sont marquées en ajoutant le caractère « < » pour les valeurs supérieures à zéro mais inférieures à 0,01 %.

En conclusion, voici un aperçu de toutes les fonctions de rendu :

Si une exception se produit lors de la surveillance ou de la découverte de services dans l’Setup, l’Summary contient des références au rapport d’incident qui vient d’être créé. Cela ressemblera par exemple à ceci :

En cliquant sur l'icône de l', une page contenant des détails s'affiche, dans laquelle vous :

La traceback vous aide, en tant que développeur, à déterminer s’il s’agit d’une erreur dans le programme (par exemple, l’appel d’une fonction inexistante) ou de données d’agent qui n’ont pas pu être traitées comme prévu. Dans le premier cas, vous devrez corriger l’erreur ; dans le second cas, il est souvent préférable de ne rien faire.

L'envoi du rapport n'est bien sûr utile que pour les plug-ins de vérification qui font officiellement partie de Checkmk. Si vous mettez vos propres plug-ins à la disposition de tiers, vous pouvez demander à vos utilisateurs de vous envoyer les données.

Si vous exécutez votre plug-in de vérification à partir de la ligne de commande, vous ne recevrez aucune indication concernant l'ID d'un rapport de plantage généré. Vous ne verrez que le message d'erreur résumé :

Si vous ajoutez l'option --debug en tant que paramètre d'appel supplémentaire, vous recevrez la trace de l'interpréteur Python :

Si l'erreur ne se reproduit pas lors de votre prochain appel à --debug, par exemple parce qu'une nouvelle sortie d'agent est disponible, vous pouvez également consulter les derniers rapports d'erreur dans le système de fichiers :

Chacun de ces dossiers contient deux fichiers :

Dans les exemples présentés ci-dessus, nous utilisons la fonction `print()` pour afficher le contenu des variables ou la structure des objets à votre intention, en tant que développeur. Ces fonctions de sortie de débogage doivent être supprimées du plug-in de vérification final.

Au lieu de les supprimer, vous pouvez également faire en sorte que votre sortie de débogage ne s'affiche que lorsque le plug-in de vérification est appelé depuis la console en mode débogage. Pour ce faire, importez l'objet debug depuis la boîte à outils Checkmk et, si nécessaire, l'aide au formatage pprint(). Vous pouvez désormais générer une sortie de débogage en fonction de la valeur de l'objet debug :

Veuillez noter que toute sortie de débogage restante doit être utilisée avec parcimonie et se limiter à des indications qui aideront les utilisateurs suivants dans leur débogage. Les erreurs utilisateur évidentes et prévisibles (par exemple, lorsque le contenu de la section agent indique que le plug-in agent a été mal configuré) doivent recevoir la réponse « UNKNOWN » et inclure des notes explicatives dans le résumé.

La question est de savoir comment vous devez réagir si la sortie de l’agent ne se présente pas sous la forme à laquelle vous vous attendiez réellement — qu’elle provienne de l’agent Checkmk ou qu’elle soit reçue via SNMP. Supposons que vous vous attendiez toujours à trois mots par ligne, que devez-vous faire si vous n’en obtenez que deux ?

Eh bien, s’il s’agit d’un comportement autorisé et connu de l’agent, vous devez bien sûr l’intercepter et traiter les cas de figure. Toutefois, si cela n’est pas réellement autorisé, il est préférable d’agir comme si la ligne se composait toujours de trois mots, par exemple avec la fonction d’analyse suivante :

Si une ligne ne comporte pas exactement trois mots, une exception est générée et vous recevez le rapport d'erreur très utile que nous venons de mentionner.

Si vous accédez à des clés d’un dictionnaire dont on s’attend à ce qu’elles manquent occasionnellement, il peut bien sûr être judicieux de réagir en conséquence. Pour ce faire, vous pouvez définir le service sur « CRIT » ou « UNKNOWN » et ajouter une note dans le résumé concernant la sortie de l’agent qui ne peut pas être évaluée. Dans tous les cas, il est préférable d’utiliser la fonction « get() » du dictionnaire à cette fin plutôt que d’intercepter l’exception « KeyError ». En effet, get() renvoie un objet de type None ou un remplacement facultatif à passer en tant que deuxième paramètre si la clé n'est pas disponible :

Que se passe-t-il si l'agent renvoie des données correctes, mais que l'élément à vérifier est manquant ? Comme ceci, par exemple :

Si l'élément que vous recherchez n'est pas présent, la boucle est exécutée et Python se termine simplement à la fin de la fonction sans renvoyer de résultat via yield. Et c'est exactement la bonne approche ! Car Checkmk reconnaît que l'élément à surveiller est manquant et génère le statut correct ainsi qu'un texte standard approprié avec la mention UNKNOWN.

Si vous souhaitez simuler des sorties d'agent particulières, les fichiers du répertoire spool sont très utiles. Vous pouvez les utiliser pour tester des cas limites qui sont autrement difficiles à reproduire. Ou vous pouvez utiliser directement la sortie d'agent qui a conduit à un rapport de plantage pour tester les modifications apportées à un plug-in de vérification.

Commencez par désactiver votre plug-in d'agent habituel, par exemple en révoquant son autorisation d'exécution. Créez ensuite un fichier dans le répertoire /var/lib/check_mk_agent/spool/ contenant la section d'agent (ou les sections d'agent attendues) que votre plug-in de vérification attend, y compris l'en-tête de section, et se terminant par un retour à la ligne. La prochaine fois que l'agent sera appelé, le contenu du fichier spool sera transféré à la place de la sortie du plug-in d'agent.

Avec certains plug-ins de vérification qui utilisent des éléments, il est tout à fait possible que, sur des serveurs de grande taille, plusieurs centaines de services soient générés. Si aucune fonction d'analyse distincte n'est utilisée, cela signifie que la liste entière de centaines de lignes doit être parcourue pour chacun des centaines d'éléments. Le temps nécessaire à la recherche augmente donc proportionnellement au carré du nombre d'éléments répertoriés, ce qui signifie des dizaines de milliers de comparaisons pour des centaines de services. Si, en revanche, la liste imbriquée est transférée dans un dictionnaire, le temps nécessaire à la recherche d'un élément n'augmente que linéairement avec la taille du dictionnaire.

Dans le wiki Python, vous trouverez un aperçu des coûts de recherche dans différents types de données, y compris une explication et la notation O. L'utilisation de la fonction parse réduit la complexité de la recherche de O(n) à O(1).

Comme les anciennes versions de cet article n'utilisaient pas la fonction parse, vous devriez identifier ces plug-ins de vérification et les réécrire pour qu'ils utilisent la fonction parse.