Sonda coletora: OpenTelemetry local e arquivos de log

01O que é monitorado

• OTLP local: logs e traces de qualquer serviço da rede que fale OpenTelemetry (@evobits/node ou o SDK oficial de qualquer linguagem), por HTTP na porta 4318 e, se ligado, por gRPC na 4317.
• Arquivos de log da máquina da sonda, em três formatos:
  • Texto: cada linha vira um log; o nível sai da primeira palavra de nível da linha (ERROR, WARN, INFO, DEBUG, também ERRO e AVISO); as regras de extração do serviço rodam sobre a linha.
  • nginx (formato combinado, o mesmo do Apache e afins): método, caminho, código, tamanho, agente e IP do cliente viram atributos; o nível vem do código (5xx erro, 4xx aviso).
  • JSON por linha: um objeto por linha; os campos viram atributos sozinhos; nível de level, severity, nivel ou lvl, e hora de time, timestamp, @timestamp ou ts.

02Como funciona

OTLP local

• Só na sonda remota (a sonda da nuvem nunca escuta OTLP nem lê arquivo), versão 1.0.9 ou mais nova, com o módulo Aplicações ligado.
• Escuta em todas as interfaces da máquina, na porta escolhida no painel. HTTP aceita /v1/traces, /v1/logs e /v1/metrics, protobuf ou JSON, gzip; gRPC sem TLS, os três serviços de Export do OTLP.
• O token do serviço é obrigatório também na rede local (Authorization: Bearer eva_..., ou o metadado authorization no gRPC). A sonda confere o token contra a lista que recebeu do evobits, sem precisar de internet. Token do navegador e pedido vindo de navegador são recusados: a sonda não vira porta aberta.
• O pedido aceito vai inteiro para o buffer em disco e a sonda responde 200 na hora. O token em claro nunca vai para o disco (o buffer guarda o hash). A máscara roda no evobits, como sempre.
• Mesmos limites da internet: 8 MB por pedido (32 MB descomprimido), 20 pedidos por segundo por token (rajada de 100), 30 tentativas sem token válido por minuto por origem. Se o evobits avisou o corte da cota para aquele token, a sonda já responde como ele (200 com X-Evobits-Corte) e não guarda.

Arquivos de log

