Vai al contenuto principale
Il daemon 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 è ora agenteye-collector (in precedenza era agenteye). Il nome breve agenteye appartiene ora alla CLI di AgentEye. Se stai aggiornando un’installazione esistente, vedi enterprise-docs/collector-migration.md.

Prerequisiti


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 repository agenteye-enterprise/releases sotto il tag di rilascio collector/v<version> più recente. Nomi artefatti disponibili:
PiattaformaArtefatto
Linux x86_64agenteye-collector-linux-x86_64
Linux arm64agenteye-collector-linux-arm64
macOS x86_64agenteye-collector-darwin-x86_64
macOS arm64agenteye-collector-darwin-arm64
Windows x86_64agenteye-collector-windows-x86_64.exe
Windows arm64agenteye-collector-windows-arm64.exe
Scarica con la CLI gh (sostituisci la versione e scegli l’artefatto della tua piattaforma):
O con curl:

Opzione B: Docker

I build beta attuali pubblicano il tag mobile :beta-latest; :latest viene assegnato solo ai rilasci stabili. Per deploy ripetibili, preferisci un tag di versione fissato come :v0.0.1-beta.13.
Esegui:
L’immagine ufficiale viene eseguita come utente non root, quindi imposta 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):
  1. Flag CLI: agenteye-collector start --url https://...
  2. Variabile di ambiente: AGENTEYE_URL=https://...
  3. File di configurazione: ~/.agenteye/config.json

Opzioni obbligatorie

OpzioneFlag CLIVariabile di ambienteChiave config.json
URL Backend--url <URL>AGENTEYE_URL"url"
Chiave API--key <KEY>AGENTEYE_KEY"key"

Opzioni facoltative (con valori predefiniti)

OpzioneFlag CLIVariabile di ambienteChiave config.jsonPredefinito
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.
OpzioneFlag CLIVariabile di ambienteChiave 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

Con mTLS:
Con mTLS più un CA personalizzato (server AgentEye autofirmato):
Se 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:
Usa https per qualsiasi deploy che attraversi una rete non affidabile in modo che gli eventi non vengano inviati in testo semplice. La forma http://your-server-host:8080/events in testo semplice è appropriata solo per test puramente locali contro un server sullo stesso host.
Prova la connessione (flush singolo, esce dopo lo scarico degli eventi in sospeso):
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:
Perché queste impostazioni:
  • autorestart=true su agenteye-collector: riavvia su qualsiasi uscita (crash, panic, OOM).
  • autorestart=unexpected sull’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.
Passa 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):
Il daemon in esecuzione scrive un heartbeat a $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)

Crea /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 rilascio collector/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; :latest esiste 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

ComandoDescrizione
agenteye-collector startAvvia 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 flushSingolo: 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 healthLeggi 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

I file in failed/ non vengono ritentati automaticamente. Per metterli di nuovo in coda manualmente, spostali nuovamente in events/ ed esegui agenteye-collector flush.