> ## 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. # Instalação do Collector > Documentação de instalação do AgentEye Collector. 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](/pt-br/agenteye/collector-migration). *** ## Pré-requisitos * Seu `AGENTEYE_TOKEN`: um PAT do GitHub que você mesmo gera (veja [enterprise-docs/github-token.md](/pt-br/agenteye/github-token)) * A URL do servidor e uma chave de API do collector (veja [enterprise-docs/api-keys.md](/pt-br/agenteye/api-keys)) *** ## 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`. 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` | **Baixe com a CLI `gh`** (substitua a versão e escolha o artefato da sua plataforma): ```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 ``` **Ou com `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 ``` *** ## Opção 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 ``` > 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:** ```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 ``` 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ção | Flag CLI | Var de ambiente | Chave no config.json | | -------------- | ------------- | --------------- | -------------------- | | URL do backend | `--url ` | `AGENTEYE_URL` | `"url"` | | Chave de API | `--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 ` | `AGENTEYE_MAX_CONCURRENT_UPLOADS` | `"max_concurrent_uploads"` | `64` | | Intervalo do sweeper (s) | `--sweep-interval ` | `AGENTEYE_SWEEP_INTERVAL` | `"sweep_interval_secs"` | `60` | | Idade mínima de arquivo do sweeper (s) | `--sweep-min-age ` | `AGENTEYE_SWEEP_MIN_AGE` | `"sweep_min_age_secs"` | `120` | | Máximo de arquivos por varredura | `--sweep-max-files ` | `AGENTEYE_SWEEP_MAX_FILES` | `"sweep_max_files"` | `64` | | Máximo de tentativas de upload | `--max-retries ` | `AGENTEYE_MAX_RETRIES` | `"max_retries"` | `5` | | Delay base de retry (ms) | `--retry-base-delay ` | `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 ` | `AGENTEYE_TLS_CERT` | `"tls_cert"` | | Chave privada do cliente (PEM) | `--tls-key ` | `AGENTEYE_TLS_KEY` | `"tls_key"` | | Certificado CA personalizado (PEM) | `--tls-ca ` | `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](/pt-br/agenteye/single-pod-deployment) 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: ```yaml theme={null} # Exemplo: trecho de Deployment do collector 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 # Somente quando o certificado do servidor não é publicamente confiável # (ex: CA autoassinada dentro do cluster). O mesmo Secret normalmente # traz ca.crt junto com tls.crt/tls.key. - name: AGENTEYE_TLS_CA value: /etc/agenteye/tls/ca.crt volumeMounts: - name: mtls-certs mountPath: /etc/agenteye/tls readOnly: true ``` ### Exemplo de `~/.agenteye/config.json` ```json theme={null} { "url": "https://ingest.example.com/events", "key": "sk-...", "max_concurrent_uploads": 16, "sweep_interval_secs": 30 } ``` Com 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" } ``` Com mTLS mais uma CA personalizada (servidor AgentEye autoassinado): ```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" } ``` 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: ```bash theme={null} mkdir -p ~/.agenteye cat > ~/.agenteye/config.json <<'EOF' { "url": "https://ingest.example.com/events", "key": "YOUR_COLLECTOR_KEY" } EOF ``` > 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): ```bash theme={null} agenteye-collector flush ``` 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] ` ou `[FAILED] ()`), seguida de um resumo `Done: / uploaded, 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 ```bash theme={null} agenteye-collector start ``` ### 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`:** ```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/* # Obtém o binário agenteye-collector da imagem oficial. # Fixe uma tag específica (:beta-latest para betas atuais, ou uma tag :v); # :latest é publicada apenas para releases estáveis. 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 ``` 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](/pt-br/agenteye/single-pod-deployment) para o padrão de sidecar no EKS. **Liveness probe para Kubernetes** (aplica-se tanto quando o collector roda sozinho quanto sob o supervisord): ```yaml theme={null} livenessProbe: exec: command: ["agenteye-collector", "health"] initialDelaySeconds: 10 periodSeconds: 30 ``` 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) ```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 ``` Crie `/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 ``` *** ## Atualizando o Collector O collector não se atualiza automaticamente. Para atualizar: * **Binário:** baixe o novo artefato `agenteye-collector--` da release mais recente `collector/v` (veja [Opção A](#option-a-binary-recommended)), 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`; `: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 | 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, 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 ``` ~/.agenteye/ ├── config.json <- arquivo de configuração opcional ├── events/ <- arquivos .jsonl escritos pelo SDK, coletados pelo collector └── failed/ <- arquivos que falharam em todas as tentativas de upload ``` 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`.