OpenTelemetry Collector: organizando o fluxo da telemetria
Publicado em 12 de outubro de 2026
Parte 3 de 8 — série Observabilidade na prática.
A API de catálogo já emite métricas. Agora queremos receber seus traces e alguns eventos de diagnóstico, controlando o que sai da aplicação. No cenário hipotético da série, configurar um destino diferente dentro de cada produtor começaria a espalhar regras de transporte e privacidade. Um ponto comum de processamento ajuda a administrar essas decisões.
O OpenTelemetry Collector recebe telemetria, aplica processamento e a encaminha. A instrumentação continua sendo responsabilidade das fontes; armazenamento e consulta ficam nos backends. Sua utilidade está em tornar explícito o caminho entre esses dois lados.
Os sinais e o protocolo OTLP
Nesta série, trabalhamos com métricas, logs e traces, sinais suportados pelo ecossistema OpenTelemetry. Uma aplicação instrumentada pode enviá-los usando o OpenTelemetry Protocol (OTLP). Outras fontes entram por receivers específicos. OpenTelemetry também trata outros sinais e mecanismos, que ficam fora deste recorte.
Essa padronização reduz a dependência entre uma aplicação e um backend. Em teoria, a instrumentação pode continuar útil se o destino mudar; na prática, semântica, atributos e capacidades ainda precisam ser compatíveis. OTLP define transporte e representação de dados, não uma garantia de que qualquer backend aceitará cada campo da mesma forma.
Receivers, processors e exporters
Uma configuração do Collector reúne componentes em pipelines:
- Receivers recebem dados, por exemplo, por OTLP ou de uma fonte de métricas.
- Processors podem agrupar, enriquecer, filtrar ou transformar dados antes de exportá-los.
- Exporters enviam os dados a um backend ou expõem uma saída consumível por outro sistema.
Uma pipeline define quais desses componentes participam e em qual ordem os dados passam por eles. Definir um receiver no arquivo não significa necessariamente que ele esteja ativo: ele precisa fazer parte da pipeline. Esse detalhe explica vários erros de configuração que parecem misteriosos à primeira vista.
Uma configuração segura começa com o caminho mínimo necessário. Para cada sinal, documente a fonte, os atributos aceitos, as transformações e o destino. Evite ativar componentes genéricos sem saber que dados receberão ou qual endereço vão abrir. As opções disponíveis e seu estado de maturidade variam entre receivers e versões; valide o arquivo com o binário correspondente à implantação.
Agente ou gateway?
Um agente roda perto da fonte e pode ler informações locais, como métricas do host ou logs acessíveis pelo usuário do processo. Um gateway recebe dados de diferentes produtores e centraliza roteamento, processamento ou controle de acesso. Os papéis podem existir em uma única instalação pequena ou ser separados quando escala e fronteiras de confiança pedirem.
Em um laboratório pequeno, começar com uma instância enxuta pode ser adequado. Separar um Collector por serviço, sem necessidade concreta, multiplica versões, configuração e diagnóstico. Um gateway único, porém, também se torna uma dependência compartilhada. Se todos os produtores dependem dele, monitore sua saúde e limite o impacto de uma falha.
Escolha o desenho considerando rede, disponibilidade e acesso. O protocolo de ingestão não deve ficar exposto por conveniência: determine quem pode enviar telemetria e por qual interface, rede ou identidade. Em ambientes que cruzam redes não confiáveis, use autenticação e criptografia conforme o cenário.
Filtrar antes de persistir
O Collector pode remover atributos que não precisam chegar ao backend, limitar nomes de métricas aceitos ou reduzir campos de logs. Essa transformação ajuda a minimizar dados antes de seu envio ao destino. O conteúdo já chegou ao Collector: quando um dado nem deveria sair da aplicação, a remoção precisa acontecer na instrumentação, antes do envio.
Filtros precisam ser testados com dados representativos. Uma regra permissiva pode deixar escapar conteúdo. Uma regra rígida demais pode descartar o único campo que explicaria uma falha. Quando a privacidade depende de uma transformação, confira como o processor trata erros: algumas opções permitem continuar encaminhando o registro. Escolha e teste uma política que descarte ou bloqueie dados não sanitizados. Validação de sintaxe não comprova esse comportamento.
Aplique a sanitização antes de exporters e de suas filas persistentes. Um exporter de debug ou um caminho paralelo também pode copiar o conteúdo original; revisar só o destino final deixa essas saídas fora da análise.
Também evite ampliar a cardinalidade por meio de atributos. IDs de usuário, endereços completos e mensagens não devem virar labels de métricas. Um atributo com alta variabilidade pode aumentar o custo de todo o pipeline, mesmo quando o produtor gera poucos dados.
Validar o Collector como serviço
Primeiro, valide a configuração sintaticamente com a mesma distribuição do Collector que será usada. Em seguida, confirme que os endpoints esperados estão acessíveis, que os alvos aparecem no destino e que um exemplo controlado atravessa a pipeline correta. Observe filas, erros de exportação e uso de memória do Collector.
Verifique também os endpoints que ele abre. Um receiver OTLP ligado a todas as interfaces pode ser acessível além da rede de containers pretendida. Um endpoint de métricas internas pode revelar detalhes do serviço. O endereço de bind, firewall e rede efetiva fazem parte da configuração de telemetria.
O Collector deve monitorar seu próprio estado. Se houver várias pipelines, acompanhe falhas de envio, dados descartados e atrasos. A ausência de métricas no backend pode ser causada pelo produtor, receiver, processor, fila, rede, exporter ou destino. Desenhar os limites torna essa investigação mais objetiva. No catálogo, podemos conferir separadamente se a aplicação emitiu um sinal, se o Collector o aceitou e se o backend o recebeu. Essa sequência diferencia falha de transporte de falta de instrumentação.
Na série: anterior — Grafana e Prometheus: da coleta à interpretação; próxima — Host e containers: recursos não contam toda a história.