Débuter avec Keen

Ce que nous allons construire

Notre premier programme est un collecteur de 27 lignes. Il demande sa page à un site web, relève le code de réponse et le temps de réponse, puis juge ces deux chiffres. Nous l’écrirons ligne par ligne, et nous nous arrêterons sur chacune.

Quand il tourne, la page de la sonde affiche l’état OK, le code de réponse (200, par exemple) et le temps de réponse en millisecondes. Si le site renvoie une erreur, répond trop lentement ou ne répond plus, l’état change et une phrase explique pourquoi.

Vous n’avez pas besoin de connaître Keen, ni de savoir programmer. Chaque notion sera expliquée au moment où nous en aurons besoin.

Pourquoi Keen

Keen est le langage des collecteurs de banshee. Il ressemble à du PHP réduit à l’essentiel, sans les écritures qui prêtent à confusion. banshee l’a développé pour quatre raisons.

• Une sonde se lit. N’importe qui peut la lire et la comprendre, facilement.
• Aucune dépendance sur les serveurs. Avec des scripts, chaque contrôle apporte ses propres prérequis, à installer et à maintenir sur chaque machine. Un collecteur Keen n’en apporte aucun.
• Un contrôle complet et une même manière de travailler. Tout ce qu’une sonde fait sur sa cible est écrit en clair dans son code. Tous les acteurs écrivent de la même façon, ce qui permet de partager des collecteurs dans la communauté en toute sérénité.
• Moins de risques. Moins de failles de sécurité et moins de serveurs abandonnés : la supervision que tout le monde redoute prend fin.

Cinq mots avant de commencer

Posons d’abord le vocabulaire. Ces cinq mots reviennent partout.

Le master est le serveur central de banshee, celui que vous ouvrez dans votre navigateur. Il garde les collecteurs, la configuration et les résultats.

Le poller est un petit programme installé au plus près de ce que vous surveillez. Il exécute les contrôles. C’est lui qui ouvre la connexion vers le master.

Un hôte est une machine, un équipement ou un site que vous surveillez. Il a sa fiche dans l’inventaire de banshee.

Un collecteur est la recette d’un contrôle. C’est un programme écrit en Keen et gardé sur le master. Il dit comment interroger quelque chose, la cible (ici, un site web), et quelles valeurs en tirer.

Une sonde est un collecteur posé sur un hôte précis, avec ses réglages. Le collecteur est la recette, la sonde est le plat préparé pour cet hôte-là.

Où écrire le code

Il vous faut un master banshee en service et un compte autorisé à écrire des collecteurs, c’est-à-dire avec le droit d’écriture sur la racine / de l’arbre. Pour l’essai final, il faut aussi un poller relié à ce master, un hôte qu’il collecte et l’adresse d’un site à vérifier. Un contrôle HTTP n’a besoin ni de mot de passe ni de clé.

Ouvrez l’écran Collecteurs et cliquez sur « Nouveau collecteur ». Tapez le nom web/https/status, laissez le code vide et validez. Un nom est un chemin dont les segments sont séparés par /. Les dossiers n’existent que par les noms qu’ils contiennent : web et web/https apparaissent tout seuls.

Ouvrez la fiche du collecteur, cliquez sur « Éditer » et choisissez le fichier « Code ». C’est là que nous écrirons le code. Sous le texte, la zone « Problèmes » relit le code à chaque pause de frappe. Quand tout est correct, elle affiche « Aucun problème. ».

Étape 1 : demander sa page au site

Commençons par le geste le plus simple : demander sa page au site. Votre navigateur fait exactement cela quand vous ouvrez une adresse. Cette demande s’appelle une requête GET.

Tapez ces lignes dans le fichier « Code » :

need('protocol:http');

// Demande la page au site.
$answer = http.get('https://www.example/');

La première ligne, need, annonce que le collecteur emploie le protocole HTTP. Le master refuse un appel http.get sans elle. Nous verrons à l’étape 7 ce qu’elle apporte.

