agenteye-collector garantiza que la telemetría de tus agentes llegue a AgentEye sin bloquear nunca tu aplicación. Tu código escribe eventos en un directorio local y continúa su ejecución; el collector toma el control desde ese momento, subiendo cada archivo en milisegundos y sobreviviendo reinicios, interrupciones de red y errores transitorios del servidor. Las subidas fallidas se reintentan con retroceso exponencial, y un barrido periódico de recuperación vuelve a encolar cualquier archivo que haya quedado pendiente tras un fallo o despliegue. El resultado es una entrega durable y de tipo “lanzar y olvidar”: tus agentes siguen funcionando a plena velocidad mientras el collector garantiza que ningún evento se pierda en tránsito.
Mecánicamente, el collector es un daemon ligero que monitorea $AGENTEYE_HOME/events/ (por defecto: ~/.agenteye/events/) en busca de archivos .jsonl escritos por el SDK de Python y los sube al servidor de AgentEye.
Cambio de nombre: el comando del collector ahora esagenteye-collector(antes eraagenteye). El nombre abreviadoagenteyeahora pertenece al CLI de AgentEye. Si estás actualizando una instalación existente, consulta enterprise-docs/collector-migration.md.
Requisitos previos
- Tu
AGENTEYE_TOKEN: un PAT de GitHub que tú mismo generas (consulta enterprise-docs/github-token.md) - La URL del servidor y una clave de API del collector (consulta enterprise-docs/api-keys.md)
Opción A: Binario (recomendado)
Hay binarios estáticos precompilados disponibles para Linux, macOS y Windows (x86_64 y arm64). Descarga el binario para tu plataforma directamente desde el repositorioagenteye-enterprise/releases, bajo la etiqueta de lanzamiento más reciente collector/v<version>.
Nombres de artefactos disponibles:
| Plataforma | Artefacto |
|---|---|
| Linux x86_64 | agenteye-collector-linux-x86_64 |
| Linux arm64 | agenteye-collector-linux-arm64 |
| macOS x86_64 | agenteye-collector-darwin-x86_64 |
| macOS arm64 | agenteye-collector-darwin-arm64 |
| Windows x86_64 | agenteye-collector-windows-x86_64.exe |
| Windows arm64 | agenteye-collector-windows-arm64.exe |
gh (reemplaza la versión y elige el artefacto de tu plataforma):
curl:
Opción B: Docker
Las compilaciones beta actuales publican la etiqueta flotanteEjecutar::beta-latest; la etiqueta:latestsolo se asigna a versiones estables. Para despliegues reproducibles, se recomienda usar una etiqueta de versión fija como:v0.0.1-beta.13.
AGENTEYE_HOME explícitamente y montar el directorio de cola del host en él. El montaje de volumen comparte el mismo directorio ~/.agenteye/ en el que el SDK de Python escribe en el host. Si ya tienes AGENTEYE_HOME configurado en otra ubicación del host, monta ese directorio en lugar de $HOME/.agenteye.
Configuración
Todas las opciones pueden establecerse de tres formas (de mayor a menor prioridad):- Bandera de CLI:
agenteye-collector start --url https://... - Variable de entorno:
AGENTEYE_URL=https://... - Archivo de configuración:
~/.agenteye/config.json
Opciones obligatorias
| Opción | Bandera CLI | Variable de entorno | Clave en config.json |
|---|---|---|---|
| URL del backend | --url <URL> | AGENTEYE_URL | "url" |
| Clave de API | --key <KEY> | AGENTEYE_KEY | "key" |
Opciones opcionales (con valores por defecto)
| Opción | Bandera CLI | Variable de entorno | Clave en config.json | Por defecto |
|---|---|---|---|---|
| Máx. subidas simultáneas | --max-concurrent-uploads <N> | AGENTEYE_MAX_CONCURRENT_UPLOADS | "max_concurrent_uploads" | 64 |
| Intervalo del barrido (s) | --sweep-interval <S> | AGENTEYE_SWEEP_INTERVAL | "sweep_interval_secs" | 60 |
| Edad mínima de archivo para barrido (s) | --sweep-min-age <S> | AGENTEYE_SWEEP_MIN_AGE | "sweep_min_age_secs" | 120 |
| Máx. archivos por barrido | --sweep-max-files <N> | AGENTEYE_SWEEP_MAX_FILES | "sweep_max_files" | 64 |
| Máx. intentos de subida | --max-retries <N> | AGENTEYE_MAX_RETRIES | "max_retries" | 5 |
| Retardo base de reintento (ms) | --retry-base-delay <MS> | AGENTEYE_RETRY_BASE_DELAY | "retry_base_delay_ms" | 1000 |
Opciones mTLS (opcionales)
Para despliegues que requieren TLS mutuo (mTLS), el collector puede presentar un certificado de cliente durante el protocolo de enlace TLS. Si no se configuran estas opciones, el collector utiliza HTTPS estándar.| Opción | Bandera CLI | Variable de entorno | Clave en config.json |
|---|---|---|---|
| Certificado de cliente (PEM) | --tls-cert <PATH> | AGENTEYE_TLS_CERT | "tls_cert" |
| Clave privada del cliente (PEM) | --tls-key <PATH> | AGENTEYE_TLS_KEY | "tls_key" |
| Certificado CA personalizado (PEM) | --tls-ca <PATH> | AGENTEYE_TLS_CA | "tls_ca" |
--tls-cert y --tls-key deben configurarse juntos. Los archivos deben estar codificados en PEM.
--tls-ca es independiente y solo es necesario cuando el servidor de AgentEye presenta un certificado TLS que no ha sido emitido por una CA de confianza pública (por ejemplo, autofirmado por un emisor cert-manager dentro del clúster cuando no tienes un dominio DNS real). El collector añade la CA proporcionada como ancla de confianza adicional; las raíces públicas estándar siguen siendo de confianza, por lo que los despliegues existentes no se ven afectados. El archivo puede contener un único certificado PEM o una cadena completa (múltiples bloques PEM concatenados).
¿Ejecutas el collector como sidecar en tu pod de aplicación? Consulta enterprise-docs/single-pod-deployment.md para ver el patrón completo en EKS: paquete mTLS entregado mediante AWS Secrets Manager + Secrets Store CSI Driver + IRSA, con rotación automática.
Cuando se ejecuta en Kubernetes con el patrón de transferencia de Secrets, monta el Secret del certificado como un volumen y apunta estas rutas a los archivos montados:
Ejemplo de ~/.agenteye/config.json
AGENTEYE_HOME está definido, se usará ese directorio en lugar de ~/.agenteye.
Configuración inicial
Tras la instalación, configura el collector con la URL de tu servidor y la clave de API:UsaProbar la conexión (vaciado puntual, finaliza tras drenar los eventos pendientes):httpspara cualquier despliegue que atraviese una red no confiable, de modo que los eventos no se envíen en texto plano. El formato en texto planohttp://your-server-host:8080/eventssolo es apropiado para pruebas puramente locales contra un servidor en el mismo host.
flush reporta su progreso por stdout. Cuando la cola está vacía, imprime No pending files. y termina con código 0. En caso contrario, imprime una línea por archivo ([UPLOADED] <file> o [FAILED] <file> (<reason>)), seguida de un resumen Done: <uploaded>/<total> uploaded, <failed> failed.. Esto convierte a flush en una verificación puntual muy práctica para comprobar que tu URL, clave y configuración TLS son correctos antes de iniciar el daemon.
Ejecución como daemon
Directamente
Contenedor / Docker
Cuando el collector y tu aplicación comparten un contenedor, ejecútalos bajo un supervisor de procesos. La opción más sencilla essupervisord; está disponible en todas las distribuciones principales, reinicia los procesos que fallen, reenvía señales y espera a un apagado controlado.
Dockerfile:
supervisord.conf:
autorestart=trueen agenteye-collector: reinicia ante cualquier salida (fallo, pánico, OOM).autorestart=unexpecteden la aplicación: solo reinicia en caso de salida con código distinto de cero, de modo que un agente puntual que termine con código 0 no entre en bucle.stopwaitsecs=30: da al collector margen para drenar las subidas pendientes al recibir SIGTERM antes de que supervisord escale a SIGKILL.stdout_logfile=/dev/stdout,*_maxbytes=0: redirige la salida de ambos programas al stdout del contenedor; sin archivos de log dentro del contenedor.
AGENTEYE_URL / AGENTEYE_KEY (y cualquier variable de entorno TLS) con docker run -e como de costumbre; supervisord hereda el entorno.
¿Contenedores separados? Si ejecutas el collector en su propio contenedor (servicio de Docker Compose, sidecar de Kubernetes, etc.), no uses supervisord; la política de reinicio del runtime de contenedores ya se encarga de eso. Consulta enterprise-docs/single-pod-deployment.md para ver el patrón de sidecar en EKS.Sonda de liveness de Kubernetes (aplica tanto si el collector se ejecuta solo como bajo supervisord):
$AGENTEYE_HOME/health.json cada 30 segundos. agenteye-collector health lee ese archivo y termina con código 0 (saludable) solo cuando el latido es reciente y las tareas de subida se están ejecutando con normalidad; termina con código 1 (no saludable) cuando el latido tiene más de 90 segundos de antigüedad (por ejemplo, el daemon se ha detenido) o mientras el observador y el barredor se están reiniciando tras una salida inesperada. El latido solo es escrito por start, así que ejecuta la sonda contra el daemon de larga duración y no contra el comando puntual flush.
systemd (Linux, recomendado para producción)
/etc/agenteye/env:
launchd (macOS)
Actualización del Collector
El collector no se actualiza a sí mismo. Para actualizarlo:- Binario: descarga el nuevo artefacto
agenteye-collector-<os>-<arch>desde la última versióncollector/v<version>(consulta Opción A), reemplaza/usr/local/bin/agenteye-collectory reinicia el servicio (sudo systemctl restart agenteye-collector, vuelve a ejecutarlaunchctl load, o reinicia tu supervisor). - Docker: ejecuta
docker pull ghcr.io/agenteye-enterprise/collector:beta-latest(o una etiqueta fija:v<version>;:latestsolo existe para versiones estables) y recrea el contenedor.
AGENTEYE_TOKEN es necesario para descargar nuevos binarios/imágenes del repositorio de versiones privado, pero no es necesario para el daemon en ejecución.
Subcomandos
| Comando | Descripción |
|---|---|
agenteye-collector start | Inicia el daemon de larga duración. Al arrancar, vacía cualquier evento que haya quedado de una ejecución anterior, luego monitorea nuevos archivos y los sube. El observador y el barredor se reinician automáticamente ante salidas inesperadas, y se escribe un latido en health.json cada 30 segundos. |
agenteye-collector flush | Puntual: sube todos los archivos pendientes y termina. Imprime No pending files. cuando la cola está vacía; en caso contrario, un registro [UPLOADED]/[FAILED] por archivo y un resumen Done: <uploaded>/<total> uploaded, <failed> failed.. |
agenteye-collector health | Lee el latido health.json del daemon. Termina con código 0 cuando está reciente y saludable; termina con código 1 cuando el latido está desactualizado (más de 90s) o las tareas se están reiniciando. |
Estructura de directorios
failed/ no se reintentan automáticamente. Para volver a ponerlos en cola manualmente, muévelos de nuevo a events/ y ejecuta agenteye-collector flush.
