Agent hôte

Les sondes vérifient vos services depuis l’extérieur. L’agent vérifie la machine elle-même, et c’est le seul moyen de voir un disque plein, un processus mort ou un hôte qui tourne sans plus faire son travail. Son périmètre est délibérément étroit : il mesure et remonte, et il n’exécute rien pour vous.

Ce qu’il mesure

Toutes les 15 secondes, sur l’hôte :

Mesure	Détail
CPU	Utilisation totale, 0 à 100
Charge moyenne	1, 5 et 15 minutes (Unix uniquement)
Mémoire et swap	utilisée, totale, pourcentage
Disque	chaque système de fichiers monté, utilisé et total et pourcentage
Uptime	secondes depuis le démarrage
Services	pour chaque processus surveillé : actif, nombre de processus, CPU, mémoire résidente

Aucun compteur réseau, aucun détail par cœur, aucune température. Rien sur l’hôte qui ne figure dans ce tableau.

Installation

Créez un jeton d’enrôlement dans l’application, sous Agents hôtes, Nouvel agent. Vous recevez une commande prête à l’emploi :

PERSTAT_TOKEN=psag_… sh -c "$(curl -fsSL https://agent.perstat.io/install.sh)"

L’affectation par l’environnement garde le jeton hors des arguments ordinaires et de la liste des processus. Une commande collée littéralement dans un shell interactif peut toutefois finir dans son historique ; utilisez votre gestionnaire de secrets ou une saisie/règle d’historique propre au shell, puis retirez la variable.

Sont pris en charge aujourd’hui : Linux sur x86_64 et aarch64 (builds statiques musl, sans dépendance d’exécution) et macOS en binaire universel. Windows n’existe pas encore.

L’installeur détecte le système et l’architecture, télécharge le binaire et contrôle SHA-256. Avec OpenSSL 3 capable d’Ed25519, il vérifie aussi la signature contre la clé du script. Sans cette capacité, notamment avec le LibreSSL courant de macOS et d’anciennes distributions, il avertit puis se rabat sur TLS plus SHA-256. Puisque l’installeur et la clé viennent de la même origine, la première installation dépend encore de la confiance dans cette origine. La mise à jour automatique utilise ensuite une clé compilée et échoue de façon fermée, comme décrit plus bas.

Sous macOS, un LaunchDaemon est installé à la place. Avec PERSTAT_NO_SERVICE=1 vous obtenez le binaire sans service.

Relancer la commande est sans danger. Si l’hôte est déjà enrôlé, l’installeur passe en mode mise à jour : il rafraîchit le binaire et le service, conserve l’identité existante et n’a besoin d’aucun jeton. Exécuter la même ligne à chaque passage de votre gestion de configuration, sur chaque hôte, est l’usage prévu. Pour plus d’une poignée de machines, voir agents sur une flotte.

Les jetons d’enrôlement

Propriété	Défaut	Plage
Durée de vie	24 heures	1 à 720 heures
Usage unique	oui	peut être rendu réutilisable

Le jeton est affiché une seule fois et stocké uniquement sous forme de condensat. L’usage unique convient à une machine, un jeton réutilisable à un déploiement de flotte. Les jetons ne peuvent pas être retirés avant leur expiration, préférez donc une durée courte à une durée longue.

Le jeton lui-même est opaque. À quelle organisation et à quel projet il appartient est résolu côté serveur et jamais interprété par l’agent.

Les monitors que vous pouvez bâtir dessus

Un agent remonte ; un monitor décide de ce qui mérite un incident. Créez des monitors de type agent et rattachez-les à l’agent. Un monitor surveille un indicateur :

metric	Champs	Se déclenche quand
availability	grace_seconds (défaut 180, plage 60 à 3600)	L’hôte n’a plus rien remonté au-delà de la période de grâce
cpu	threshold (défaut 90)	CPU au-dessus du seuil
mem	threshold (défaut 90)	Mémoire au-dessus du seuil
disk	threshold (défaut 90)	Le système de fichiers le plus rempli au-dessus du seuil
service	service_name, grace_seconds (défaut 120, plage 60 à 3600)	Le processus est absent au-delà de la période de grâce

