Agent hôte

Les sondes vérifient vos services depuis l’extérieur. L’agent vérifie la machine elle-même et montre ce que seul l’intérieur révèle : un disque plein, un processus mort ou un hôte qui tourne sans plus faire son travail. Il mesure et remonte, et il n’exécute rien. Vous le déployez ainsi sur des hôtes de production sans avoir à vérifier quelles commandes il pourrait recevoir.

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

Le tableau est complet : l’agent collecte ces mesures sur l’hôte, et rien d’autre.

Installation

Créez un jeton d’enrôlement dans l’application, sous Agents hôtes, puis 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. Injectez le jeton depuis votre gestionnaire de secrets ou par une saisie masquée, puis retirez la variable.

L’agent tourne sous Linux (x86_64 et aarch64, builds statiques musl sans dépendance d’exécution) et sous macOS en binaire universel. Un agent Windows est prévu.

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. Sur les systèmes sans cette capacité, comme le LibreSSL courant de macOS et d’anciennes distributions, il avertit et vérifie via le transport TLS plus SHA-256. L’installeur et la clé viennent de la même origine, la première installation fait donc confiance à cette origine. Chaque mise à jour automatique ultérieure vérifie contre une clé compilée dans l’agent et échoue de façon fermée, comme décrit plus bas.

Sous Linux, l’installeur met en place une unité systemd, sous macOS un LaunchDaemon. 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é sous forme de condensat. L’usage unique convient à une machine, un jeton réutilisable à un déploiement de flotte. Un jeton reste valable jusqu’à son expiration, choisissez donc une durée courte.

Le jeton lui-même est opaque. L’organisation et le projet auxquels il appartient sont résolus côté serveur et jamais interprétés par l’agent.

Les monitors que vous pouvez bâtir dessus

Un agent remonte, et 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 avis dans l’application). notify_push active la notification push.

Un seul monitor de disque couvre tous les points de montage, puisque le seuil s’applique au système de fichiers le plus rempli. Il surveille les systèmes de fichiers qui se remplissent : un journal qui ajoute 700 Mo sur un disque de 25 Go déplace le chiffre de trois points, et un seuil à 90 % reste donc silencieux. Pour alerter sur un fichier ou un répertoire qui grossit, utilisez un monitor heartbeat.

Perstat évalue les monitors d’agent toutes les 30 secondes environ. Ils remontent directement, sans 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.

Bon à savoir 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 partagent donc un nom. Les démons compilés et tout ce qui définit son propre nom de processus sont identifiés sans ambiguïté.

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 laisse votre historique complet. Cette file réside en mémoire et repart de zéro 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, et leurs données historiques suivent les règles de rétention applicables.

Retirez 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 suspendent leur évaluation 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. Ces tuiles continuent d’afficher leur dernière valeur, généralement au vert : quand un hôte se tait, lisez donc le monitor de disponibilité.

Pour distinguer un hôte mort d’un hôte sain qui n’arrive pas à joindre Perstat, associez au monitor de disponibilité une vérification externe de la même machine. Le signal de l’agent est l’arrivée de sa remontée, et de son point de vue les deux cas se ressemblent.

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. L’agent mesure l’hôte et remonte le résultat, et tout son périmètre tient dans le tableau de la section Ce qu’il mesure.

Il n’exécute rien non plus. Il n’existe aucun canal de commande à distance, aucun point d’accroche pour un script, et personne chez Perstat n’a de moyen de faire tourner quoi que ce soit sur votre machine.

Bon à savoir

• Les monitors de service vérifient des processus. 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é ou des redémarrages en boucle dans la période de grâce paraissent donc en bonne santé. Pour les services critiques, ajoutez une vérification externe ou un heartbeat qui teste ce que le service fournit.
• Les mesures propres passent par les heartbeats. Pour alerter sur un chiffre que seul l’hôte connaît, utilisez un monitor heartbeat : 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. Le point d’entrée 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.

Pour aller plus loin

• Agents sur une flotte : déployer l’agent sur de nombreuses machines à la fois.
• API : gérer les agents et leurs monitors avec une clé API.