Vient ensuite un commentaire. Tout ce qui suit //, jusqu’à la fin de la ligne, est ignoré par banshee. Il n’est là que pour la personne qui relira le code. Prenez l’habitude d’en écrire.

La dernière ligne fait le travail. http.get est une fonction, c’est-à-dire une action qui porte un nom. Ce nom a deux morceaux collés autour d’un point, sans espace : http est le domaine, le protocole employé, et get est la méthode, ce qu’il faut faire. Presque toutes les fonctions de Keen s’écrivent ainsi.

Entre les parenthèses, nous donnons à la fonction ce dont elle a besoin : l’adresse du site. Ce que nous donnons à une fonction s’appelle un argument. Une adresse est un texte, et un texte s’écrit entre apostrophes. À l’étape 3, nous remplacerons cette adresse par un réglage.

À gauche, $answer = range la réponse dans une variable. Une variable est une boîte qui porte un nom. Ce nom commence par $, suivi de lettres minuscules, de chiffres ou de _. Inutile de créer la boîte d’avance : elle existe dès que nous y rangeons quelque chose avec =.

Le point-virgule termine l’instruction. Il en faut un à la fin de chacune.

Que contient $answer ? Un tableau, c’est-à-dire une série de cases qui ont chacune une étiquette. Celui que rend http.get en a quatre :

• status : le code de réponse du site, un nombre. 200 veut dire que tout va bien, 404 que la page n’existe pas.
• headers : les en-têtes de la réponse.
• body : le texte de la page.
• time : le temps de réponse, en millisecondes.

Si le site ne répond pas du tout, http.get arrête le collecteur de lui-même. Nous n’avons rien à écrire pour cela. L’étape 4 montre ce que la sonde en dit.

Étape 2 : rendre le code de réponse

Pour l’instant, la réponse reste enfermée dans le collecteur. Faisons-en sortir le code de réponse, pour que banshee puisse l’afficher et le juger.

Un collecteur remet ses résultats sous forme de valeurs rendues. Pour en rendre une, il faut deux gestes : l’annoncer en tête du code, puis la rendre au bon moment. Ajoutez la première ligne sous la ligne need, avant le commentaire, et la seconde à la fin, sous la ligne $answer :

output('code', 'number', array('label' => 'Code de réponse'));

value('code', $answer['status']);

output annonce la valeur. C’est une déclaration, et les déclarations viennent toujours avant le reste du code : le master refuse une déclaration placée plus bas.

'code' est le nom de la valeur, qui servira à la retrouver. 'number' est sa sorte, ici un nombre. L’autre sorte possible est 'text'.

Le dernier argument, array('label' => 'Code de réponse'), est un tableau comme celui de la réponse, mais écrit par nous. Il ne contient qu’une paire, qui se lit « étiquette => contenu ». L’étiquette label porte le libellé que l’écran affiche devant la valeur.

value('code', $answer['status']) rend la valeur : d’abord le nom annoncé plus haut, ensuite la valeur elle-même.

$answer['status'] va chercher dans le tableau la case qui porte l’étiquette status. Nous écrivons le nom de la variable, puis l’étiquette entre crochets et entre apostrophes.

Une valeur annoncée doit être rendue une fois, et une seule, à chaque passage. Un passage est une exécution complète du collecteur. Sinon, le collecteur s’arrête, et l’étape 4 dit sur quel état.

Voici le code complet à ce stade :

need('protocol:http');

output('code', 'number', array('label' => 'Code de réponse'));

// Demande la page au site.
$answer = http.get('https://www.example/');
value('code', $answer['status']);

Étape 3 : rendre l’adresse réglable

Une adresse écrite dans le code oblige à faire un collecteur par site. Il vaut mieux que chaque sonde porte la sienne : un seul collecteur sert alors autant de sites que vous voulez.

Ajoutez ce bloc dans les déclarations, au-dessus des lignes output, puis remplacez la ligne $answer par la seconde ligne :

$url = variable('web:url', 'text', array(
    'label' => 'Adresse à vérifier',
    'help'  => 'Par exemple https://www.example/.',
));

$answer = http.get($url);

