agenteye-collector garante que a telemetria dos seus agentes chegue ao AgentEye sem nunca bloquear sua aplicação. Seu código escreve eventos em um diretório local e segue em frente; o collector assume a responsabilidade a partir daí, fazendo o upload de cada arquivo em milissegundos e sobrevivendo a reinicializações, quedas de rede e erros transitórios do servidor. Uploads com falha são reprocessados com backoff exponencial, e uma varredura periódica de recuperação recoloca na fila tudo que ficou para trás por um crash ou deploy. O resultado é uma entrega durável no esquema dispare-e-esqueça: seus agentes continuam rodando em velocidade máxima enquanto o collector garante que nenhum evento seja perdido no caminho.
Mecanicamente, o collector é um daemon leve que monitora $AGENTEYE_HOME/events/ (padrão: ~/.agenteye/events/) em busca de arquivos .jsonl escritos pelo SDK Python e os envia para o servidor AgentEye.
Renomeado: o comando do collector agora éagenteye-collector(antes eraagenteye). O nome curtoagenteyeagora pertence à CLI do AgentEye. Se você está atualizando uma instalação existente, consulte enterprise-docs/collector-migration.md.
Pré-requisitos
- Seu
AGENTEYE_TOKEN: um PAT do GitHub que você mesmo gera (veja enterprise-docs/github-token.md) - A URL do servidor e uma chave de API do collector (veja enterprise-docs/api-keys.md)
Opção A: Binário (recomendado)
Binários estáticos pré-compilados estão disponíveis para Linux, macOS e Windows (x86_64 e arm64). Baixe o binário para sua plataforma diretamente do repositórioagenteye-enterprise/releases na tag de release mais recente collector/v<version>.
Nomes de artefatos disponíveis:
| Plataforma | Artefato |
|---|---|
| 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 (substitua a versão e escolha o artefato da sua plataforma):
curl:
Opção B: Docker
As builds beta atuais publicam a tag flutuanteExecutar::beta-latest;:latesté atribuída apenas a releases estáveis. Para deploys reproduzíveis, prefira uma tag de versão fixada como:v0.0.1-beta.13.
AGENTEYE_HOME explicitamente e monte o spool do host nele. O volume compartilha o mesmo diretório ~/.agenteye/ que o SDK Python escreve no host. Se você já definiu AGENTEYE_HOME em outro lugar no host, monte esse diretório em vez de $HOME/.agenteye.
Configuração
Todas as opções podem ser definidas de três formas (maior prioridade primeiro):- Flag CLI:
agenteye-collector start --url https://... - Variável de ambiente:
AGENTEYE_URL=https://... - Arquivo de configuração:
~/.agenteye/config.json
Opções obrigatórias
| Opção | Flag CLI | Var de ambiente | Chave no config.json |
|---|---|---|---|
| URL do backend | --url <URL> | AGENTEYE_URL | "url" |
| Chave de API | --key <KEY> | AGENTEYE_KEY | "key" |
Opções opcionais (com valores padrão)
| Opção | Flag CLI | Var de ambiente | Chave no config.json | Padrão |
|---|---|---|---|---|
| Uploads simultâneos máximos | --max-concurrent-uploads <N> | AGENTEYE_MAX_CONCURRENT_UPLOADS | "max_concurrent_uploads" | 64 |
| Intervalo do sweeper (s) | --sweep-interval <S> | AGENTEYE_SWEEP_INTERVAL | "sweep_interval_secs" | 60 |
| Idade mínima de arquivo do sweeper (s) | --sweep-min-age <S> | AGENTEYE_SWEEP_MIN_AGE | "sweep_min_age_secs" | 120 |
| Máximo de arquivos por varredura | --sweep-max-files <N> | AGENTEYE_SWEEP_MAX_FILES | "sweep_max_files" | 64 |
| Máximo de tentativas de upload | --max-retries <N> | AGENTEYE_MAX_RETRIES | "max_retries" | 5 |
| Delay base de retry (ms) | --retry-base-delay <MS> | AGENTEYE_RETRY_BASE_DELAY | "retry_base_delay_ms" | 1000 |
Opções de mTLS (opcional)
Para deploys que exigem TLS mútuo (mTLS), o collector pode apresentar um certificado de cliente durante o handshake TLS. Quando essas opções não estão definidas, o collector utiliza HTTPS padrão.| Opção | Flag CLI | Var de ambiente | Chave no config.json |
|---|---|---|---|
| Certificado do cliente (PEM) | --tls-cert <PATH> | AGENTEYE_TLS_CERT | "tls_cert" |
| Chave privada do cliente (PEM) | --tls-key <PATH> | AGENTEYE_TLS_KEY | "tls_key" |
| Certificado CA personalizado (PEM) | --tls-ca <PATH> | AGENTEYE_TLS_CA | "tls_ca" |
--tls-cert e --tls-key devem ser definidos juntos. Os arquivos devem estar em formato PEM.
--tls-ca é independente e só é necessário quando o servidor AgentEye apresenta um certificado TLS que não foi emitido por uma CA publicamente confiável (por exemplo, autoassinado por um emissor cert-manager dentro do cluster quando você não tem um domínio DNS real). O collector adiciona a CA fornecida como uma âncora de confiança adicional; as raízes públicas padrão continuam confiáveis, portanto implantações existentes não são afetadas. O arquivo pode conter um único certificado PEM ou uma cadeia completa (múltiplos blocos PEM concatenados).
Rodando o collector como sidecar no pod da sua aplicação? Veja enterprise-docs/single-pod-deployment.md para o padrão completo no EKS: bundle mTLS entregue via AWS Secrets Manager + Secrets Store CSI Driver + IRSA, com rotação automática.
Ao rodar no Kubernetes com o padrão de repasse de Secret, monte o Secret de certificado como um volume e aponte esses caminhos para os arquivos montados:
Exemplo de ~/.agenteye/config.json
AGENTEYE_HOME estiver definido, esse diretório é usado em vez de ~/.agenteye.
Configuração inicial
Após instalar, configure o collector com a URL do seu servidor e a chave de API:UseTeste a conexão (flush único, encerra após drenar os eventos pendentes):httpspara qualquer implantação que cruze uma rede não confiável para que os eventos não sejam enviados em texto simples. A forma comhttp://seu-servidor:8080/eventsé adequada apenas para testes puramente locais em um servidor no mesmo host.
flush reporta seu progresso no stdout. Quando o spool está vazio, imprime No pending files. e sai com código 0. Caso contrário, imprime uma linha por arquivo ([UPLOADED] <file> ou [FAILED] <file> (<reason>)), seguida de um resumo Done: <uploaded>/<total> uploaded, <failed> failed.. Isso torna o flush uma verificação pontual conveniente para confirmar que sua URL, chave e configurações TLS estão corretas antes de iniciar o daemon.
Executando como Daemon
Diretamente
Container / Docker
Quando o collector e sua aplicação compartilham um container, execute-os sob um supervisor de processos. A opção mais simples é osupervisord; ele está disponível em todas as principais distribuições, reinicia processos com crash, encaminha sinais e aguarda o encerramento gracioso.
Dockerfile:
supervisord.conf:
autorestart=trueno agenteye-collector: reinicia em qualquer saída (crash, panic, OOM).autorestart=unexpectedna aplicação: reinicia apenas em saída com código não-zero, para que um agente pontual que sai com 0 não entre em loop.stopwaitsecs=30: dá ao collector tempo para drenar uploads pendentes no SIGTERM antes que o supervisord escale para SIGKILL.stdout_logfile=/dev/stdout,*_maxbytes=0: transmite a saída de ambos os programas para o stdout do container; sem arquivos de log dentro do container.
AGENTEYE_URL / AGENTEYE_KEY (e quaisquer variáveis de ambiente TLS) via docker run -e como antes; o supervisord herda o ambiente.
Containers separados? Se você roda o collector como seu próprio container (serviço do Docker Compose, sidecar no Kubernetes, etc.), não use o supervisord; a política de restart do runtime de container já faz esse trabalho. Veja enterprise-docs/single-pod-deployment.md para o padrão de sidecar no EKS.Liveness probe para Kubernetes (aplica-se tanto quando o collector roda sozinho quanto sob o supervisord):
$AGENTEYE_HOME/health.json a cada 30 segundos. O agenteye-collector health lê esse arquivo e sai com 0 (saudável) apenas quando o heartbeat está fresco e as tarefas de upload estão funcionando normalmente; sai com 1 (não saudável) quando o heartbeat tem mais de 90 segundos (por exemplo, o daemon parou) ou enquanto o watcher e o sweeper estão reiniciando após uma saída inesperada. O heartbeat é escrito apenas pelo start, portanto execute a probe contra o daemon de longa duração e não contra o comando pontual flush.
systemd (Linux, recomendado para produção)
/etc/agenteye/env:
launchd (macOS)
Atualizando o Collector
O collector não se atualiza automaticamente. Para atualizar:- Binário: baixe o novo artefato
agenteye-collector-<os>-<arch>da release mais recentecollector/v<version>(veja Opção A), substitua/usr/local/bin/agenteye-collectore reinicie o serviço (sudo systemctl restart agenteye-collector,launchctl loadnovamente, ou reinicie seu supervisor). - Docker: execute
docker pull ghcr.io/agenteye-enterprise/collector:beta-latest(ou uma tag fixada:v<version>;:latestexiste apenas para releases estáveis) e recrie o container.
AGENTEYE_TOKEN é necessário para baixar novos binários/imagens do repositório privado de releases, mas não é necessário para o daemon em execução.
Subcomandos
| Comando | Descrição |
|---|---|
agenteye-collector start | Inicia o daemon de longa duração. Na inicialização, faz o flush de quaisquer eventos deixados por uma execução anterior, depois monitora novos arquivos e os envia. O watcher e o sweeper reiniciam automaticamente em caso de saída inesperada, e um heartbeat é gravado em health.json a cada 30 segundos. |
agenteye-collector flush | Pontual: envia todos os arquivos pendentes e encerra. Imprime No pending files. quando o spool está vazio; caso contrário, um log por arquivo com [UPLOADED]/[FAILED] e um resumo Done: <uploaded>/<total> uploaded, <failed> failed.. |
agenteye-collector health | Lê o heartbeat health.json do daemon. Sai com 0 quando fresco e saudável; sai com 1 quando o heartbeat está desatualizado (mais de 90s) ou as tarefas estão reiniciando. |
Estrutura de Diretórios
failed/ não são reprocessados automaticamente. Para recolocá-los na fila manualmente, mova-os de volta para events/ e execute agenteye-collector flush.
