Passer au contenu principal
Le daemon agenteye-collector garantit que la télémétrie de vos agents parvient à AgentEye sans jamais bloquer votre application. Votre code écrit des événements dans un répertoire local et continue son exécution ; le collector prend en charge le reste, en téléversant chaque fichier en quelques millisecondes et en survivant aux redémarrages, aux pannes réseau et aux erreurs serveur transitoires. Les téléversements échoués sont réessayés avec un backoff exponentiel, et un balayage de récupération périodique remet en file d’attente tout ce qui aurait été laissé en suspens lors d’un crash ou d’un déploiement. Le résultat est une livraison durable en mode « fire-and-forget » : vos agents continuent de tourner à pleine vitesse pendant que le collector s’assure qu’aucun événement n’est perdu en transit. Concrètement, le collector est un daemon léger qui surveille $AGENTEYE_HOME/events/ (par défaut : ~/.agenteye/events/) pour y détecter les fichiers .jsonl écrits par le SDK Python et les téléverser vers le serveur AgentEye.
Renommage : la commande du collector s’appelle désormais agenteye-collector (elle s’appelait auparavant agenteye). Le nom abrégé agenteye appartient maintenant à l’interface en ligne de commande AgentEye. Si vous mettez à jour une installation existante, consultez enterprise-docs/collector-migration.md.

Prérequis


Option A : Binaire (recommandé)

Des binaires statiques pré-compilés sont disponibles pour Linux, macOS et Windows (x86_64 et arm64). Téléchargez le binaire correspondant à votre plateforme directement depuis le dépôt agenteye-enterprise/releases, sous le dernier tag de release collector/v<version>. Noms des artefacts disponibles :
PlateformeArtefact
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
Téléchargement avec la CLI gh (remplacez la version et choisissez l’artefact correspondant à votre plateforme) :
Ou avec curl :

Option B : Docker

Les builds bêta actuels publient le tag flottant :beta-latest ; :latest est réservé aux releases stables. Pour des déploiements reproductibles, privilégiez un tag de version fixe tel que :v0.0.1-beta.13.
Démarrage :
L’image officielle s’exécute en tant qu’utilisateur non-root ; définissez donc AGENTEYE_HOME explicitement et montez le spool de l’hôte sur ce chemin. Le montage de volume partage le même répertoire ~/.agenteye/ dans lequel le SDK Python écrit sur l’hôte. Si vous avez déjà défini AGENTEYE_HOME à un autre emplacement sur l’hôte, montez ce répertoire plutôt que $HOME/.agenteye.

Configuration

Toutes les options peuvent être définies de trois manières (par ordre de priorité décroissante) :
  1. Flag CLI : agenteye-collector start --url https://...
  2. Variable d’environnement : AGENTEYE_URL=https://...
  3. Fichier de configuration : ~/.agenteye/config.json

Options requises

OptionFlag CLIVariable d’envClé config.json
URL du backend--url <URL>AGENTEYE_URL"url"
Clé API--key <KEY>AGENTEYE_KEY"key"

Options facultatives (avec valeurs par défaut)

OptionFlag CLIVariable d’envClé config.jsonValeur par défaut
Téléversements simultanés max--max-concurrent-uploads <N>AGENTEYE_MAX_CONCURRENT_UPLOADS"max_concurrent_uploads"64
Intervalle de balayage (s)--sweep-interval <S>AGENTEYE_SWEEP_INTERVAL"sweep_interval_secs"60
Âge min. des fichiers pour le balayage (s)--sweep-min-age <S>AGENTEYE_SWEEP_MIN_AGE"sweep_min_age_secs"120
Fichiers max. par balayage--sweep-max-files <N>AGENTEYE_SWEEP_MAX_FILES"sweep_max_files"64
Tentatives de téléversement max--max-retries <N>AGENTEYE_MAX_RETRIES"max_retries"5
Délai de base entre tentatives (ms)--retry-base-delay <MS>AGENTEYE_RETRY_BASE_DELAY"retry_base_delay_ms"1000

Options mTLS (facultatives)

Pour les déploiements nécessitant un TLS mutuel (mTLS), le collector peut présenter un certificat client lors de la négociation TLS. Si ces options ne sont pas définies, le collector utilise HTTPS standard.
OptionFlag CLIVariable d’envClé config.json
Certificat client (PEM)--tls-cert <PATH>AGENTEYE_TLS_CERT"tls_cert"
Clé privée client (PEM)--tls-key <PATH>AGENTEYE_TLS_KEY"tls_key"
Certificat CA personnalisé (PEM)--tls-ca <PATH>AGENTEYE_TLS_CA"tls_ca"
--tls-cert et --tls-key doivent être définis ensemble. Les fichiers doivent être encodés en PEM. --tls-ca est indépendant et n’est nécessaire que lorsque le serveur AgentEye présente un certificat TLS qui n’est pas émis par une CA publiquement reconnue (par exemple, auto-signé par un émetteur cert-manager dans le cluster lorsque vous ne disposez pas d’un vrai domaine DNS). Le collector ajoute la CA fournie comme ancre de confiance supplémentaire ; les racines publiques standard restent approuvées, de sorte que les déploiements existants ne sont pas affectés. Le fichier peut contenir un seul certificat PEM ou une chaîne complète (plusieurs blocs PEM concaténés). Vous exécutez le collector en tant que sidecar dans votre pod applicatif ? Consultez enterprise-docs/single-pod-deployment.md pour le schéma EKS de bout en bout : bundle mTLS livré via AWS Secrets Manager + Secrets Store CSI Driver + IRSA, avec rotation automatique. Lorsque vous déployez dans Kubernetes avec le pattern de remise de Secret, montez le Secret de certificat en tant que volume et pointez ces chemins vers les fichiers montés :