variable déclare un réglage que la sonde fournit. Sur la sonde, il devient un champ à remplir. La fiche du collecteur range ces réglages sous le titre « Arguments ».

$url = range dans une variable la valeur de ce réglage pour l’hôte de la sonde. À chaque passage, $url contient donc l’adresse que l’administrateur a saisie.

'web:url' est le nom du réglage. Il a au moins deux parties, séparées par :, en lettres minuscules. 'text' est sa forme : un champ de texte.

Le dernier argument est un tableau de deux paires, écrit sur plusieurs lignes. En Keen, les retours à la ligne et les espaces ne changent rien : ils servent à la lecture. label est le texte affiché devant le champ, help la phrase qui l’explique.

Dans http.get($url), l’argument est maintenant la variable. Une variable s’écrit sans apostrophes ; avec des apostrophes, ce serait le texte $url.

Ce réglage est obligatoire. Une sonde sans adresse ne peut pas travailler, et banshee le lui fait dire : l’étape 4 montre comment.

Voici le code complet à ce stade :

need('protocol:http');

$url = variable('web:url', 'text', array(
    'label' => 'Adresse à vérifier',
    'help'  => 'Par exemple https://www.example/.',
));

output('code', 'number', array('label' => 'Code de réponse'));

// Demande la page au site.
$answer = http.get($url);
value('code', $answer['status']);

Étape 4 : juger le code de réponse

Jusqu’ici, le collecteur mesure. Apprenons-lui à dire si la mesure est bonne.

C’est le rôle d’une surveillance : une règle de jugement que le collecteur propose, par exemple « le code de réponse doit être 200 ». Le collecteur ne juge pas lui-même. Sur la sonde, l’administrateur coche les surveillances qu’il veut, et le poller juge chaque résultat.

Une surveillance a des seuils, les limites à partir desquelles elle se déclenche. Le code écrit une valeur proposée, et l’administrateur peut la changer sur la sonde sans lire le code.

Le résultat du jugement est un état, un mot qui résume la situation de la sonde. Nous allons les rencontrer un par un.

Ajoutez cette ligne sous les lignes output :

watch.expect('code', 'Réponse en erreur', 'code', array('critical' => array(200)));

watch.expect déclare une surveillance du genre « Valeur attendue ». Elle se déclenche quand la valeur n’est aucune de celles que nous attendons.

Elle prend quatre arguments. Le premier, 'code', est son identifiant : la sonde retient sous ce nom si l’administrateur l’a cochée. Il peut être identique au nom de la valeur, car ce sont deux choses distinctes. Le deuxième, 'Réponse en erreur', est le titre que l’administrateur lit. Le troisième, 'code' encore, désigne la valeur surveillée, celle que l’étape 2 a annoncée. Le quatrième est le tableau d’options.

'critical' => array(200) dit que seul 200 est attendu. array(200) est une liste d’une seule case, ici un nombre, écrit sans apostrophes. critical est le niveau critique, le plus grave. Toute valeur absente de la liste le déclenche.

Ce 200 est un seuil proposé. L’administrateur peut le changer sur la sonde, ou le vider. Un seuil vide veut dire que ce niveau n’est pas jugé.

OK

L’état OK veut dire que tout va bien : aucune surveillance cochée ne se déclenche. Ici, le code de réponse est 200.

CRITICAL

L’état CRITICAL veut dire critique. Ici, le code de réponse est différent de 200. Une redirection (301, par exemple) donne aussi CRITICAL, parce que http.get ne la suit pas. Une erreur du serveur (500, par exemple) aussi : le site a bien répondu, et le collecteur reçoit cette réponse comme une valeur.

UNREACHABLE

L’état UNREACHABLE veut dire injoignable. Il apparaît quand le site ne répond pas du tout : délai dépassé, connexion refusée, nom inconnu. http.get arrête alors le collecteur lui-même, et la sonde prend cet état. Aucune ligne de code n’est nécessaire. Aucune valeur n’est rendue et aucune surveillance n’est jugée.

MISCONFIGURED

