Agente de host

Las sondas comprueban tus servicios desde fuera. El agente comprueba la máquina en sí, y esa es la única manera de ver un disco lleno, un proceso muerto o un host que está vivo pero ya no hace su trabajo. Su alcance es deliberadamente estrecho: mide e informa, y no ejecuta nada por ti.

Qué mide

Cada 15 segundos, en el host:

Medida	Detalle
CPU	Uso total, de 0 a 100
Carga media	1, 5 y 15 minutos (solo Unix)
Memoria y swap	usada, total, porcentaje
Disco	cada sistema de archivos montado, usado y total y porcentaje
Tiempo encendido	segundos desde el arranque
Servicios	por cada proceso vigilado: activo, número de procesos, CPU, memoria residente

Ningún contador de red, ningún desglose por núcleo, ninguna temperatura. Nada del host que no esté en esa tabla.

Instalación

Crea un token de alta en la aplicación, en Agentes de host, Nuevo agente. Te entrega un comando listo para usar:

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

La asignación de entorno mantiene el token fuera de los argumentos ordinarios y de la lista de procesos. Un comando pegado literalmente en un shell interactivo sí puede acabar en su historial; usa tu gestor de secretos o una entrada/política de historial específica del shell y elimina la variable después.

Hoy están soportados Linux en x86_64 y aarch64 (builds estáticos con musl, sin dependencias en ejecución) y macOS como binario universal. Windows todavía no existe.

El instalador detecta sistema y arquitectura, descarga el binario y comprueba SHA-256. Con OpenSSL 3 capaz de Ed25519 también verifica la firma contra la clave del script. Sin esa capacidad, incluidos el LibreSSL habitual de macOS y distribuciones antiguas, avisa y recurre a transporte TLS más SHA-256. Como instalador y clave llegan del mismo origen, la primera instalación sigue dependiendo de confiar en ese origen. La autoactualización posterior usa una clave compilada y falla de forma cerrada, como se explica más abajo.

En macOS instala un LaunchDaemon en su lugar. Con PERSTAT_NO_SERVICE=1 obtienes el binario sin servicio.

Volver a ejecutarlo es seguro. Si el host ya está dado de alta, el instalador pasa a modo actualización: renueva el binario y el servicio, conserva la identidad existente y no necesita token. Ejecutar la misma línea desde tu gestión de configuración en cada host y en cada pasada es el uso previsto. Para más de un puñado de máquinas, mira agentes en una flota.

Tokens de alta

Propiedad	Por defecto	Rango
Vigencia	24 horas	de 1 a 720 horas
Un solo uso	sí	se puede hacer reutilizable

El token se muestra una única vez y se guarda solo como hash. Un solo uso es lo adecuado para una máquina, un token reutilizable para desplegar una flota. Los tokens no se pueden retirar antes de que caduquen, así que elige una vigencia corta antes que una larga.

El token en sí es opaco. A qué organización y a qué proyecto pertenece se resuelve en el servidor y el agente nunca lo interpreta.

Monitores que puedes montar sobre él

Un agente informa; un monitor decide qué merece un incidente. Crea monitores de tipo agent y vincúlalos al agente. Un monitor observa un valor:

metric	Campos	Salta cuando
availability	grace_seconds (por defecto 180, rango de 60 a 3600)	El host lleva más que el periodo de gracia sin enviar nada
cpu	threshold (por defecto 90)	CPU por encima del umbral
mem	threshold (por defecto 90)	Memoria por encima del umbral
disk	threshold (por defecto 90)	El sistema de archivos más lleno por encima del umbral
service	service_name, grace_seconds (por defecto 120, rango de 60 a 3600)	El proceso lleva más que el periodo de gracia ausente

Dos ajustes valen para todos. breach_severity es down (abre un incidente, avisa a la guardia, aparece en las páginas de estado) o degraded (solo un aviso dentro de la aplicación). notify_push activa la notificación push.

Un solo monitor de disco cubre todos los puntos de montaje, porque el umbral se evalúa contra el sistema de archivos más lleno. Fíjate en qué atrapa y qué no: ve un sistema de archivos que se llena, no un archivo suelto que crece. Un log que añade 700 MB a un disco de 25 GB mueve la cifra tres puntos y no llega a un umbral del 90 %.

Los monitores de agente se evalúan en nuestro lado cada 30 segundos aproximadamente. No llevan regiones de comprobación ni quórum, así que una sola evaluación en exceso abre el incidente en cuanto pasa el periodo de gracia.

Vigilar servicios

service_name es un nombre de proceso, no una unidad de systemd. El agente recorre la lista de procesos y casa de tres formas: por el nombre exacto del proceso, por el nombre exacto del archivo ejecutable (que es lo que hace que funcionen tanto postgres como postmaster) y por el recorte a 15 caracteres de Linux. En Linux se distingue mayúsculas de minúsculas.

Eso tiene una consecuencia que conviene conocer antes de configurarlo. Un servicio que arranca como script aparece en la lista de procesos como python3, sh o node, así que dos servicios así no se distinguen por el nombre. Los demonios compilados y todo lo que fija su propio nombre de proceso no dan problema.