Exemple de ~/.agenteye/config.json

Avec mTLS :
Avec mTLS et une CA personnalisée (serveur AgentEye auto-signé) :
Si AGENTEYE_HOME est défini, ce répertoire est utilisé à la place de ~/.agenteye.

Configuration initiale

Après l’installation, configurez le collector avec l’URL de votre serveur et votre clé API :
Utilisez https pour tout déploiement traversant un réseau non fiable, afin que les événements ne soient pas transmis en clair. La forme en clair http://your-server-host:8080/events n’est appropriée que pour des tests purement locaux contre un serveur sur la même machine.
Tester la connexion (vidage ponctuel, se termine après avoir traité les événements en attente) :
flush rapporte sa progression sur stdout. Lorsque le spool est vide, il affiche No pending files. et se termine avec le code 0. Sinon, il affiche une ligne par fichier ([UPLOADED] <file> ou [FAILED] <file> (<reason>)), suivie d’un résumé Done: <uploaded>/<total> uploaded, <failed> failed.. Cela fait de flush un outil pratique pour vérifier en une seule passe que votre URL, votre clé et vos paramètres TLS sont corrects avant de démarrer le daemon.

Exécution en tant que daemon

Directement

Conteneur / Docker

Lorsque le collector et votre application partagent un conteneur, exécutez-les sous un superviseur de processus. L’option la plus simple est supervisord ; il est disponible dans toutes les distributions majeures, redémarre les processus qui ont planté, transmet les signaux et attend un arrêt gracieux. Dockerfile :
supervisord.conf :
Explication de ces paramètres :
  • autorestart=true sur agenteye-collector : redémarre à chaque arrêt (crash, panique, OOM).
  • autorestart=unexpected sur l’app : redémarre uniquement en cas de sortie avec un code non-zéro, afin qu’un agent ponctuel qui se termine avec le code 0 ne boucle pas indéfiniment.
  • stopwaitsecs=30 : laisse au collector le temps de vider les téléversements en attente lors d’un SIGTERM avant que supervisord n’escalade vers SIGKILL.
  • stdout_logfile=/dev/stdout, *_maxbytes=0 : redirige la sortie des deux programmes vers le stdout du conteneur, sans fichiers de log à l’intérieur du conteneur.
Transmettez AGENTEYE_URL / AGENTEYE_KEY (et les éventuelles variables d’environnement TLS) via docker run -e comme précédemment ; supervisord hérite de l’environnement.
Conteneurs séparés ? Si vous exécutez le collector dans son propre conteneur (service Docker Compose, sidecar Kubernetes, etc.), n’utilisez pas supervisord ; la politique de redémarrage du runtime de conteneurs remplit déjà ce rôle. Consultez enterprise-docs/single-pod-deployment.md pour le schéma de sidecar EKS.
Sonde de vivacité Kubernetes (applicable que le collector tourne seul ou sous supervisord) :
Le daemon en cours d’exécution écrit un heartbeat dans $AGENTEYE_HOME/health.json toutes les 30 secondes. agenteye-collector health lit ce fichier et se termine avec le code 0 (sain) uniquement lorsque le heartbeat est récent et que les tâches de téléversement fonctionnent normalement ; il se termine avec le code 1 (défaillant) lorsque le heartbeat est antérieur à 90 secondes (par exemple, le daemon s’est arrêté) ou pendant que le watcher et le sweeper redémarrent après un arrêt inattendu. Le heartbeat n’est écrit que par start, alors exécutez la sonde contre le daemon long-lived plutôt que contre la commande ponctuelle flush.

systemd (Linux, recommandé pour la production)

Créez /etc/agenteye/env :

launchd (macOS)


Mise à jour du Collector

Le collector ne se met pas à jour automatiquement. Pour effectuer une mise à jour :
  • Binaire : téléchargez le nouvel artefact agenteye-collector-<os>-<arch> depuis la dernière release collector/v<version> (voir Option A), remplacez /usr/local/bin/agenteye-collector, puis redémarrez le service (sudo systemctl restart agenteye-collector, relancez launchctl load, ou redémarrez votre superviseur).
  • Docker : docker pull ghcr.io/agenteye-enterprise/collector:beta-latest (ou un tag :v<version> épinglé ; :latest n’existe que pour les releases stables) et recréez le conteneur.
AGENTEYE_TOKEN est nécessaire pour télécharger de nouveaux binaires/images depuis le dépôt de releases privé, mais n’est pas requis par le daemon en cours d’exécution.

Sous-commandes

CommandeDescription
agenteye-collector startDémarre le daemon long-lived. Au démarrage, il vide tous les événements restants d’une exécution précédente, puis surveille les nouveaux fichiers et les téléverse. Le watcher et le sweeper redémarrent automatiquement en cas d’arrêt inattendu, et un heartbeat est écrit dans health.json toutes les 30 secondes.
agenteye-collector flushPonctuel : téléverse tous les fichiers en attente et se termine. Affiche No pending files. lorsque le spool est vide, sinon un journal [UPLOADED]/[FAILED] par fichier et un résumé Done: <uploaded>/<total> uploaded, <failed> failed..
agenteye-collector healthLit le heartbeat health.json du daemon. Se termine avec le code 0 lorsqu’il est récent et sain ; se termine avec le code 1 lorsque le heartbeat est périmé (antérieur à 90s) ou que les tâches redémarrent.

Structure des répertoires

Les fichiers dans failed/ ne sont pas automatiquement réessayés. Pour les remettre manuellement en file d’attente, déplacez-les vers events/ et exécutez agenteye-collector flush.