Deux réglages valent pour tous. breach_severity vaut down (ouvre un incident, alerte l’astreinte, apparaît sur les pages de statut) ou degraded (un simple avis dans l’application). notify_push active la notification push.

Un seul monitor de disque couvre tous les points de montage, puisque le seuil est évalué sur le système de fichiers le plus rempli. Notez ce qu’il attrape et ce qu’il n’attrape pas : il voit un système de fichiers qui se remplit, pas un fichier isolé qui grossit. Un journal qui ajoute 700 Mo sur un disque de 25 Go déplace le chiffre de trois points et ne franchira pas un seuil à 90 %.

Les monitors d’agent sont évalués chez nous toutes les 30 secondes environ. Ils ne portent ni région de contrôle ni quorum, une seule évaluation en dépassement ouvre donc l’incident dès que la période de grâce est passée.

Surveiller des services

service_name est un nom de processus, pas une unité systemd. L’agent parcourt la liste des processus et fait correspondre de trois manières : le nom exact du processus, le nom exact du fichier exécutable (c’est ce qui fait fonctionner à la fois postgres et postmaster), et la troncature à 15 caractères de Linux. La casse est significative sous Linux.

Cela a une conséquence à connaître avant de configurer. Un service qui démarre sous forme de script apparaît dans la liste des processus comme python3, sh ou node, deux services de ce genre ne peuvent donc pas être distingués par leur nom. Les démons compilés et tout ce qui définit son propre nom de processus ne posent pas de problème.

Pour voir les vrais noms, lancez ps -eo comm= | sort -u sur l’hôte, ou activez l’inventaire des processus pour cet agent. Il s’active explicitement, il est désactivé par défaut, et il ne transmet que des noms de processus et d’exécutables, dédupliqués et plafonnés, jamais de lignes de commande, de chemins, d’utilisateurs ni de PID. Une fois activé, le formulaire du monitor propose des noms au lieu de vous les faire saisir.

L’agent ne parcourt la liste des processus que si au moins un monitor de service existe pour lui.

Réseau et pare-feu

Sortant uniquement. L’agent n’ouvre jamais de socket en écoute. Il n’y a aucune règle entrante à écrire ni aucun port à exposer, et l’unité systemd restreint les familles d’adresses et les appels système en conséquence.

En sortie, en HTTPS sur le port 443, vers deux noms :

Hôte	Usage
api.perstat.io	enrôlement, mesures, interrogation de la configuration
agent.perstat.io	installeur, binaires, mises à jour automatiques

Les deux doivent pouvoir être résolus. Sur une machine qui fait tourner un serveur de noms faisant autorité plutôt qu’un résolveur, assurez-vous qu’un résolveur utilisable est configuré.

Cadences

Mesure toutes les 15 secondes, envoi groupé toutes les 60 secondes, interrogation de la configuration toutes les 5 minutes environ. La première mesure part immédiatement après l’enrôlement, un nouvel hôte apparaît donc en quelques secondes.

Si un envoi échoue, les mesures s’accumulent en mémoire (environ six heures) et partent au retour de la connexion, une coupure brève ne laisse donc pas de trou dans votre historique. Cette file ne survit pas au redémarrage de l’agent.

Une conséquence de l’interrogation toutes les 5 minutes : après avoir créé un monitor de service, il peut s’écouler quelques minutes avant que l’agent surveille ce processus. Tant que de vraies données ne sont pas arrivées, le monitor reste en attente au lieu de se déclencher, un monitor fraîchement créé ne provoque donc jamais de fausse alerte.

Mise à jour automatique