L’état MISCONFIGURED veut dire mal configurée. Il apparaît quand le collecteur ne peut pas travailler à cause d’un réglage. C’est le cas d’une sonde sans adresse, puisque ce réglage est obligatoire. C’est aussi le cas d’une valeur annoncée qui n’est pas rendue, ou rendue deux fois.

Chaque état vient avec une phrase qui dit pourquoi.

Voici le code complet à ce stade :

need('protocol:http');

$url = variable('web:url', 'text', array(
    'label' => 'Adresse à vérifier',
    'help'  => 'Par exemple https://www.example/.',
));

output('code', 'number', array('label' => 'Code de réponse'));

watch.expect('code', 'Réponse en erreur', 'code', array('critical' => array(200)));

// Demande la page au site.
$answer = http.get($url);
value('code', $answer['status']);

Étape 5 : mesurer le temps de réponse

Un site peut répondre 200 et mettre cinq secondes à le faire. Ajoutons le temps de réponse, avec sa surveillance.

Trois lignes arrivent, une dans chaque groupe : la première avec les lignes output, la deuxième avec les lignes watch, la troisième à la fin du code.

output('response-time', 'number', array('label' => 'Temps de réponse', 'unit' => 'ms'));

watch.above('slow', 'Site lent', 'response-time', array('warning' => 500, 'critical' => 2000, 'for' => '3 runs'));

value('response-time', $answer['time']);

La ligne output annonce une seconde valeur, sur le modèle de l’étape 2. Le tableau d’options a maintenant deux paires, séparées par une virgule. 'unit' => 'ms' donne l’unité, que l’écran affiche après le nombre. Le tiret de 'response-time' est permis dans un nom de valeur.

La ligne value rend cette valeur. $answer['time'] lit la case time de la réponse, la durée en millisecondes.

watch.above déclare une surveillance du genre « Seuil haut ». Elle se déclenche quand la valeur dépasse un seuil. Ses arguments suivent le même ordre qu’à l’étape 4 : l’identifiant 'slow', le titre 'Site lent', la valeur surveillée 'response-time', puis les options.

'warning' => 500 fixe le premier seuil. Au-delà de 500, l’état devient WARNING, l’avertissement, un niveau moins grave que le critique. Le seuil se franchit strictement : 500 exactement ne déclenche rien. Le nombre est dans l’unité de la valeur surveillée, ici des millisecondes.

'critical' => 2000 fixe le second seuil. Au-delà de 2 000 millisecondes, l’état devient CRITICAL.

'for' => '3 runs' règle la durée. Le texte s’écrit en anglais dans le code : un nombre, une espace, puis runs, les passages. Il demande que le seuil soit franchi pendant trois passages de suite avant que l’état change. Une seule réponse lente ne déclenche rien.

Une sonde porte l’état le plus grave de ses surveillances. Si le code est 200 mais que le temps dépasse 2 000 ms pendant trois passages, la sonde est CRITICAL.

Voici le code complet à ce stade :

need('protocol:http');

$url = variable('web:url', 'text', array(
    'label' => 'Adresse à vérifier',
    'help'  => 'Par exemple https://www.example/.',
));

output('code', 'number', array('label' => 'Code de réponse'));
output('response-time', 'number', array('label' => 'Temps de réponse', 'unit' => 'ms'));

watch.expect('code', 'Réponse en erreur', 'code', array('critical' => array(200)));
watch.above('slow', 'Site lent', 'response-time', array('warning' => 500, 'critical' => 2000, 'for' => '3 runs'));

// Demande la page au site.
$answer = http.get($url);
value('code', $answer['status']);
value('response-time', $answer['time']);

Ce que donne chaque situation :

• code 200 et temps de réponse de 500 ms au plus : OK ;
• temps de réponse au-delà de 500 ms pendant trois passages : WARNING ;
• temps de réponse au-delà de 2 000 ms pendant trois passages : CRITICAL ;
• code différent de 200 : CRITICAL ;
• site qui ne répond pas : UNREACHABLE ;
• adresse non renseignée sur la sonde : MISCONFIGURED.

Étape 6 : chercher un mot dans la page

