> ## Documentation Index > Fetch the complete documentation index at: https://docs.befailproof.ai/llms.txt > Use this file to discover all available pages before exploring further. # Collector-Installation > Installationsdokumentation für den AgentEye Collector. 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](/de/agenteye/collector-migration). *** ## Voraussetzungen * Ihr `AGENTEYE_TOKEN`: ein GitHub PAT, den Sie selbst generieren (siehe [enterprise-docs/github-token.md](/de/agenteye/github-token)) * Die Server-URL und ein Collector-API-Schlüssel (siehe [enterprise-docs/api-keys.md](/de/agenteye/api-keys)) *** ## 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` 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` | **Download mit der `gh`-CLI** (Version ersetzen und das Artefakt Ihrer Plattform auswählen): ```bash theme={null} VERSION=0.0.1-beta.13 GITHUB_TOKEN=$AGENTEYE_TOKEN gh release download "collector/v${VERSION}" \ --repo agenteye-enterprise/releases \ --pattern 'agenteye-collector-linux-x86_64' chmod +x agenteye-collector-linux-x86_64 sudo mv agenteye-collector-linux-x86_64 /usr/local/bin/agenteye-collector ``` **Oder mit `curl`:** ```bash theme={null} VERSION=0.0.1-beta.13 ARTIFACT=agenteye-collector-linux-x86_64 curl -fsSL \ -H "Authorization: token $AGENTEYE_TOKEN" \ -L "https://github.com/agenteye-enterprise/releases/releases/download/collector%2Fv${VERSION}/${ARTIFACT}" \ -o agenteye-collector chmod +x agenteye-collector sudo mv agenteye-collector /usr/local/bin/agenteye-collector ``` *** ## Option B: Docker ```bash theme={null} echo $AGENTEYE_TOKEN | docker login ghcr.io -u x --password-stdin docker pull ghcr.io/agenteye-enterprise/collector:beta-latest ``` > 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:** ```bash theme={null} docker run -d --restart unless-stopped \ --name agenteye-collector \ -e AGENTEYE_URL=https://ingest.example.com/events \ -e AGENTEYE_KEY="$AGENTEYE_KEY" \ -e AGENTEYE_HOME=/data \ -v "$HOME/.agenteye:/data" \ ghcr.io/agenteye-enterprise/collector:beta-latest \ start ``` 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 | Option | CLI-Flag | Umgebungsvariable | config.json-Schlüssel | | ------------- | ------------- | ----------------- | --------------------- | | Backend-URL | `--url ` | `AGENTEYE_URL` | `"url"` | | API-Schlüssel | `--key ` | `AGENTEYE_KEY` | `"key"` | ### Optionale Einstellungen (mit Standardwerten) | Option | CLI-Flag | Umgebungsvariable | config.json-Schlüssel | Standard | | --------------------------------------- | ------------------------------ | --------------------------------- | -------------------------- | -------- | | Max. gleichzeitige Uploads | `--max-concurrent-uploads ` | `AGENTEYE_MAX_CONCURRENT_UPLOADS` | `"max_concurrent_uploads"` | `64` | | Sweep-Intervall (s) | `--sweep-interval ` | `AGENTEYE_SWEEP_INTERVAL` | `"sweep_interval_secs"` | `60` | | Minimales Datei-Alter für Sweep (s) | `--sweep-min-age ` | `AGENTEYE_SWEEP_MIN_AGE` | `"sweep_min_age_secs"` | `120` | | Max. Dateien pro Sweep | `--sweep-max-files ` | `AGENTEYE_SWEEP_MAX_FILES` | `"sweep_max_files"` | `64` | | Max. Upload-Versuche | `--max-retries ` | `AGENTEYE_MAX_RETRIES` | `"max_retries"` | `5` | | Basis-Verzögerung für Wiederholung (ms) | `--retry-base-delay ` | `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 ` | `AGENTEYE_TLS_CERT` | `"tls_cert"` | | Privater Client-Schlüssel (PEM) | `--tls-key ` | `AGENTEYE_TLS_KEY` | `"tls_key"` | | Benutzerdefiniertes CA-Zertifikat (PEM) | `--tls-ca ` | `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](/de/agenteye/single-pod-deployment) 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: ```yaml theme={null} # Beispiel: Collector-Deployment-Ausschnitt volumes: - name: mtls-certs secret: secretName: agenteye-collector-mtls containers: - name: collector env: - name: AGENTEYE_TLS_CERT value: /etc/agenteye/tls/tls.crt - name: AGENTEYE_TLS_KEY value: /etc/agenteye/tls/tls.key # Nur wenn das Server-Zertifikat nicht öffentlich vertrauenswürdig ist # (z. B. clustereigene selbstsignierte CA). Dasselbe Secret enthält # typischerweise ca.crt neben tls.crt/tls.key. - name: AGENTEYE_TLS_CA value: /etc/agenteye/tls/ca.crt volumeMounts: - name: mtls-certs mountPath: /etc/agenteye/tls readOnly: true ``` ### Beispiel `~/.agenteye/config.json` ```json theme={null} { "url": "https://ingest.example.com/events", "key": "sk-...", "max_concurrent_uploads": 16, "sweep_interval_secs": 30 } ``` Mit mTLS: ```json theme={null} { "url": "https://ingest.example.com/events", "key": "sk-...", "tls_cert": "/etc/agenteye/tls/tls.crt", "tls_key": "/etc/agenteye/tls/tls.key" } ``` Mit mTLS und benutzerdefinierter CA (selbstsignierter AgentEye-Server): ```json theme={null} { "url": "https://ingest.example.com/events", "key": "sk-...", "tls_cert": "/etc/agenteye/tls/tls.crt", "tls_key": "/etc/agenteye/tls/tls.key", "tls_ca": "/etc/agenteye/tls/ca.crt" } ``` 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: ```bash theme={null} mkdir -p ~/.agenteye cat > ~/.agenteye/config.json <<'EOF' { "url": "https://ingest.example.com/events", "key": "YOUR_COLLECTOR_KEY" } EOF ``` > 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): ```bash theme={null} agenteye-collector flush ``` `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] ` oder `[FAILED] ()`), gefolgt von einer `Done: / uploaded, 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 ```bash theme={null} agenteye-collector start ``` ### 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`:** ```Dockerfile theme={null} FROM python:3.11-slim RUN apt-get update && apt-get install -y --no-install-recommends supervisor \ && rm -rf /var/lib/apt/lists/* # Die agenteye-collector-Binärdatei aus dem offiziellen Image beziehen. # Einen spezifischen Tag angeben (:beta-latest für aktuelle Betas oder einen :v-Tag); # :latest wird nur für stabile Releases veröffentlicht. COPY --from=ghcr.io/agenteye-enterprise/collector:beta-latest \ /usr/local/bin/agenteye-collector /usr/local/bin/agenteye-collector COPY supervisord.conf /etc/supervisor/conf.d/agenteye.conf COPY my_agent.py /app/my_agent.py CMD ["/usr/bin/supervisord", "-c", "/etc/supervisor/supervisord.conf"] ``` **`supervisord.conf`:** ```ini theme={null} [supervisord] nodaemon=true user=root [program:agenteye-collector] command=/usr/local/bin/agenteye-collector start autorestart=true stopwaitsecs=30 stdout_logfile=/dev/stdout stdout_logfile_maxbytes=0 stderr_logfile=/dev/stderr stderr_logfile_maxbytes=0 [program:app] command=python /app/my_agent.py autorestart=unexpected stopwaitsecs=30 stdout_logfile=/dev/stdout stdout_logfile_maxbytes=0 stderr_logfile=/dev/stderr stderr_logfile_maxbytes=0 ``` 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](/de/agenteye/single-pod-deployment) für das EKS-Sidecar-Muster. **Kubernetes Liveness-Probe** (gilt sowohl wenn der Collector allein als auch unter supervisord läuft): ```yaml theme={null} livenessProbe: exec: command: ["agenteye-collector", "health"] initialDelaySeconds: 10 periodSeconds: 30 ``` 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) ```ini theme={null} # /etc/systemd/system/agenteye-collector.service [Unit] Description=AgentEye Collector After=network.target [Service] ExecStart=/usr/local/bin/agenteye-collector start Restart=on-failure RestartSec=5 EnvironmentFile=/etc/agenteye/env [Install] WantedBy=multi-user.target ``` Erstellen Sie `/etc/agenteye/env`: ``` AGENTEYE_URL=https://ingest.example.com/events AGENTEYE_KEY=YOUR_COLLECTOR_KEY ``` ```bash theme={null} sudo systemctl daemon-reload sudo systemctl enable --now agenteye-collector sudo systemctl status agenteye-collector ``` ### launchd (macOS) ```xml theme={null} Label ai.befailproof.agenteye-collector ProgramArguments /usr/local/bin/agenteye-collector start EnvironmentVariables AGENTEYE_URL https://ingest.example.com/events AGENTEYE_KEY YOUR_COLLECTOR_KEY RunAtLoad KeepAlive ``` ```bash theme={null} launchctl load ~/Library/LaunchAgents/ai.befailproof.agenteye-collector.plist ``` *** ## Collector aktualisieren Der Collector aktualisiert sich nicht selbst. So führen Sie ein Upgrade durch: * **Binärdatei:** Laden Sie das neue `agenteye-collector--`-Artefakt aus dem neuesten `collector/v`-Release herunter (siehe [Option A](#option-a-binary-recommended)), 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`-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 | 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, 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 ``` ~/.agenteye/ ├── config.json <- optionale Konfigurationsdatei ├── events/ <- .jsonl-Dateien, die vom SDK geschrieben und vom Collector aufgenommen werden └── failed/ <- Dateien, bei denen alle Upload-Versuche fehlgeschlagen sind ``` 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.