Pular para o conteúdo principal
O daemon 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 era agenteye). O nome curto agenteye agora pertence à CLI do AgentEye. Se você está atualizando uma instalação existente, consulte enterprise-docs/collector-migration.md.

Pré-requisitos


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ório agenteye-enterprise/releases na tag de release mais recente collector/v<version>. Nomes de artefatos disponíveis:
PlataformaArtefato
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
Baixe com a CLI gh (substitua a versão e escolha o artefato da sua plataforma):
Ou com curl:

Opção B: Docker

As builds beta atuais publicam a tag flutuante :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.
Executar:
A imagem oficial roda como um usuário não-root, então defina 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):
  1. Flag CLI: agenteye-collector start --url https://...
  2. Variável de ambiente: AGENTEYE_URL=https://...
  3. Arquivo de configuração: ~/.agenteye/config.json

Opções obrigatórias

OpçãoFlag CLIVar de ambienteChave 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çãoFlag CLIVar de ambienteChave no config.jsonPadrã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çãoFlag CLIVar de ambienteChave 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

Com mTLS:
Com mTLS mais uma CA personalizada (servidor AgentEye autoassinado):
Se 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:
Use https para qualquer implantação que cruze uma rede não confiável para que os eventos não sejam enviados em texto simples. A forma com http://seu-servidor:8080/events é adequada apenas para testes puramente locais em um servidor no mesmo host.
Teste a conexão (flush único, encerra após drenar os eventos pendentes):
O 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 é o supervisord; ele está disponível em todas as principais distribuições, reinicia processos com crash, encaminha sinais e aguarda o encerramento gracioso. Dockerfile:
supervisord.conf:
Por que essas configurações:
  • autorestart=true no agenteye-collector: reinicia em qualquer saída (crash, panic, OOM).
  • autorestart=unexpected na 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.
Passe 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):
O daemon em execução grava um heartbeat em $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)

Crie /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 recente collector/v<version> (veja Opção A), substitua /usr/local/bin/agenteye-collector e reinicie o serviço (sudo systemctl restart agenteye-collector, launchctl load novamente, ou reinicie seu supervisor).
  • Docker: execute docker pull ghcr.io/agenteye-enterprise/collector:beta-latest (ou uma tag fixada :v<version>; :latest existe 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

ComandoDescrição
agenteye-collector startInicia 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 flushPontual: 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 healthLê 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

Arquivos em failed/ não são reprocessados automaticamente. Para recolocá-los na fila manualmente, mova-os de volta para events/ e execute agenteye-collector flush.