Jusqu’ici, tout ce que le collecteur juge passe par des surveillances que l’administrateur règle. Voyons comment le code peut décider lui-même.

Un site peut répondre 200 en affichant une page d’erreur. Le code de réponse ne le révèle pas, mais le texte de la page, oui : c’est la case body du tableau. Nous allons chercher un mot dans cette page et, s’il manque, déclarer la sonde critique. Le mot est un second réglage de la sonde, facultatif, parce que tous les sites n’en ont pas besoin.

Ajoutez le premier bloc sous la déclaration de $url, et le second sous la ligne $answer :

$word = variable('web:word', 'text', array(
    'label'    => 'Mot à trouver dans la page',
    'help'     => 'Facultatif. Si la page ne contient pas ce mot, la sonde est critique.',
    'required' => false,
));

if ($word != '' && !text.contains($answer['body'], $word)) {
    fail('critical', 'Mot absent', 'La page ne contient pas le mot ' . $word . '.');
}

Le réglage reprend la forme de l’étape 3. La nouveauté est 'required' => false. Un réglage est obligatoire d’office ; cette option le rend facultatif. false est un booléen, une valeur qui est vraie ou fausse. Ses deux écritures sont true et false, sans apostrophes. Quand la sonde ne donne pas de mot, la variable $word contient un texte vide, ''.

if (…) { … } exécute le code entre accolades seulement si la condition entre parenthèses est vraie. Les accolades sont obligatoires, même pour une seule instruction.

La condition a deux parties. $word != '' est la première. Le signe != veut dire « est différent de », et deux apostrophes collées écrivent un texte vide. Cela se lit « un mot a été renseigné ».

&& veut dire « et » : les deux parties doivent être vraies. Le côté droit n’est même pas lu quand le côté gauche est faux. Son pendant est ||, « ou ».

text.contains($answer['body'], $word) appelle une fonction du domaine text. Elle rend vrai si le premier texte contient le second. Ici, elle cherche le mot dans la page.

Le ! placé devant inverse le résultat. La condition entière se lit donc « un mot est demandé et la page ne le contient pas ».

fail arrête le collecteur sur l’état que nous choisissons. Le premier argument est cet état, écrit tel quel : 'critical', 'misconfigured' ou 'unreachable'. Le deuxième est le résumé du message, le troisième son détail. Un collecteur arrêté par fail ne rend aucune valeur, et aucune surveillance n’est jugée. Cet état-là, c’est le code qui le décide seul : l’administrateur ne règle aucun seuil dessus.

Dans le détail du message, le point . colle des textes les uns aux autres. Cette opération s’appelle la concaténation. Le point s’écrit avec une espace de chaque côté, comme dans '…le mot ' . $word . '.'.

Voici le code complet à ce stade :

need('protocol:http');

$url = variable('web:url', 'text', array(
    'label' => 'Adresse à vérifier',
    'help'  => 'Par exemple https://www.example/.',
));
$word = variable('web:word', 'text', array(
    'label'    => 'Mot à trouver dans la page',
    'help'     => 'Facultatif. Si la page ne contient pas ce mot, la sonde est critique.',
    'required' => false,
));

output('code', 'number', array('label' => 'Code de réponse'));
output('response-time', 'number', array('label' => 'Temps de réponse', 'unit' => 'ms'));

watch.expect('code', 'Réponse en erreur', 'code', array('critical' => array(200)));
watch.above('slow', 'Site lent', 'response-time', array('warning' => 500, 'critical' => 2000, 'for' => '3 runs'));

// Demande la page au site.
$answer = http.get($url);

if ($word != '' && !text.contains($answer['body'], $word)) {
    fail('critical', 'Mot absent', 'La page ne contient pas le mot ' . $word . '.');
}

value('code', $answer['status']);
value('response-time', $answer['time']);

Étape 7 : régler le protocole

Une requête HTTP a ses propres réglages, que banshee connaît déjà. Inutile de les redéclarer avec variable : le collecteur les demande par leur nom.

C’est le rôle de la ligne écrite à l’étape 1, tout en haut du code :

need('protocol:http');