• A sonda só lê dentro das pastas liberadas na instalação (instalar.sh --logs, ou o volume montado na imagem Docker). O painel escolhe o arquivo, mas nunca passa dessas pastas: o painel não consegue mandar a sonda ler /etc/shadow.
• Pastas recusadas sempre: /, /etc, /proc, /sys, /dev, /boot, /root, /run, /home e as pastas da própria sonda. Recusados também: caminho com .., link simbólico que aponta para fora, arquivo que não é comum (dispositivo, fila, socket) e arquivo com mais de um link físico.
• * vale só no nome do arquivo (/var/log/minha-app/*.log), até 50 arquivos por caminho.
• Nunca escreve nos arquivos. Na primeira vez começa do fim (não reenvia o histórico), guarda a posição de cada arquivo e acompanha a rotação: quando o nome passa a apontar para um arquivo novo, lê o resto do antigo e começa o novo do zero; arquivo truncado volta ao zero.
• Linha até 16 kB. A máscara roda na sonda antes do buffer, e de novo no evobits.
• Cada arquivo é ligado a um serviço de Aplicações. O serviço precisa ter pelo menos um token ativo.

Buffer e queda de internet

• Buffer de Aplicações separado do buffer de amostras de sensor, com teto de 2 GB (SONDA_BUFFER_APLICACOES_MAX_MB): um serviço falador não empurra amostra de sensor para fora numa queda.
• Sem internet, tudo fica no disco. Na volta, a sonda manda um pedido por vez, na ordem. Acima do teto, o segmento mais antigo é descartado.
• Recusa definitiva do evobits (token revogado, pedido inválido) tira o pedido do buffer e conta como descartado; 429, 5xx e falha de rede esperam e tentam de novo, sem apagar nada.

03Onde aparece

Sondas > a sonda > Receptores, dois cartões ao lado de Traps, Syslog e Fluxos:

• OpenTelemetry (OTLP): HTTP e gRPC com chave de liga e desliga, porta e estado ("Escutando"); recebidos em 24 h, recusados, bytes no buffer; o que pôr no serviço; os serviços vistos por aqui.
• Arquivos de log: caminho, serviço, formato ("texto", "texto, regra", "nginx", "JSON por linha"), linhas por minuto, última linha e estado. Arquivo fora das pastas aparece como "Recusado", com o motivo.

Os dados aparecem nas telas de Aplicações do serviço, como se tivessem vindo pela internet.

04Alertas

Os do serviço (rota, contagem de log, erro novo, regressão). A sonda em si segue com os alertas de sempre.

05Limites e privacidade

• A sonda só recebe de quem está na mesma rede ou numa rota até ela; ela nunca escuta a internet por conta própria. Libere a porta 4318 (e 4317, se usar gRPC) no firewall da máquina só para a rede dos serviços.
• O usuário de sistema evobits-sonda precisa poder ler os arquivos (por exemplo setfacl -R -m u:evobits-sonda:rX /var/log/minha-app; para os arquivos novos da rotação, também setfacl -d -m u:evobits-sonda:rX /var/log/minha-app).
• O formato nginx grava o IP do visitante em client.address; IP não está na máscara fixa. Crie uma regra extra por atributo se não quiser guardá-lo.

06Como instalar ou conectar

1. Libere as pastas de log na instalação da sonda (repita a opção sempre que reinstalar):

curl -fsSL https://app.evobits.com.br/downloads/sonda/instalar.sh | sudo sh -s -- --token evi_... --logs /var/log/minha-app,/opt/legado/logs

Em Docker, monte cada pasta como volume só de leitura, informe o caminho de dentro do contêiner e publique a porta do OTLP:

docker run -d --name evobits-sonda --cap-add NET_RAW \
  -p 4318:4318/tcp \
  -v /var/log/minha-app:/logs/minha-app:ro \
  -e SONDA_LOGS_PASTAS=/logs/minha-app \
  -e SONDA_URL=https://app.evobits.com.br -e SONDA_TOKEN_INSTALACAO=evi_... \
  -v evobits-sonda-dados:/var/lib/evobits-sonda \
  evobitstecnologia/sonda:estavel

Em Docker, o endereço para os serviços é o IP da máquina que roda o contêiner.

2. Ligue o OTLP em Sondas > a sonda > Receptores > OpenTelemetry (OTLP): HTTP na 4318; gRPC na 4317 só se algum serviço precisar.

3. Aponte o serviço para a sonda, com o token do serviço de sempre:

O resto do guia da linguagem vale como está.

4. Arquivos de log: em Receptores > Arquivos de log > Adicionar arquivo: caminho completo (com * só no nome), serviço e formato. Para texto com campos, cadastre antes as regras de extração na Configuração do serviço.

07Como conferir

1. 1O cartão OTLP mostra "Escutando" e, depois dos primeiros envios, a contagem de recebidos em 24 h e o serviço na lista "Serviços vistos por aqui".
2. 2Na tabela de arquivos, a coluna "Última" mostra uma linha recente e "Linhas/min" sobe. "Última" em amarelo: nenhuma linha há mais de 1 hora.
3. 3Em Aplicações > Logs, filtre pelo serviço: as linhas do arquivo aparecem com o nível certo.
4. 4Teste de queda: com a internet da sonda fora, "no buffer" cresce; na volta, cai a zero e os dados aparecem com a hora original.

08Problemas comuns

09Texto para IA

Para pedir a um assistente de código (Claude Code ou afins) que aponte o serviço para a sonda da sua rede. Troque os marcadores entre < >; o token fica só na variável EVOBITS_TOKEN.

# Tarefa: mandar logs e traces do serviço <nome do serviço> ao evobits pela sonda coletora da rede local

## Objetivo
Apontar este serviço, que roda numa rede sem saída para a internet, para a sonda do evobits em <ip-da-sonda>, que
recebe OpenTelemetry na rede local e repassa ao evobits.

## Contexto
- A sonda escuta OTLP por HTTP em http://<ip-da-sonda>:4318 (caminhos /v1/traces e /v1/logs, protobuf ou JSON) e,
  se ligado no painel, gRPC sem TLS em http://<ip-da-sonda>:4317.
- O token do serviço é obrigatório mesmo na rede local: `Authorization: Bearer <token>`, com o token SÓ na variável
  de ambiente EVOBITS_TOKEN.
- Node.js com o pacote `@evobits/node`: use `EVOBITS_ENDPOINT=http://<ip-da-sonda>:4318` (a versão 1.0.1 ou mais
  nova também lê OTEL_EXPORTER_OTLP_ENDPOINT e OTEL_EXPORTER_OTLP_HEADERS; a 1.0.0 não).
- Outras linguagens (SDK oficial do OpenTelemetry): `OTEL_EXPORTER_OTLP_ENDPOINT=http://<ip-da-sonda>:4318`,
  `OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf`, `OTEL_EXPORTER_OTLP_HEADERS=Authorization=Bearer%20${EVOBITS_TOKEN}`,
  `OTEL_SERVICE_NAME=<nome do serviço>`, `OTEL_METRICS_EXPORTER=none` e `OTEL_RESOURCE_ATTRIBUTES` com
  `service.version` e `service.instance.id`.
- Pedido vindo de navegador é recusado pela sonda; páginas web usam o endereço da internet.

## Passos
1. Descubra a linguagem e onde o serviço recebe variáveis de ambiente (systemd, compose, Kubernetes, .env fora do git).
2. Se o serviço ainda não tem OpenTelemetry, siga primeiro o guia da linguagem do evobits (Node.js ou OpenTelemetry
   oficial) e só troque o endereço.
3. Defina as variáveis do contexto, com o token sempre por referência a ${EVOBITS_TOKEN}.
4. Confirme que a máquina do serviço alcança <ip-da-sonda> na porta 4318 (por exemplo `curl -s -o /dev/null -w
   '%{http_code}' -X POST http://<ip-da-sonda>:4318/v1/logs` deve dar 401 sem token: a porta responde).

## Regras
- Nunca escreva o token em arquivo versionado, em log ou na resposta.
- Não mude nada além do endereço e das variáveis do pedido.
- Não abra a porta da sonda para a internet.

## Como saber que deu certo
1. O serviço sobe sem erro de exportação no log.
2. No painel do evobits, Sondas > a sonda > Receptores > OpenTelemetry (OTLP) mostra o serviço <nome do serviço> em
   "Serviços vistos por aqui", e as telas de Aplicações do serviço recebem os dados.