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.
Предварительные требования
- Ваш
AGENTEYE_TOKEN: GitHub PAT, который вы создаёте сами (см. enterprise-docs/github-token.md) - URL сервера и ключ API collector (см. enterprise-docs/api-keys.md)
Вариант A: Бинарный файл (рекомендуется)
Предварительно собранные статические бинарные файлы доступны для Linux, macOS и Windows (x86_64 и arm64). Загрузите бинарный файл для вашей платформы прямо из репозиторияagenteye-enterprise/releases под последний тег релиза collector/v<version>.
Доступные имена артефактов:
| Платформа | Артефакт |
|---|---|
| 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 (замените версию и выберите артефакт для вашей платформы):
curl:
Вариант B: Docker
Текущие бета-сборки публикуют плавающий тегЗапуск::beta-latest;:latestназначается только стабильным релизам. Для повторяемых развёртываний предпочитайте закреплённый тег версии, такой как:v0.0.1-beta.13.
AGENTEYE_HOME явно и смонтируйте хостовый буфер к нему. Монтирование тома использует тот же каталог ~/.agenteye/, в который Python SDK записывает на хосте. Если вы уже установили AGENTEYE_HOME в другом месте на хосте, смонтируйте вместо этого этот каталог.
Конфигурация
Все параметры можно установить тремя способами (в порядке приоритета):- Флаг CLI:
agenteye-collector start --url https://... - Переменная окружения:
AGENTEYE_URL=https://... - Файл конфигурации:
~/.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
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.
