Zum Hauptinhalt springen
Der 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 jetzt agenteye-collector (früher war es agenteye). Der kurze Name agenteye gehört nun zur AgentEye-CLI. Wenn Sie eine bestehende Installation aktualisieren, lesen Sie enterprise-docs/collector-migration.md.

Voraussetzungen


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 Repository agenteye-enterprise/releases unter dem neuesten Release-Tag collector/v<version> herunter. Verfügbare Artefaktnamen:
PlattformArtefakt
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
Download mit der gh-CLI (Version ersetzen und das Artefakt Ihrer Plattform auswählen):
Oder mit curl:

Option B: Docker

Aktuelle Beta-Builds veröffentlichen den variablen Tag :beta-latest; :latest wird nur stabilen Releases zugewiesen. Für reproduzierbare Deployments sollten Sie einen festen Versions-Tag wie :v0.0.1-beta.13 bevorzugen.
Ausführen:
Das offizielle Image läuft als Nicht-Root-Benutzer, daher setzen Sie 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):
  1. CLI-Flag: agenteye-collector start --url https://...
  2. Umgebungsvariable: AGENTEYE_URL=https://...
  3. Konfigurationsdatei: ~/.agenteye/config.json

Pflichtoptionen

OptionCLI-FlagUmgebungsvariableconfig.json-Schlüssel
Backend-URL--url <URL>AGENTEYE_URL"url"
API-Schlüssel--key <KEY>AGENTEYE_KEY"key"

Optionale Einstellungen (mit Standardwerten)

OptionCLI-FlagUmgebungsvariableconfig.json-SchlüsselStandard
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.
OptionCLI-FlagUmgebungsvariableconfig.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

Mit mTLS:
Mit mTLS und benutzerdefinierter CA (selbstsignierter AgentEye-Server):
Wenn 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 Sie https für jedes Deployment, das ein nicht vertrauenswürdiges Netzwerk überquert, damit Ereignisse nicht im Klartext gesendet werden. Die Klartextform http://your-server-host:8080/events ist nur für rein lokale Tests gegen einen Server auf demselben Host geeignet.
Verbindung testen (einmaliger Flush, beendet sich nach dem Leeren ausstehender Ereignisse):
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 ist supervisord; 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:
Begründung dieser Einstellungen:
  • autorestart=true beim agenteye-collector: Neustart bei jedem Beenden (Absturz, Panic, OOM).
  • autorestart=unexpected bei 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.
Übergeben Sie 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):
Der laufende Daemon schreibt alle 30 Sekunden einen Heartbeat in $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)

Erstellen Sie /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 neuesten collector/v<version>-Release herunter (siehe Option A), ersetzen Sie /usr/local/bin/agenteye-collector und starten Sie dann den Dienst neu (sudo systemctl restart agenteye-collector, erneutes launchctl load oder Neustart Ihres Supervisors).
  • Docker: docker pull ghcr.io/agenteye-enterprise/collector:beta-latest (oder einen festen :v<version>-Tag; :latest existiert 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

BefehlBeschreibung
agenteye-collector startStartet 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 flushEinmalig: 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 healthLiest 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

Dateien in 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.