L’agent se tient à jour lui-même. Les versions sont signées en ed25519, la clé de signature reste hors ligne, et l’agent vérifie la signature contre une clé compilée dans son propre binaire avant de remplacer quoi que ce soit. Il est fail-closed : ce qui ne peut pas être vérifié n’est pas installé, et une version inférieure n’est jamais retenue. Le remplacement a lieu dans le répertoire propre à l’agent et ne demande aucun droit root.

Mettez DATARGO_AGENT_NO_SELFUPDATE=1 dans l’environnement du service si vous préférez piloter les versions vous-même.

Retirer un agent

Retirez l’identité avec l’icône de corbeille sur l’agent. Cela révoque son jeton, archive les monitors liés à cet agent et résout leurs incidents ouverts. Les monitors archivés libèrent leurs places dans la formule, tandis que leurs données historiques restent.

Retirer le logiciel sur l’hôte :

curl -fsSL https://agent.perstat.io/uninstall.sh | sudo sh

Cela arrête et supprime le service, efface le binaire, l’état et l’utilisateur de service, puis désinscrit l’hôte. Si la machine a déjà disparu, retirer l’identité dans le Cockpit suffit.

Quand un agent se tait

Cela mérite d’être compris précisément, parce que cela décide de ce que vous voyez.

Le monitor de disponibilité se déclenche : un silence au-delà de sa période de grâce ouvre un incident. C’est le monitor qui vous dit qu’un hôte a disparu, et c’est la raison d’en donner un à chaque agent.

Les autres monitors ne sont plus évalués du tout dès que la dernière remontée date de plus de 180 secondes. Ils n’écrivent aucun contrôle, ils n’ouvrent donc et ne ferment rien, ce qui explique qu’un hôte mort produise un incident et non un par indicateur. Le revers : ces tuiles continuent d’afficher leur dernière valeur, généralement au vert. Quand un hôte se tait, lisez le monitor de disponibilité, pas les tuiles.

Une distinction que nous ne faisons pas encore : un hôte mort et un hôte en bonne santé qui n’arrive pas à nous joindre produisent le même signal, parce que l’horodatage sur lequel nous travaillons est celui de la réception. Si cette différence compte pour vous, associez au monitor de disponibilité une vérification externe de la même machine.

Minimisation des données

L’agent ne collecte jamais de lignes de commande, de variables d’environnement ni de noms d’utilisateur. L’inventaire des processus s’active explicitement et se limite aux noms. Il mesure l’hôte et remonte le résultat ; ce n’est ni un outil d’inventaire ni un outil d’analyse forensique, et ce périmètre étroit est justement l’idée.

Il n’exécute rien non plus. Il n’existe aucun canal de commande à distance, aucun point d’accroche pour un script et aucun moyen pour nous de faire tourner quoi que ce soit sur votre machine. C’est une limite voulue et non une fonctionnalité que nous n’aurions pas encore construite.

Limites actuelles

• Windows n’est pas livré. Cela figurera au changelog quand ce sera réel.
• L’état d’une unité systemd n’est pas lu. La vérification répond « un processus de ce nom est-il vivant », une unité en échec avec un processus résiduel, un processus bloqué et des redémarrages en boucle à l’intérieur de la période de grâce paraissent donc tous en bonne santé.
• Vos propres mesures ne peuvent pas être remontées par l’agent. Si vous voulez alerter sur un chiffre que seul l’hôte connaît, un monitor heartbeat le couvre : chacun dispose d’un point d’entrée sain (/ping/<token>) et d’un point d’entrée d’échec (/ping/<token>/fail), et une minuterie sur l’hôte choisit lequel appeler. Appeler celui d’échec fait basculer à la prochaine évaluation, sans attendre la fin de la période. Cela couvre ce qu’un seuil en pourcentage ne peut pas exprimer, par exemple un compte qui a chuté ou un répertoire qui a grossi.
• Un monitor par indicateur. Surveiller quatre processus sur un hôte, c’est quatre monitors.