need réclame des réglages qui existent déjà dans banshee. 'protocol:http' désigne ceux du protocole HTTP : le délai d’attente de la requête, l’empreinte d’un certificat épinglé, le nom sous lequel la requête se présente au site (le User-Agent) et la manière de juger la connexion chiffrée (le profil TLS). Ils sont facultatifs, et chacun apparaît sur la sonde comme un champ.

Un collecteur ne reçoit que les réglages qu’il déclare : sans cette ligne, ces champs n’existeraient pas sur la sonde, et la requête suivrait le profil TLS par défaut au lieu de celui que l’administrateur a réglé. C’est pourquoi le master refuse un appel http.get sans elle. need est une déclaration, comme variable et output, et reste donc dans l’en-tête.

Notre collecteur est terminé. Le voici en entier, avec ses 27 lignes :

need('protocol:http');

$url = variable('web:url', 'text', array(
    'label' => 'Adresse à vérifier',
    'help'  => 'Par exemple https://www.example/.',
));
$word = variable('web:word', 'text', array(
    'label'    => 'Mot à trouver dans la page',
    'help'     => 'Facultatif. Si la page ne contient pas ce mot, la sonde est critique.',
    'required' => false,
));

output('code', 'number', array('label' => 'Code de réponse'));
output('response-time', 'number', array('label' => 'Temps de réponse', 'unit' => 'ms'));

watch.expect('code', 'Réponse en erreur', 'code', array('critical' => array(200)));
watch.above('slow', 'Site lent', 'response-time', array('warning' => 500, 'critical' => 2000, 'for' => '3 runs'));

// Demande la page au site.
$answer = http.get($url);

if ($word != '' && !text.contains($answer['body'], $word)) {
    fail('critical', 'Mot absent', 'La page ne contient pas le mot ' . $word . '.');
}

value('code', $answer['status']);
value('response-time', $answer['time']);

Étape 8 : lire les fautes du master

Tout le monde écrit des fautes. Provoquons-en quelques-unes exprès, pour apprendre à les lire.

Keen est plus strict que PHP, volontairement. Le master relit le code à chaque pause de frappe, et une dernière fois à l’enregistrement. Il refuse tout ce qui prête à confusion, et un code qui a une faute ne s’enregistre pas. Chaque faute donne trois informations : la ligne, la colonne et la raison.

Une fonction qui n’existe pas

Ajoutez cette ligne à la fin du code :

$f = file_get_contents('/etc/passwd');

La zone « Problèmes » indique la ligne 28, la colonne 6 et la raison : La fonction « file_get_contents » n’existe pas dans un collecteur. Keen ne connaît que les fonctions de sa liste. Aucune ne lit un fichier du poller, ne lance un programme ni ne sort sur le réseau, hors des fonctions de protocole comme http.get. Retirez la ligne.

Une écriture que Keen retire à PHP

Ajoutez maintenant cette ligne à la place :

$speed = $answer['time'] > 500 ? 'lent' : 'normal';

La raison : « ? : » n’existe pas dans un collecteur : écrivez un if / else. Keen retire quelques écritures de PHP qui doublent une autre écriture ou se lisent mal, et la faute dit toujours par quoi les remplacer. Retirez la ligne.

Un point mal entouré

$label = 'code '.$answer['status'];

La raison : Une concaténation s’écrit avec un blanc de chaque côté du point. Le point a deux sens. Collé à deux noms, il écrit un appel de fonction, comme http.get. Entouré de blancs, il colle deux textes. Retirez la ligne.

Une variable lue avant d’être remplie

value('code', $reponse['status']);

La raison : « $reponse » n’est affectée nulle part avant. Dans notre code, la variable s’appelle $answer ; $reponse n’a jamais reçu de valeur. Une variable doit avoir reçu une valeur plus haut dans le code avant d’être lue. Retirez la ligne.

Ce que Keen retire à PHP

Chaque écriture retirée a son remplaçant :

• ? : s’écrit if … else … ;
• += et ++ s’écrivent $i = $i + 1 ;
• [1, 2] s’écrit array(1, 2) ;
• null s’écrit avec une valeur, ou '' pour « rien » ;
• # et /* … */ s’écrivent //.

