agenteye-collector-Daemon stellt sicher, dass die Telemetriedaten Ihrer Agents AgentEye erreichen, ohne Ihre Anwendung jemals zu blockieren. Ihr Code schreibt Ereignisse in ein lokales Verzeichnis und macht weiter; der Collector übernimmt von dort aus, lädt jede Datei innerhalb von Millisekunden hoch und übersteht Neustarts, Netzwerkausfälle und vorübergehende Serverfehler. Fehlgeschlagene Uploads werden mit exponentiellem Backoff wiederholt, und ein periodischer Recovery-Sweep stellt alles wieder in die Warteschlange, was nach einem Absturz oder Deployment zurückgeblieben ist. Das Ergebnis ist eine robuste Fire-and-forget-Übertragung: Ihre Agents laufen weiterhin mit voller Geschwindigkeit, während der Collector sicherstellt, dass keine Ereignisse während der Übertragung verloren gehen.
Technisch gesehen ist der Collector ein schlanker Daemon, der $AGENTEYE_HOME/events/ (Standard: ~/.agenteye/events/) auf .jsonl-Dateien überwacht, die vom Python-SDK geschrieben wurden, und diese auf den AgentEye-Server hochlädt.
Umbenannt: Der Collector-Befehl heißt jetztagenteye-collector(früher war esagenteye). Der kurze Nameagenteyegehört nun zur AgentEye-CLI. Wenn Sie eine bestehende Installation aktualisieren, lesen Sie enterprise-docs/collector-migration.md.
Voraussetzungen
- Ihr
AGENTEYE_TOKEN: ein GitHub PAT, den Sie selbst generieren (siehe enterprise-docs/github-token.md) - Die Server-URL und ein Collector-API-Schlüssel (siehe enterprise-docs/api-keys.md)
Option A: Binärdatei (empfohlen)
Vorgefertigte statische Binärdateien sind für Linux, macOS und Windows (x86_64 und arm64) verfügbar. Laden Sie die Binärdatei für Ihre Plattform direkt aus dem Repositoryagenteye-enterprise/releases unter dem neuesten Release-Tag collector/v<version> herunter.
Verfügbare Artefaktnamen:
| Plattform | Artefakt |
|---|---|
| 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-CLI (Version ersetzen und das Artefakt Ihrer Plattform auswählen):
curl:
Option B: Docker
Aktuelle Beta-Builds veröffentlichen den variablen TagAusführen::beta-latest;:latestwird nur stabilen Releases zugewiesen. Für reproduzierbare Deployments sollten Sie einen festen Versions-Tag wie:v0.0.1-beta.13bevorzugen.
AGENTEYE_HOME explizit und mounten Sie den Host-Spool dorthin. Das Volume-Mount teilt dasselbe ~/.agenteye/-Verzeichnis, in das das Python-SDK auf dem Host schreibt. Wenn Sie AGENTEYE_HOME bereits anderswo auf dem Host gesetzt haben, mounten Sie stattdessen dieses Verzeichnis anstelle von $HOME/.agenteye.
Konfiguration
Alle Optionen können auf drei Arten gesetzt werden (höchste Priorität zuerst):- CLI-Flag:
agenteye-collector start --url https://... - Umgebungsvariable:
AGENTEYE_URL=https://... - Konfigurationsdatei:
~/.agenteye/config.json
Pflichtoptionen
| Option | CLI-Flag | Umgebungsvariable | config.json-Schlüssel |
|---|---|---|---|
| Backend-URL | --url <URL> | AGENTEYE_URL | "url" |
| API-Schlüssel | --key <KEY> | AGENTEYE_KEY | "key" |
Optionale Einstellungen (mit Standardwerten)
| Option | CLI-Flag | Umgebungsvariable | config.json-Schlüssel | Standard |
|---|---|---|---|---|
| Max. gleichzeitige Uploads | --max-concurrent-uploads <N> | AGENTEYE_MAX_CONCURRENT_UPLOADS | "max_concurrent_uploads" | 64 |
| Sweep-Intervall (s) | --sweep-interval <S> | AGENTEYE_SWEEP_INTERVAL | "sweep_interval_secs" | 60 |
| Minimales Datei-Alter für Sweep (s) | --sweep-min-age <S> | AGENTEYE_SWEEP_MIN_AGE | "sweep_min_age_secs" | 120 |
| Max. Dateien pro Sweep | --sweep-max-files <N> | AGENTEYE_SWEEP_MAX_FILES | "sweep_max_files" | 64 |
| Max. Upload-Versuche | --max-retries <N> | AGENTEYE_MAX_RETRIES | "max_retries" | 5 |
| Basis-Verzögerung für Wiederholung (ms) | --retry-base-delay <MS> | AGENTEYE_RETRY_BASE_DELAY | "retry_base_delay_ms" | 1000 |
mTLS-Optionen (optional)
Für Deployments, die gegenseitiges TLS (mTLS) erfordern, kann der Collector beim TLS-Handshake ein Client-Zertifikat vorlegen. Wenn diese Optionen nicht gesetzt sind, verwendet der Collector Standard-HTTPS.| Option | CLI-Flag | Umgebungsvariable | config.json-Schlüssel |
|---|---|---|---|
| Client-Zertifikat (PEM) | --tls-cert <PATH> | AGENTEYE_TLS_CERT | "tls_cert" |
| Privater Client-Schlüssel (PEM) | --tls-key <PATH> | AGENTEYE_TLS_KEY | "tls_key" |
| Benutzerdefiniertes CA-Zertifikat (PEM) | --tls-ca <PATH> | AGENTEYE_TLS_CA | "tls_ca" |
--tls-cert und --tls-key müssen zusammen gesetzt werden. Die Dateien müssen PEM-kodiert sein.
--tls-ca ist unabhängig und wird nur benötigt, wenn der AgentEye-Server ein TLS-Zertifikat vorlegt, das nicht von einer öffentlich vertrauenswürdigen CA ausgestellt wurde (z. B. selbstsigniert von einem clustereigenen cert-manager-Issuer, wenn Sie keine echte DNS-Domain haben). Der Collector fügt die angegebene CA als zusätzlichen Vertrauensanker hinzu; die öffentlichen Standard-Root-Zertifikate bleiben weiterhin vertrauenswürdig, bestehende Deployments sind daher nicht betroffen. Die Datei kann ein einzelnes PEM-Zertifikat oder eine vollständige Kette (mehrere verkettete PEM-Blöcke) enthalten.
Betreiben Sie den Collector als Sidecar in Ihrem Application-Pod? Lesen Sie enterprise-docs/single-pod-deployment.md für das vollständige EKS-Muster: mTLS-Bundle über AWS Secrets Manager + Secrets Store CSI Driver + IRSA, mit automatischer Rotation.
Wenn Sie in Kubernetes mit dem Secret-Übergabe-Muster arbeiten, mounten Sie das Zertifikats-Secret als Volume und verweisen Sie diese Pfade auf die gemounteten Dateien:
Beispiel ~/.agenteye/config.json
AGENTEYE_HOME gesetzt ist, wird dieses Verzeichnis anstelle von ~/.agenteye verwendet.
Ersteinrichtung
Konfigurieren Sie nach der Installation den Collector mit Ihrer Server-URL und Ihrem API-Schlüssel:Verwenden SieVerbindung testen (einmaliger Flush, beendet sich nach dem Leeren ausstehender Ereignisse):httpsfür jedes Deployment, das ein nicht vertrauenswürdiges Netzwerk überquert, damit Ereignisse nicht im Klartext gesendet werden. Die Klartextformhttp://your-server-host:8080/eventsist nur für rein lokale Tests gegen einen Server auf demselben Host geeignet.
flush gibt seinen Fortschritt auf stdout aus. Wenn der Spool leer ist, gibt es No pending files. aus und beendet sich mit 0. Andernfalls wird eine Zeile pro Datei ausgegeben ([UPLOADED] <file> oder [FAILED] <file> (<reason>)), gefolgt von einer Done: <uploaded>/<total> uploaded, <failed> failed.-Zusammenfassung. Damit ist flush eine praktische Einmalprüfung, ob Ihre URL, Ihr Schlüssel und Ihre TLS-Einstellungen korrekt sind, bevor Sie den Daemon starten.
Als Daemon betreiben
Direkt
Container / Docker
Wenn Collector und Anwendung einen Container teilen, führen Sie beide unter einem Prozess-Supervisor aus. Die einfachste Option istsupervisord; es ist in jeder großen Distribution enthalten, startet abgestürzte Prozesse neu, leitet Signale weiter und wartet auf einen sauberen Shutdown.
Dockerfile:
supervisord.conf:
autorestart=truebeim agenteye-collector: Neustart bei jedem Beenden (Absturz, Panic, OOM).autorestart=unexpectedbei der App: Neustart nur bei nicht-null Exit-Code, damit ein einmaliger Agent, der mit 0 beendet wird, keine Endlosschleife verursacht.stopwaitsecs=30: Gibt dem Collector Zeit, ausstehende Uploads bei SIGTERM zu beenden, bevor supervisord zu SIGKILL eskaliert.stdout_logfile=/dev/stdout,*_maxbytes=0: Ausgabe beider Programme zum Container-stdout streamen; keine Logdateien innerhalb des Containers.
AGENTEYE_URL / AGENTEYE_KEY (und alle TLS-Umgebungsvariablen) wie gehabt über docker run -e; supervisord erbt die Umgebung.
Separate Container? Wenn Sie den Collector als eigenständigen Container betreiben (Docker-Compose-Service, Kubernetes-Sidecar usw.), verwenden Sie kein supervisord; die Restart-Policy der Container-Runtime übernimmt diese Aufgabe bereits. Lesen Sie enterprise-docs/single-pod-deployment.md für das EKS-Sidecar-Muster.Kubernetes Liveness-Probe (gilt sowohl wenn der Collector allein als auch unter supervisord läuft):
$AGENTEYE_HOME/health.json. agenteye-collector health liest diese Datei und gibt nur dann 0 (gesund) zurück, wenn der Heartbeat aktuell ist und die Upload-Tasks normal laufen; es gibt 1 (ungesund) zurück, wenn der Heartbeat älter als 90 Sekunden ist (beispielsweise hat der Daemon aufgehört zu laufen) oder während Watcher und Sweeper nach einem unerwarteten Beenden neu starten. Der Heartbeat wird nur durch start geschrieben, führen Sie die Probe daher gegen den langlebigen Daemon und nicht gegen den einmaligen flush-Befehl aus.
systemd (Linux, empfohlen für Produktion)
/etc/agenteye/env:
launchd (macOS)
Collector aktualisieren
Der Collector aktualisiert sich nicht selbst. So führen Sie ein Upgrade durch:- Binärdatei: Laden Sie das neue
agenteye-collector-<os>-<arch>-Artefakt aus dem neuestencollector/v<version>-Release herunter (siehe Option A), ersetzen Sie/usr/local/bin/agenteye-collectorund starten Sie dann den Dienst neu (sudo systemctl restart agenteye-collector, erneuteslaunchctl loadoder Neustart Ihres Supervisors). - Docker:
docker pull ghcr.io/agenteye-enterprise/collector:beta-latest(oder einen festen:v<version>-Tag;:latestexistiert nur für stabile Releases) und den Container neu erstellen.
AGENTEYE_TOKEN wird benötigt, um neue Binärdateien/Images aus dem privaten Releases-Repository herunterzuladen, wird aber vom laufenden Daemon nicht benötigt.
Unterbefehle
| Befehl | Beschreibung |
|---|---|
agenteye-collector start | Startet den langlebigen Daemon. Beim Start werden alle Ereignisse aus einem vorherigen Lauf übertragen, dann werden neue Dateien überwacht und hochgeladen. Watcher und Sweeper starten bei unerwarteten Beenden automatisch neu, und alle 30 Sekunden wird ein Heartbeat in health.json geschrieben. |
agenteye-collector flush | Einmalig: Alle ausstehenden Dateien hochladen und beenden. Gibt No pending files. aus, wenn der Spool leer ist, andernfalls ein [UPLOADED]/[FAILED]-Log pro Datei und eine Done: <uploaded>/<total> uploaded, <failed> failed.-Zusammenfassung. |
agenteye-collector health | Liest den health.json-Heartbeat des Daemons. Gibt 0 zurück, wenn aktuell und gesund; gibt 1 zurück, wenn der Heartbeat veraltet ist (älter als 90 s) oder die Tasks neu starten. |
Verzeichnisstruktur
failed/ werden nicht automatisch erneut versucht. Um sie manuell wieder in die Warteschlange einzureihen, verschieben Sie sie zurück nach events/ und führen Sie agenteye-collector flush aus.
