Agentes APM
Instala el agente APM en un servidor Linux o Windows, instrumenta sus aplicaciones (también servicios de Windows e IIS), actualízalo sin reinstalar, revisa su estado y revócalo o quítalo cuando ya no
En esta página
- Antes de empezar
- Crear el comando de instalación
- Instalar el agente en el servidor
- Instrumentar una aplicación
- Observar una aplicación sin instrumentarla (eBPF)
- Instalar el agente en Windows
- Instrumentar un servicio de Windows o IIS
- Desinstalar el agente de Windows
- Qué se obtiene
- Ver el estado
- Actualizar un agente
- Crear un token nuevo para un agente
- Revocar un agente
- Quitar un agente
- Relacionado
Un agente APM recibe la telemetría de las aplicaciones de un servidor y la envía a ARGUNIS con un certificado propio de ese agente. En Configuración → APM → Agentes APM creas el comando con que se instala, ves los pasos para instrumentar cada aplicación, lo actualizas cuando hay una versión nueva, revisas si está conectado y lo revocas o quitas.
Antes de empezar
Tu plan debe incluir el módulo APM y el APM debe estar activo. Ver Activar el APM.
Para ver la lista necesitas Operar en el módulo APM. Para crear tokens, actualizar, revocar o quitar necesitas Administrar.
Un servidor Linux con systemd (x64 o arm64) con alguien que pueda usar
sudo, o un Windows Server 2016 o posterior (x64) con alguien que pueda abrir PowerShell como Administrador.
Si la página muestra un aviso arriba de la lista (por ejemplo, que el APM no está activo), no se pueden crear tokens hasta resolverlo.
ARGUNIS no instala, instrumenta ni reinicia nada por su cuenta en tus servidores. Los comandos de esta página los corre el administrador del servidor cuando decide hacerlo.
Crear el comando de instalación
Entra a Configuración → APM → Agentes APM.
Presiona Nuevo agente APM.
Escribe un Nombre que identifique el servidor o el sistema (por ejemplo, el nombre del servidor y su ambiente). No puede repetir el de otro agente.
Presiona Crear.
Copia el comando con Copiar comando de instalación y guárdalo en un lugar seguro: lleva el token del agente. Debajo aparece la Conexión del agente: la dirección donde se enrola, a dónde enviará y la huella de la autoridad. Luego presiona Listo.
El comando se muestra una sola vez, su token sirve para instalar un solo agente y vence a las 24 horas. Si se pierde o vence, crea uno nuevo (abajo).
Instalar el agente en el servidor
Entra al servidor Linux donde corren las aplicaciones, con un usuario que pueda usar
sudo.Pega y ejecuta el comando que copiaste. Tiene esta forma:
curl -fsSL 'https://<tu ARGUNIS>/apm-agent/v1/install.sh' | sudo sh -s -- --token 'jaa_…'Espera el mensaje Agente APM … instalado y corriendo.
El instalador comprueba la firma del agente antes de instalar nada, crea un usuario de sistema propio para el agente, lo enrola con el token (la llave del certificado se genera en tu servidor y nunca sale de él) y lo deja como servicio que arranca solo. En pocos minutos el agente aparece conectado en la lista.
En un ARGUNIS instalado en tu red con un certificado propio, el comando que muestra la pantalla ya viene armado para eso: baja el instalador, comprueba su huella y le pasa el certificado de tu autoridad (--server-ca). Úsalo tal cual.
Instrumentar una aplicación
Cada aplicación que quieras ver en el APM se instrumenta una vez, con su servicio de systemd. En Configuración → APM → API key y SDK, sección Instrumentar una aplicación con el agente APM, elige el lenguaje (Java, .NET, Node.js o Python) para ver sus pasos exactos.
Si el lenguaje lo pide, prepara la aplicación:
Node.js: en la carpeta de la aplicación,
npm install @opentelemetry/api @opentelemetry/auto-instrumentations-node.Python: en el entorno de la aplicación,
pip install opentelemetry-distro opentelemetry-exporter-otlp && opentelemetry-bootstrap -a install.Java y .NET: nada; el agente descarga y verifica lo necesario.
En el servidor, ejecuta el comando con el nombre del servicio, su entorno y su versión:
sudo argunis-apm-agent --instrumentar facturacion.service --lenguaje java --env produccion --version 1.4.2Solo en Python: agrega
opentelemetry-instrumentdelante del comando de inicio del servicio.Reinicia el servicio cuando te acomode (por ejemplo, en una ventana de mantenimiento):
sudo systemctl restart facturacion.serviceEl comando deja la configuración lista pero no reinicia la aplicación: empieza a enviar después de que tú la reinicies.
Para dejar de instrumentarla, ejecuta sudo argunis-apm-agent --desinstrumentar facturacion.service y reinicia el servicio.
Observar una aplicación sin instrumentarla (eBPF)
Si una aplicación de un servidor Linux no se puede instrumentar (un programa sin código fuente, un binario antiguo o un lenguaje sin agente), el agente puede observarla desde el sistema operativo con eBPF, usando OpenTelemetry eBPF Instrumentation (OBI). Ve sus peticiones HTTP y gRPC y sus consultas a bases de datos (MySQL, PostgreSQL, SQL Server, Redis, MongoDB), Kafka y otras, sin tocar la aplicación ni reiniciarla. Viene apagado: lo activa el administrador del servidor.
Necesitas un servidor Linux con kernel 5.8 o superior (o Red Hat Enterprise Linux 8 y sus derivados) que exponga BTF, como las distribuciones actuales (Ubuntu 20.10+, Debian 11+, RHEL 8.2+), y el agente APM ya instalado. Si el servidor no cumple, el comando lo dice y no activa nada.
Elige qué observar: los programas que escuchan en ciertos puertos o un ejecutable por su nombre.
En el servidor, ejecuta uno de estos comandos:
sudo argunis-apm-agent --ebpf activar --puertos 80,443,8080 --env produccion
sudo argunis-apm-agent --ebpf activar --proceso facturador --env produccionEspera el mensaje eBPF activado. En unos minutos la aplicación aparece en APM → Servicios con el nombre de su ejecutable.
Para revisarlo, ejecuta sudo argunis-apm-agent --ebpf estado; para cambiar qué observa, vuelve a correr --ebpf activar con otros puertos o proceso; para apagarlo, sudo argunis-apm-agent --ebpf desactivar.
Con eBPF se ven la tasa, los errores y la latencia de cada petición y de sus llamadas, pero no lo que pasa dentro del código (funciones, excepciones con su detalle) ni las peticiones HTTPS que cifra la propia aplicación Java. Si la aplicación se puede instrumentar con su lenguaje (arriba), es la mejor opción. Las aplicaciones ya instrumentadas no se duplican: eBPF las salta.
Qué cubre cada forma de instrumentar, por lenguaje y versión: Qué se puede monitorear con el APM.
Instalar el agente en Windows
En el diálogo de instalación del agente, elige la pestaña Windows.
En el servidor Windows, abre PowerShell como Administrador.
Copia el comando del Paso 1 y pégalo en PowerShell (es una sola línea). Baja el instalador, comprueba su huella (SHA-256) y solo entonces lo ejecuta.
Cuando pida la clave, copia la del Paso 2, pégala y presiona Enter. Al pegarla no se ve nada en pantalla: es normal.
Espera el mensaje Agente APM … instalado y corriendo.
El instalador comprueba la firma del agente, deja el servicio de Windows ArgunisApmAgent (arranca solo con el equipo) y enrola el agente: la llave de su certificado se genera en el servidor, en C:\ProgramData\ArgunisApmAgent, que solo pueden leer el sistema y los administradores. Los registros del agente quedan en C:\ProgramData\ArgunisApmAgent\logs.
En un ARGUNIS instalado en tu red con un certificado propio, el comando de la pestaña Windows ya trae el certificado de tu autoridad (-ServerCa). Úsalo tal cual.
Instrumentar un servicio de Windows o IIS
En Windows se instrumentan aplicaciones .NET (.NET Framework 4.6.2 o superior y .NET 6 o superior) y Java (8 o superior) que corren como servicio de Windows, y sitios .NET en IIS por su grupo de aplicaciones (app pool). El agente descarga y verifica lo necesario; no hay que cambiar la aplicación. Todos los comandos van en PowerShell como Administrador.
Servicio de Windows (usa el nombre del servicio, el que muestra Get-Service, no el nombre para mostrar):
& 'C:\Program Files\ArgunisApmAgent\bin\argunis-apm-agent.ps1' -Instrumentar Facturacion -Lenguaje dotnet -Env produccion -Version 1.4.2Con Java, cambia -Lenguaje dotnet por -Lenguaje java. Después, cuando te acomode, reinicia el servicio:
Restart-Service -Name 'Facturacion'IIS (solo .NET), con el nombre del app pool:
& 'C:\Program Files\ArgunisApmAgent\bin\argunis-apm-agent.ps1' -AppPool Ventas -Lenguaje dotnet -Env produccionDespués recicla el app pool cuando te acomode:
Restart-WebAppPool -Name 'Ventas'El comando deja las variables de la instrumentación en el servicio o en el app pool, pero no reinicia la aplicación: empieza a enviar después de que tú la reinicies o recicles. IIS puede reciclar el app pool por su cuenta al cambiar su configuración si así está configurado.
Las variables que el servicio o el app pool ya tenían se conservan. Para dejar de instrumentar, ejecuta argunis-apm-agent.ps1 -Desinstrumentar Facturacion (servicio) o argunis-apm-agent.ps1 -Desinstrumentar -AppPool Ventas (IIS), y reinicia o recicla: se quitan las variables del agente y vuelven las que había antes. Para ver el estado del agente: argunis-apm-agent.ps1 -Status.
Desinstalar el agente de Windows
Quita antes la instrumentación de cada aplicación (arriba) y reiníciala: el desinstalador no avanza si queda alguna instrumentada.
En PowerShell como Administrador, ejecuta el instalador con
-Desinstalar(bájalo de la URL que muestra el diálogo):
& "$env:TEMP\argunis-apm-agent-install.ps1" -DesinstalarQuita también el agente en ARGUNIS (abajo, Quitar un agente).
Qué se obtiene
La aplicación aparece en APM → Servicios con el nombre, el entorno y la versión que indicaste, y con sus trazas, tasa, errores y latencias. Ver Ver los servicios.
El agente envía por un canal cifrado con un certificado propio que renueva solo antes de vencer.
Si ARGUNIS no está disponible por un rato, lo enviado espera en el disco del servidor y se manda al volver, sin perderse.
Ver el estado
Cada agente muestra:
Columna | Qué indica |
|---|---|
Estado (punto y texto bajo el nombre) | esperando instalación (aún no se instala; si dice token vencido, crea uno nuevo), conectado (envió en los últimos minutos), sin conexión, instalado · aún no se conecta o revocado |
Servidor | Nombre del equipo y sistema operativo que informó el agente |
Versión | Versión del agente instalado. → 1.3.1 (amarillo) avisa que hay una versión nueva; actualizando a … que la orden está enviada; falló …, volvió a … (rojo) que la versión nueva no arrancó y el agente siguió con la anterior (pasa el mouse para ver el motivo) |
Última conexión | Hace cuánto se conectó o envió por última vez (pasa el mouse para ver la fecha exacta) |
Certificado vence | Hasta cuándo vale su certificado. El agente lo renueva solo antes de esa fecha |
Actualizar un agente
Cuando hay una versión nueva del agente APM, la columna Versión lo avisa y aparece el botón Actualizar (ícono de flechas) en la fila. No hay que reinstalar ni crear un token: el agente conserva su identidad, su certificado, lo que tenga en espera en el disco, las aplicaciones instrumentadas y eBPF.
En la fila del agente, presiona Actualizar (o Actualizar todos a … arriba de la lista para todos los que tengan una versión anterior).
Confirma con Actualizar.
En a lo más un minuto el agente toma la orden: baja la versión nueva, comprueba su firma y reinicia solo el agente APM (tus aplicaciones siguen corriendo). Al terminar, la columna Versión muestra la nueva.
Si la versión nueva no arranca, el agente vuelve solo a la anterior en unos minutos y la fila lo muestra en rojo. Los datos no se pierden: esperan en el disco del servidor mientras el agente se reinicia.
También puede actualizarlo el administrador del servidor:
sudo argunis-apm-agent --actualizar& 'C:\Program Files\ArgunisApmAgent\bin\argunis-apm-agent.ps1' -ActualizarLos agentes con una versión anterior a la 1.3.0 no se actualizan desde la web (el aviso de versión nueva aparece, pero sin botón): reinstálalos una vez con un token nuevo (abajo).
Crear un token nuevo para un agente
Úsalo si el token venció antes de instalar o si necesitas reinstalar el agente.
En la fila del agente, presiona el ícono de llave (Token de instalación nuevo).
Confirma con Crear token.
Copia el comando de instalación nuevo y presiona Listo.
Ejecútalo en el servidor como en Instalar el agente en el servidor o Instalar el agente en Windows. Las aplicaciones ya instrumentadas no se tocan.
Si el agente ya estaba instalado, su certificado deja de valer al instante y tendrás que volver a instalarlo con el token nuevo. Si no lo estaba, los tokens anteriores que no se usaron dejan de servir.
Revocar un agente
En la fila del agente, presiona el ícono de detener (Revocar).
Confirma con Revocar.
Su certificado deja de valer al instante y ARGUNIS corta su conexión. El agente queda en la lista como revocado; para volver a usar ese servidor, quítalo y crea un agente nuevo.
Quitar un agente
En la fila del agente, presiona el ícono de basurero (Quitar).
Confirma con Quitar.
Si el agente estaba vigente, su certificado deja de valer al instante y ARGUNIS corta su conexión. Después, desinstálalo del servidor.
Los datos que el agente ya envió siguen en el APM hasta que venzan por la retención.
Relacionado
Instrumentar una aplicación de servidor (sin agente, enviando directo a ARGUNIS)