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ésormaisagenteye-collector(elle s’appelait auparavantagenteye). Le nom abrégéagenteyeappartient maintenant à l’interface en ligne de commande AgentEye. Si vous mettez à jour une installation existante, consultez enterprise-docs/collector-migration.md.
Prérequis
- Votre
AGENTEYE_TOKEN: un PAT GitHub que vous générez vous-même (voir enterprise-docs/github-token.md) - L’URL du serveur et une clé API pour le collector (voir enterprise-docs/api-keys.md)
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ôtagenteye-enterprise/releases, sous le dernier tag de release collector/v<version>.
Noms des artefacts disponibles :
| Plateforme | Artefact |
|---|---|
| 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 (remplacez la version et choisissez l’artefact correspondant à votre plateforme) :
curl :
Option B : Docker
Les builds bêta actuels publient le tag flottantDémarrage ::beta-latest;:latestest réservé aux releases stables. Pour des déploiements reproductibles, privilégiez un tag de version fixe tel que:v0.0.1-beta.13.
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) :- Flag CLI :
agenteye-collector start --url https://... - Variable d’environnement :
AGENTEYE_URL=https://... - Fichier de configuration :
~/.agenteye/config.json
Options requises
| Option | Flag CLI | Variable d’env | Clé config.json |
|---|---|---|---|
| URL du backend | --url <URL> | AGENTEYE_URL | "url" |
| Clé API | --key <KEY> | AGENTEYE_KEY | "key" |
Options facultatives (avec valeurs par défaut)
| Option | Flag CLI | Variable d’env | Clé config.json | Valeur 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.| Option | Flag CLI | Variable d’env | Clé 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
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 :UtilisezTester la connexion (vidage ponctuel, se termine après avoir traité les événements en attente) :httpspour tout déploiement traversant un réseau non fiable, afin que les événements ne soient pas transmis en clair. La forme en clairhttp://your-server-host:8080/eventsn’est appropriée que pour des tests purement locaux contre un serveur sur la même machine.
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 estsupervisord ; 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 :
autorestart=truesur agenteye-collector : redémarre à chaque arrêt (crash, panique, OOM).autorestart=unexpectedsur 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 code0ne 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.
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) :
$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)
/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 releasecollector/v<version>(voir Option A), remplacez/usr/local/bin/agenteye-collector, puis redémarrez le service (sudo systemctl restart agenteye-collector, relancezlaunchctl load, ou redémarrez votre superviseur). - Docker :
docker pull ghcr.io/agenteye-enterprise/collector:beta-latest(ou un tag:v<version>épinglé ;:latestn’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
| Commande | Description |
|---|---|
agenteye-collector start | Dé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 flush | Ponctuel : 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 health | Lit 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
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.
