agenteye-collector garantisce che la telemetria dei tuoi agenti raggiunga AgentEye senza mai bloccare la tua applicazione. Il tuo codice scrive gli eventi in una directory locale e continua; il collector prende in carico da lì, caricando ogni file in pochi millisecondi e sopravvivendo a riavvii, interruzioni di rete e errori transitori del server. I caricamenti falliti vengono ritentati con backoff esponenziale, e una scansione di recupero periodica rimette in coda tutto ciò che è stato lasciato da un crash o da un deploy. Il risultato è una consegna duratura, fire-and-forget: i tuoi agenti continuano a funzionare a piena velocità mentre il collector assicura che nessun evento vada perso durante il transito.
Meccanicamente, il collector è un daemon leggero che osserva $AGENTEYE_HOME/events/ (predefinito: ~/.agenteye/events/) per i file .jsonl scritti dall’SDK Python e li carica sul server AgentEye.
Rinominato: il comando del collector è oraagenteye-collector(in precedenza eraagenteye). Il nome breveagenteyeappartiene ora alla CLI di AgentEye. Se stai aggiornando un’installazione esistente, vedi enterprise-docs/collector-migration.md.
Prerequisiti
- Il tuo
AGENTEYE_TOKEN: un GitHub PAT che generi tu stesso (vedi enterprise-docs/github-token.md) - L’URL del server e una chiave API del collector (vedi enterprise-docs/api-keys.md)
Opzione A: Binary (consigliato)
I binari statici precompilati sono disponibili per Linux, macOS e Windows (x86_64 e arm64). Scarica il binario per la tua piattaforma direttamente dal repositoryagenteye-enterprise/releases sotto il tag di rilascio collector/v<version> più recente.
Nomi artefatti disponibili:
| Piattaforma | Artefatto |
|---|---|
| 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 (sostituisci la versione e scegli l’artefatto della tua piattaforma):
curl:
Opzione B: Docker
I build beta attuali pubblicano il tag mobileEsegui::beta-latest;:latestviene assegnato solo ai rilasci stabili. Per deploy ripetibili, preferisci un tag di versione fissato come:v0.0.1-beta.13.
AGENTEYE_HOME esplicitamente e monta lo spool dell’host su di esso. Il mount del volume condivide la stessa directory ~/.agenteye/ in cui l’SDK Python scrive sull’host. Se hai già impostato AGENTEYE_HOME altrove sull’host, monta quella directory invece di $HOME/.agenteye.
Configurazione
Tutte le opzioni possono essere impostate in tre modi (priorità più alta per prima):- Flag CLI:
agenteye-collector start --url https://... - Variabile di ambiente:
AGENTEYE_URL=https://... - File di configurazione:
~/.agenteye/config.json
Opzioni obbligatorie
| Opzione | Flag CLI | Variabile di ambiente | Chiave config.json |
|---|---|---|---|
| URL Backend | --url <URL> | AGENTEYE_URL | "url" |
| Chiave API | --key <KEY> | AGENTEYE_KEY | "key" |
Opzioni facoltative (con valori predefiniti)
| Opzione | Flag CLI | Variabile di ambiente | Chiave config.json | Predefinito |
|---|---|---|---|---|
| Caricamenti simultanei massimi | --max-concurrent-uploads <N> | AGENTEYE_MAX_CONCURRENT_UPLOADS | "max_concurrent_uploads" | 64 |
| Intervallo sweeper (s) | --sweep-interval <S> | AGENTEYE_SWEEP_INTERVAL | "sweep_interval_secs" | 60 |
| Età minima file sweeper (s) | --sweep-min-age <S> | AGENTEYE_SWEEP_MIN_AGE | "sweep_min_age_secs" | 120 |
| File massimi per sweep | --sweep-max-files <N> | AGENTEYE_SWEEP_MAX_FILES | "sweep_max_files" | 64 |
| Tentativi di caricamento massimi | --max-retries <N> | AGENTEYE_MAX_RETRIES | "max_retries" | 5 |
| Ritardo base dei retry (ms) | --retry-base-delay <MS> | AGENTEYE_RETRY_BASE_DELAY | "retry_base_delay_ms" | 1000 |
Opzioni mTLS (facoltative)
Per i deploy che richiedono TLS reciproco (mTLS), il collector può presentare un certificato client durante l’handshake TLS. Quando queste opzioni non sono impostate, il collector utilizza HTTPS standard.| Opzione | Flag CLI | Variabile di ambiente | Chiave config.json |
|---|---|---|---|
| Certificato client (PEM) | --tls-cert <PATH> | AGENTEYE_TLS_CERT | "tls_cert" |
| Chiave privata client (PEM) | --tls-key <PATH> | AGENTEYE_TLS_KEY | "tls_key" |
| Certificato CA personalizzato (PEM) | --tls-ca <PATH> | AGENTEYE_TLS_CA | "tls_ca" |
--tls-cert e --tls-key devono essere impostati insieme. I file devono essere codificati in PEM.
--tls-ca è indipendente e necessario solo quando il server AgentEye presenta un certificato TLS che non è stato emesso da un’autorità di certificazione pubblicamente affidabile (ad es. autofirmato da un issuer cert-manager in-cluster quando non hai un vero dominio DNS). Il collector aggiunge il CA fornito come ancoraggio di trust aggiuntivo; le radici pubbliche standard rimangono fidate, quindi i deploy esistenti non sono interessati. Il file può contenere un singolo certificato PEM o una catena completa (più blocchi PEM concatenati).
Esegui il collector come sidecar nel pod della tua applicazione? Vedi enterprise-docs/single-pod-deployment.md per il pattern EKS end-to-end: bundle mTLS consegnato tramite AWS Secrets Manager + Secrets Store CSI Driver + IRSA, con rotazione automatica.
Quando esegui in Kubernetes con il pattern di handoff del Secret, monta il Secret del certificato come volume e punta questi percorsi ai file montati:
Esempio ~/.agenteye/config.json
AGENTEYE_HOME è impostato, quella directory viene utilizzata al posto di ~/.agenteye.
Configurazione iniziale
Dopo l’installazione, configura il collector con l’URL del server e la chiave API:UsaProva la connessione (flush singolo, esce dopo lo scarico degli eventi in sospeso):httpsper qualsiasi deploy che attraversi una rete non affidabile in modo che gli eventi non vengano inviati in testo semplice. La formahttp://your-server-host:8080/eventsin testo semplice è appropriata solo per test puramente locali contro un server sullo stesso host.
flush segnala il suo avanzamento a stdout. Quando lo spool è vuoto stampa No pending files. ed esce con 0. Altrimenti stampa una riga per file ([UPLOADED] <file> o [FAILED] <file> (<reason>)), seguita da un riepilogo Done: <uploaded>/<total> uploaded, <failed> failed.. Questo rende flush una comoda verifica singola per verificare che l’URL, la chiave e le impostazioni TLS siano corretti prima di avviare il daemon.
Esecuzione come Daemon
Diretto
Container / Docker
Quando il collector e la tua applicazione condividono un container, eseguili sotto un supervisore di processi. L’opzione più semplice èsupervisord; viene fornito in ogni distro principale, riavvia i processi in crash, inoltri i segnali e attende l’arresto corretto.
Dockerfile:
supervisord.conf:
autorestart=truesu agenteye-collector: riavvia su qualsiasi uscita (crash, panic, OOM).autorestart=unexpectedsull’app: riavvia solo su uscita non zero, quindi un agente singolo che esce 0 non entra in loop.stopwaitsecs=30: dà al collector spazio per drenare i caricamenti in sospeso su SIGTERM prima che supervisord passi a SIGKILL.stdout_logfile=/dev/stdout,*_maxbytes=0: flussi dell’output di entrambi i programmi allo stdout del container; nessun file di log dentro il container.
AGENTEYE_URL / AGENTEYE_KEY (e qualsiasi variabile di ambiente TLS) su docker run -e come prima; supervisord eredita l’ambiente.
Container separati? Se esegui il collector come suo proprio container (servizio Docker Compose, sidecar Kubernetes, ecc.), non usare supervisord; la politica di riavvio del runtime del container già fa questo lavoro. Vedi enterprise-docs/single-pod-deployment.md per il pattern sidecar EKS.Sonda di liveness Kubernetes (si applica sia che il collector venga eseguito da solo che sotto supervisord):
$AGENTEYE_HOME/health.json ogni 30 secondi. agenteye-collector health legge quel file ed esce con 0 (sano) solo quando l’heartbeat è fresco e i compiti di caricamento sono in esecuzione normalmente; esce con 1 (non sano) quando l’heartbeat è più vecchio di 90 secondi (ad esempio, il daemon si è fermato) o mentre il watcher e lo sweeper si stanno riavviando dopo un’uscita inaspettata. L’heartbeat viene scritto solo da start, quindi esegui la sonda contro il daemon longevo piuttosto che il comando flush singolo.
systemd (Linux, consigliato per la produzione)
/etc/agenteye/env:
launchd (macOS)
Aggiornamento del Collector
Il collector non si aggiorna automaticamente. Per aggiornare:- Binary: scarica il nuovo artefatto
agenteye-collector-<os>-<arch>dal rilasciocollector/v<version>più recente (vedi Opzione A), sostituisci/usr/local/bin/agenteye-collector, quindi riavvia il servizio (sudo systemctl restart agenteye-collector, ri-launchctl load, o riavvia il tuo supervisore). - Docker:
docker pull ghcr.io/agenteye-enterprise/collector:beta-latest(o un tag:v<version>fissato;:latestesiste solo per i rilasci stabili) e ricrea il container.
AGENTEYE_TOKEN è richiesto per scaricare nuovi binari/immagini dal repository privato dei rilasci, ma non è necessario per il daemon in esecuzione.
Sottocomandi
| Comando | Descrizione |
|---|---|
agenteye-collector start | Avvia il daemon longevo. All’avvio, scarica tutti gli eventi rimasti da un’esecuzione precedente, quindi osserva i nuovi file e li carica. Il watcher e lo sweeper si riavviano automaticamente su uscita inaspettata, e un heartbeat viene scritto a health.json ogni 30 secondi. |
agenteye-collector flush | Singolo: carica tutti i file in sospeso ed esce. Stampa No pending files. quando lo spool è vuoto, altrimenti un log per file [UPLOADED]/[FAILED] e un riepilogo Done: <uploaded>/<total> uploaded, <failed> failed.. |
agenteye-collector health | Leggi l’heartbeat health.json del daemon. Esce con 0 quando è fresco e sano; esce con 1 quando l’heartbeat è stantio (più vecchio di 90 secondi) o i compiti si stanno riavviando. |
Struttura delle Directory
failed/ non vengono ritentati automaticamente. Per metterli di nuovo in coda manualmente, spostali nuovamente in events/ ed esegui agenteye-collector flush.