Deux autres règles font aussi des fautes. Un nom s’écrit en minuscules : $Answer est refusé. Et une déclaration (need, variable, output, watch) placée après une instruction est refusée.

Étape 9 : essayer le collecteur

Il reste à faire tourner le collecteur pour de vrai. Cela passe par quatre écrans, dans l’ordre.

Dans l’éditeur, saisissez un commentaire facultatif et cliquez sur « Enregistrer ». Le master juge le code une dernière fois. Chaque enregistrement crée une version, une copie numérotée du code qui ne change plus. La dernière est la version courante, celle que les sondes emploient. Rien ne s’efface : revenir en arrière, c’est désigner une ancienne version. Cliquez sur « Fermer » pour revenir à la fiche.

Dans l’inventaire, ouvrez l’hôte et ajoutez-lui une sonde qui emploie le collecteur web/https/status. Renseignez « Adresse à vérifier ». Gardez cochées « Réponse en erreur » et « Site lent », qui le sont d’office, et réglez leurs seuils si besoin.

Sur la machine du poller, un administrateur fait prendre le collecteur avec l’option --update-collectors, suivie du nom du collecteur, par exemple --update-collectors=web/https/status*. Le poller montre les changements et attend sa confirmation.

Ouvrez enfin la page de la sonde. Tant qu’aucun résultat n’est arrivé, elle est dans l’état PENDING, en attente. Puis elle prend l’état que donnent les surveillances. Pour voir les autres états, changez un seuil sur la sonde, ou donnez-lui une adresse qui n’existe pas.

En résumé

Le collecteur complet :

need('protocol:http');

$url = variable('web:url', 'text', array(
    'label' => 'Adresse à vérifier',
    'help'  => 'Par exemple https://www.example/.',
));
$word = variable('web:word', 'text', array(
    'label'    => 'Mot à trouver dans la page',
    'help'     => 'Facultatif. Si la page ne contient pas ce mot, la sonde est critique.',
    'required' => false,
));

output('code', 'number', array('label' => 'Code de réponse'));
output('response-time', 'number', array('label' => 'Temps de réponse', 'unit' => 'ms'));

watch.expect('code', 'Réponse en erreur', 'code', array('critical' => array(200)));
watch.above('slow', 'Site lent', 'response-time', array('warning' => 500, 'critical' => 2000, 'for' => '3 runs'));

// Demande la page au site.
$answer = http.get($url);

if ($word != '' && !text.contains($answer['body'], $word)) {
    fail('critical', 'Mot absent', 'La page ne contient pas le mot ' . $word . '.');
}

value('code', $answer['status']);
value('response-time', $answer['time']);

Ce que nous avons appris en l’écrivant :

• Un code Keen commence par ses déclarations, puis vient le reste. Chaque instruction se termine par un point-virgule, et // ouvre un commentaire.
• Une variable s’écrit $nom et reçoit une valeur avec =. Les valeurs sont des textes, des nombres, des booléens et des tableaux.
• Un tableau s’écrit array(…), en liste ou en paires étiquette => contenu, et se lit avec $a['étiquette'].
• Une fonction s’écrit domaine.méthode. Sept mots, dont value et output, s’écrivent seuls.
• need, variable, output et watch.… déclarent ce que le collecteur demande, rend et surveille. value rend une valeur, et fail arrête le collecteur sur un état.
• if, les comparaisons, &&, || et ! servent à décider. Le point entouré d’espaces colle des textes.
• Une sonde est OK, WARNING, CRITICAL, UNREACHABLE ou MISCONFIGURED. Le master signale chaque faute avec sa ligne, sa colonne et sa raison.

Pour poursuivre, essayez un autre genre de surveillance, comme watch.below, ou écrivez un second collecteur sur le même modèle. Keen sait aussi interroger un équipement en SNMP avec snmp.get, ou en SSH avec ssh.run. Les questions courantes sur Keen et les collecteurs sont dans la FAQ, et l’équipe répond aux autres par le formulaire de contact.