Перейти к основному содержанию
Демон agenteye-collector гарантирует, что телеметрия ваших агентов достигает AgentEye без блокирования приложения. Ваш код записывает события в локальный каталог и продолжает работу; collector берет на себя ответственность, загружая каждый файл в течение миллисекунд и сохраняя работоспособность при перезагрузках, сбоях сети и временных ошибках сервера. Неудачные загрузки повторяются с экспоненциальной задержкой, а периодическая восстановительная развёртка повторно ставит в очередь всё, что осталось после сбоя или развёртывания. Результат — надежная доставка с принципом «отправить и забыть»: ваши агенты работают на полной скорости, а collector гарантирует, что события не потеряются в пути. По сути, collector — это лёгкий демон, который отслеживает $AGENTEYE_HOME/events/ (по умолчанию: ~/.agenteye/events/) для файлов .jsonl, записанных Python SDK, и загружает их на сервер AgentEye.
Переименовано: команда collector теперь agenteye-collector (раньше это был agenteye). Краткое имя agenteye теперь принадлежит CLI AgentEye. Если вы обновляете существующую установку, см. enterprise-docs/collector-migration.md.

Предварительные требования


Вариант A: Бинарный файл (рекомендуется)

Предварительно собранные статические бинарные файлы доступны для Linux, macOS и Windows (x86_64 и arm64). Загрузите бинарный файл для вашей платформы прямо из репозитория agenteye-enterprise/releases под последний тег релиза collector/v<version>. Доступные имена артефактов:
ПлатформаАртефакт
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
Загрузка с помощью CLI gh (замените версию и выберите артефакт для вашей платформы):
Или с помощью curl:

Вариант B: Docker

Текущие бета-сборки публикуют плавающий тег :beta-latest; :latest назначается только стабильным релизам. Для повторяемых развёртываний предпочитайте закреплённый тег версии, такой как :v0.0.1-beta.13.
Запуск:
Официальный образ запускается от непривилегированного пользователя, поэтому задайте AGENTEYE_HOME явно и смонтируйте хостовый буфер к нему. Монтирование тома использует тот же каталог ~/.agenteye/, в который Python SDK записывает на хосте. Если вы уже установили AGENTEYE_HOME в другом месте на хосте, смонтируйте вместо этого этот каталог.

Конфигурация

Все параметры можно установить тремя способами (в порядке приоритета):
  1. Флаг CLI: agenteye-collector start --url https://...
  2. Переменная окружения: AGENTEYE_URL=https://...
  3. Файл конфигурации: ~/.agenteye/config.json

Обязательные параметры

ПараметрФлаг CLIПеременная окруженияКлюч config.json
URL сервера--url <URL>AGENTEYE_URL"url"
Ключ API--key <KEY>AGENTEYE_KEY"key"

Опциональные параметры (со значениями по умолчанию)

ПараметрФлаг CLIПеременная окруженияКлюч config.jsonПо умолчанию
Макс. одновременных загрузок--max-concurrent-uploads <N>AGENTEYE_MAX_CONCURRENT_UPLOADS"max_concurrent_uploads"64
Интервал развёртки (сек)--sweep-interval <S>AGENTEYE_SWEEP_INTERVAL"sweep_interval_secs"60
Мин. возраст файла развёртки (сек)--sweep-min-age <S>AGENTEYE_SWEEP_MIN_AGE"sweep_min_age_secs"120
Макс. файлов в развёртке--sweep-max-files <N>AGENTEYE_SWEEP_MAX_FILES"sweep_max_files"64
Макс. попыток загрузки--max-retries <N>AGENTEYE_MAX_RETRIES"max_retries"5
Базовая задержка повтора (мс)--retry-base-delay <MS>AGENTEYE_RETRY_BASE_DELAY"retry_base_delay_ms"1000

Параметры mTLS (опционально)

Для развёртываний, требующих взаимной TLS (mTLS), collector может представить сертификат клиента во время установления TLS. Если эти параметры не установлены, collector использует стандартный HTTPS.
ПараметрФлаг CLIПеременная окруженияКлюч config.json
Сертификат клиента (PEM)--tls-cert <PATH>AGENTEYE_TLS_CERT"tls_cert"
Приватный ключ клиента (PEM)--tls-key <PATH>AGENTEYE_TLS_KEY"tls_key"
Пользовательский сертификат CA (PEM)--tls-ca <PATH>AGENTEYE_TLS_CA"tls_ca"
--tls-cert и --tls-key должны быть установлены вместе. Файлы должны быть в формате PEM. --tls-ca независим и требуется только тогда, когда сервер AgentEye представляет TLS-сертификат, который не выдан общедоступным CA (например, самоподписанный издателем cert-manager в кластере, когда у вас нет настоящего DNS-домена). Collector добавляет предоставленный CA как дополнительное доверенное якорё; стандартные корни общедоступности остаются доверенными, поэтому существующие развёртывания не затрагиваются. Файл может содержать один PEM-сертификат или полную цепь (несколько объединённых PEM-блоков). Запуск collector как sidecar в поде приложения? См. enterprise-docs/single-pod-deployment.md для полного паттерна EKS: пакет mTLS, доставляемый через AWS Secrets Manager + Secrets Store CSI Driver + IRSA с автоматической ротацией. При запуске в Kubernetes с паттерном передачи Secret смонтируйте Secret сертификата как том и укажите эти пути на смонтированные файлы:

