Agente de host

Las sondas comprueban tus servicios desde fuera. El agente comprueba la máquina en sí y muestra lo que solo se ve desde dentro: un disco lleno, un proceso muerto o un host que está vivo pero ya no hace su trabajo. Mide e informa, y no ejecuta nada. Así lo despliegas en hosts de producción sin tener que revisar qué órdenes podría recibir.

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

La tabla está completa: el agente recoge estas medidas del host y nada más.

Instalación

Crea un token de alta en la aplicación, en Agentes de host, luego 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. Inyecta el token desde tu gestor de secretos o con una entrada oculta, y elimina la variable después.

El agente funciona en Linux (x86_64 y aarch64, builds estáticos con musl sin dependencias en ejecución) y en macOS como binario universal. Hay un agente para Windows previsto.

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. En sistemas sin esa capacidad, como el LibreSSL habitual de macOS y distribuciones antiguas, avisa y verifica mediante transporte TLS más SHA-256. Instalador y clave llegan del mismo origen, así que la primera instalación confía en ese origen. Cada autoactualización posterior verifica contra una clave compilada en el agente y falla de forma cerrada, como se explica más abajo.

En Linux, el instalador crea una unidad de systemd, y en macOS un LaunchDaemon. 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 como hash. Un solo uso es lo adecuado para una máquina, un token reutilizable para desplegar una flota. Un token sigue siendo válido hasta que caduca, así que elige una vigencia corta.

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, y 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 (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 aplica al sistema de archivos más lleno. Vigila sistemas de archivos que se llenan: un log que añade 700 MB a un disco de 25 GB mueve la cifra tres puntos, así que un umbral del 90 % sigue en calma. Para avisar sobre un archivo o un directorio que crece, usa un monitor heartbeat.

Perstat evalúa los monitores de agente cada 30 segundos aproximadamente. Informan directamente, sin 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.

Conviene saber, 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í comparten nombre. Los demonios compilados y todo lo que fija su propio nombre de proceso se identifican sin ambigüedad.

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 expresamente, 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 tu historial queda completo tras un corte breve. Esa cola vive en memoria y empieza de cero cuando el agente se reinicia.

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, y sus datos históricos siguen las reglas de retención aplicables.

Quita 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 pausan su evaluación 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. Esos paneles siguen mostrando su última lectura, normalmente en verde, así que cuando un host calla, lee el monitor de disponibilidad.

Para distinguir un host muerto de uno sano que no consigue alcanzar Perstat, acompaña el monitor de disponibilidad con una comprobación externa de la misma máquina. La señal del agente es la llegada de su envío, así que desde su lado los dos casos se parecen.

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 expresamente y se limita a nombres. El agente mide el host e informa del resultado, y todo su alcance cabe en la tabla de Qué mide.

Tampoco ejecuta nada. No hay canal de órdenes remotas, ni gancho para scripts, ni forma de que nadie en Perstat haga correr algo en tu máquina.

Conviene saber

• Los monitores de servicio comprueban procesos. La comprobación responde “¿hay vivo un proceso con este nombre?”. Una unidad fallida con un proceso residual, un proceso colgado o los reinicios en bucle dentro del periodo de gracia parecen por tanto sanos. Para los servicios críticos, añade una comprobación externa o un heartbeat que pruebe lo que el servicio entrega.
• Las mediciones propias van por heartbeats. Para avisar sobre una cifra que solo conoce el host, usa 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. El endpoint 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.

Siguientes pasos

• Agentes en una flota: despliega el agente en muchas máquinas a la vez.
• API: gestiona los agentes y sus monitores con una clave de API.