Para ver los nombres reales, ejecuta ps -eo comm= | sort -u en el host, o activa el inventario de procesos para ese agente. Hay que activarlo a propósito, viene desactivado, y transmite solo nombres de procesos y de ejecutables, sin duplicados y con un tope, nunca líneas de comando, rutas, usuarios ni PID. Con él activado, el formulario del monitor sugiere nombres en lugar de pedirte que los escribas.

El agente solo recorre la lista de procesos si existe al menos un monitor de servicio para él.

Red y cortafuegos

Solo salida. El agente nunca abre un socket a la escucha. No hay ninguna regla de entrada que escribir ni ningún puerto que exponer, y la unidad de systemd restringe familias de direcciones y llamadas al sistema en consecuencia.

Hacia fuera, por HTTPS en el puerto 443, a dos nombres:

Host	Para qué
api.perstat.io	alta, mediciones, consulta de configuración
agent.perstat.io	instalador, binarios, descargas de autoactualización

Ambos tienen que resolverse. En una máquina que ejecuta un servidor de nombres autoritativo y no un resolutor, asegúrate de que hay un resolutor utilizable configurado.

Ritmos

Medición cada 15 segundos, envío por lotes cada 60 segundos, consulta de la configuración cada 5 minutos aproximadamente. La primera medición sale inmediatamente después del alta, así que un host nuevo aparece en segundos.

Si un envío falla, las mediciones se acumulan en memoria (unas seis horas) y salen cuando vuelve la conexión, de modo que un corte breve no deja un hueco en tu historial. Esa cola no sobrevive a un reinicio del agente.

Una consecuencia de la consulta cada 5 minutos: después de crear un monitor de servicio pueden pasar unos minutos hasta que el agente vigile ese proceso. Hasta que llegan datos reales, el monitor se queda pendiente en lugar de saltar, así que un monitor recién creado nunca genera una falsa alarma.

Autoactualización

El agente se mantiene al día solo. Las versiones van firmadas con ed25519, la clave de firma se queda fuera de línea y el agente verifica la firma contra una clave compilada en su propio binario antes de cambiar nada. Es fail-closed: lo que no se puede verificar no se instala, y una versión inferior nunca entra. El cambio ocurre dentro del directorio propio del agente y no necesita root.

Pon DATARGO_AGENT_NO_SELFUPDATE=1 en el entorno del servicio si prefieres llevar tú las versiones.

Quitar un agente

Quita la identidad con el icono de papelera del agente. Esto revoca su token, archiva los monitores vinculados al agente y resuelve sus incidentes abiertos. Los monitores archivados liberan plazas del plan, mientras sus datos históricos permanecen.

Quitar el software en el host:

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

Para y elimina el servicio, borra el binario, el estado y el usuario de servicio y da de baja el host. Si la máquina ya no existe, basta con quitar la identidad en el cockpit.

Cuando un agente calla

Conviene entenderlo con precisión, porque decide lo que ves.

El monitor de disponibilidad salta: el silencio más allá de su periodo de gracia abre un incidente. Es el monitor que te dice que un host ha desaparecido, y la razón para darle uno a cada agente.

Los demás monitores dejan de evaluarse por completo en cuanto el último envío tiene más de 180 segundos. No escriben comprobaciones, así que no abren ni cierran nada, y por eso un host muerto produce un incidente y no uno por valor. La otra cara: esos paneles siguen mostrando su última lectura, normalmente en verde. Cuando un host calla, lee el monitor de disponibilidad y no los paneles.

Una distinción que todavía no hacemos: una máquina muerta y una máquina sana que no consigue alcanzarnos producen la misma señal, porque la marca de tiempo con la que trabajamos es la de la recepción. Si esa diferencia te importa, acompaña el monitor de disponibilidad con una comprobación externa de la misma máquina.

Minimización de datos

El agente nunca recoge líneas de comando, variables de entorno ni nombres de usuario. El inventario de procesos hay que activarlo a propósito y se limita a nombres. Mide el host y envía el resultado; no es una herramienta de inventario ni de análisis forense, y ese alcance corto es precisamente la idea.

Tampoco ejecuta nada. No hay canal de órdenes remotas, ni gancho para scripts, ni forma de que nosotros hagamos correr algo en tu máquina. Es un límite deliberado y no una función que aún no hayamos construido.

Límites de hoy

• Windows no existe. Llegará al changelog cuando exista de verdad.
• El estado de una unidad de systemd no se lee. La comprobación responde “¿hay vivo un proceso con este nombre?”, así que una unidad fallida con un proceso residual, un proceso colgado y los reinicios en bucle dentro del periodo de gracia parecen todos sanos.
• Tus propias mediciones no se pueden enviar por el agente. Si necesitas avisar sobre una cifra que solo conoce el host, lo cubre un monitor heartbeat: cada uno tiene un endpoint sano (/ping/<token>) y uno de fallo (/ping/<token>/fail), y un temporizador en el host decide a cuál llama. Llamar al de fallo hace saltar el monitor en la siguiente evaluación, sin esperar a que pase el periodo. Eso cubre lo que un umbral en porcentaje no puede expresar, como un recuento que ha bajado o un directorio que ha crecido.
• Un monitor por valor. Vigilar cuatro procesos en un host son cuatro monitores.