Пример ~/.agenteye/config.json

С mTLS:
С mTLS плюс пользовательский CA (самоподписанный сервер AgentEye):
Если установлен AGENTEYE_HOME, используется этот каталог вместо ~/.agenteye.

Первоначальная настройка

После установки настройте collector с URL сервера и ключом API:
Используйте https для любого развёртывания, пересекающего ненадёжную сеть, чтобы события не отправлялись в открытом виде. Открытая форма http://your-server-host:8080/events подходит только для чисто локального тестирования против сервера на том же хосте.
Протестируйте соединение (одноразовое полоскание, выход после слива ожидающих событий):
flush сообщает о прогрессе на stdout. Когда буфер пуст, выводит No pending files. и выходит с кодом 0. В противном случае выводит одну строку на файл ([UPLOADED] <file> или [FAILED] <file> (<reason>)), затем итоговую сводку Done: <uploaded>/<total> uploaded, <failed> failed.. Это делает flush удобной одноразовой проверкой, что ваш URL, ключ и параметры TLS верны перед запуском демона.

Запуск как демон

Прямой запуск

Контейнер / Docker

Когда collector и приложение используют один контейнер, запустите их под супервизором процессов. Самый простой вариант — supervisord; он поставляется в каждом основном дистрибутиве, перезапускает упавшие процессы, перенаправляет сигналы и ждёт корректного завершения. Dockerfile:
supervisord.conf:
Почему эти параметры:
  • autorestart=true на agenteye-collector: перезапуск при любом выходе (сбой, паника, OOM).
  • autorestart=unexpected на приложении: перезапуск только при ненулевом выходе, поэтому одноразовый агент, выходящий с 0, не зацикливается.
  • stopwaitsecs=30: дает collector возможность слить ожидающие загрузки при SIGTERM перед тем, как supervisord переключится на SIGKILL.
  • stdout_logfile=/dev/stdout, *_maxbytes=0: потоковая передача вывода обоих программ на контейнер stdout; без логфайлов внутри контейнера.
Передайте AGENTEYE_URL / AGENTEYE_KEY (и любые переменные TLS) на docker run -e как раньше; supervisord наследует окружение.
Отдельные контейнеры? Если вы запускаете collector как собственный контейнер (сервис Docker Compose, sidecar Kubernetes и т.д.), не используйте supervisord; политика перезагрузки runtime контейнера уже выполняет эту работу. См. enterprise-docs/single-pod-deployment.md для паттерна EKS sidecar.
Проверка живучести Kubernetes (применяется независимо от того, работает ли collector отдельно или под supervisord):
Работающий демон записывает пульс в $AGENTEYE_HOME/health.json каждые 30 секунд. agenteye-collector health читает этот файл и выходит с кодом 0 (здоров) только если пульс свежий и задачи загрузки работают нормально; выходит с кодом 1 (болен) если пульс старше 90 секунд (например, демон остановился) или пока наблюдатель и развёртка перезагружаются после непредвиденного выхода. Пульс записывается только командой start, поэтому запустите проверку против долгоживущего демона, а не одноразовой команды flush.

systemd (Linux, рекомендуется для production)

Создайте /etc/agenteye/env:

launchd (macOS)


Обновление Collector

Collector не обновляется самостоятельно. Для обновления:
  • Бинарный файл: загрузите новый артефакт agenteye-collector-<os>-<arch> из последнего релиза collector/v<version> (см. Вариант A), замените /usr/local/bin/agenteye-collector, затем перезагрузите сервис (sudo systemctl restart agenteye-collector, переза-launchctl load или перезагрузите ваш супервизор).
  • Docker: docker pull ghcr.io/agenteye-enterprise/collector:beta-latest (или закреплённый тег :v<version>; :latest существует только для стабильных релизов) и пересоздайте контейнер.
AGENTEYE_TOKEN требуется для загрузки новых бинарных файлов/образов из приватного репозитория релизов, но не требуется работающему демону.

Подкоманды

КомандаОписание
agenteye-collector startЗапустить долгоживущий демон. При запуске он полоскает все события, оставшиеся с предыдущего запуска, затем отслеживает новые файлы и загружает их. Наблюдатель и развёртка автоматически перезагружаются при непредвиденном выходе, и пульс записывается в health.json каждые 30 секунд.
agenteye-collector flushОдноразово: загрузить все ожидающие файлы и выйти. Выводит No pending files. если буфер пуст, в противном случае логирует для каждого файла [UPLOADED]/[FAILED] и итоговую сводку Done: <uploaded>/<total> uploaded, <failed> failed..
agenteye-collector healthПрочитать пульс health.json демона. Выход 0 если свежий и здоров; выход 1 если пульс устарел (старше 90 сек) или задачи перезагружаются.

Макет каталога

Файлы в failed/ не повторяются автоматически. Чтобы вручную переставить их в очередь, переместите их обратно в events/ и запустите agenteye-collector flush.