Como implementar OpenTelemetry no Kubernetes: do Collector ao Operator

Rodar aplicações em Kubernetes multiplica os dados que a operação precisa coletar: métricas de pods, logs de containers, eventos do cluster e traces distribuídos. Sem um padrão único de coleta, cada equipe instala um agente diferente. Como resultado, os custos crescem e a visibilidade fica fragmentada.

O OpenTelemetry surgiu para resolver esse problema com um padrão aberto de instrumentação e exportação de telemetria. No Kubernetes, o projeto oferece recursos dedicados: um Operator próprio, coleta nativa de métricas da infraestrutura e auto-instrumentação de aplicações sem mudança de código.

Neste guia, você vai entender os padrões de arquitetura do Collector no cluster, o papel do OpenTelemetry Operator e as boas práticas que sustentam essa stack em produção.

O que é o OpenTelemetry no Kubernetes

O OpenTelemetry no Kubernetes é a aplicação do padrão aberto de telemetria da CNCF em clusters de containers. O OTel Collector roda dentro do cluster e coleta métricas, logs e traces das aplicações e da infraestrutura. Depois, exporta tudo via OTLP para qualquer backend, sem prender a operação a um fornecedor.

Na prática, isso significa instrumentar uma vez e trocar de ferramenta quando fizer sentido. O mesmo pipeline que envia dados para o Jaeger hoje pode apontar para outro backend amanhã. Para entender a arquitetura do padrão em profundidade, veja o guia de OpenTelemetry.

A diferença no Kubernetes está no contexto. O cluster produz sinais próprios: estado de pods, eventos de scheduling, consumo por nó. Além disso, os workloads sobem e descem o tempo todo. Por isso, a coleta precisa acompanhar essa dinâmica e enriquecer cada dado com metadados como namespace, pod e deployment.

Vale lembrar o papel de cada sinal nesse quadro. Métricas mostram o quê, traces mostram onde, logs explicam o detalhe. Dentro do cluster, os três ganham a mesma camada extra de contexto de orquestração: qual pod, qual nó, qual versão do deployment estava no ar.

Por que padronizar a telemetria do cluster com OpenTelemetry

Kubernetes deixou de ser exceção e virou regra nos ambientes corporativos. Os números da própria fundação que abriga os dois projetos confirmam esse movimento.

A pesquisa anual da CNCF mostra que 82% dos usuários de containers já rodam a plataforma em produção.

O mesmo levantamento aponta o OpenTelemetry como o segundo projeto de maior velocity da fundação, com mais de 24.000 contribuidores ativos.

Padronizar importa porque ambientes de containers misturam linguagens, times e ferramentas. Sem um formato comum, cada aplicação exporta dados de um jeito diferente. Consequentemente, correlacionar um pico de latência com um evento do cluster vira trabalho manual e demorado.

Vale destacar que o OpenTelemetry não substitui seu sistema de métricas: ele padroniza a coleta e o transporte. O Prometheus, por exemplo, segue como backend comum nesse cenário. O comparativo entre OpenTelemetry e Prometheus detalha onde cada um atua.

A padronização também fortalece o monitoramento de Kubernetes tradicional. Health checks e alertas continuam essenciais. A telemetria unificada adiciona a camada de diagnóstico: o porquê por trás de cada alerta disparado.

Existe ainda o efeito sobre o time. Profissionais que chegam à equipe já conhecem o padrão aberto, enquanto treinar gente em um pipeline proprietário custa caro e amarra a operação. Com o padrão da comunidade, o conhecimento acompanha o mercado, não a ferramenta.

Padrões de deployment do Collector: DaemonSet, Deployment e sidecar

Toda arquitetura de OpenTelemetry em cluster passa por uma decisão central: onde rodar o OTel Collector. Existem três padrões principais de deployment, cada um com escopo e custo diferentes. Em muitos ambientes, a resposta certa combina dois deles.

DaemonSet: um agente em cada nó

No padrão DaemonSet, o Kubernetes agenda um pod do Collector em cada nó do cluster. Esse agente local coleta métricas do kubelet, lê os logs dos containers do próprio nó e recebe traces das aplicações vizinhas. Dessa forma, a coleta escala automaticamente junto com o cluster.

O DaemonSet é o ponto de partida recomendado para coleta de infraestrutura. Ele fica perto da origem dos dados, reduz o tráfego entre nós e carimba cada sinal com os metadados locais antes do envio.

Deployment: o gateway central

No padrão Deployment, o Collector roda como serviço com réplicas e funciona como gateway. Ele recebe a telemetria dos agentes, aplica o processamento pesado e concentra a saída para o backend. Além disso, é nele que ficam as coletas de escopo único, como métricas de estado do cluster.

Centralizar a saída simplifica a governança. Políticas de sampling, filtros e credenciais do backend ficam em um único ponto, em vez de espalhadas por todos os nós do ambiente.

Sidecar: um Collector por pod

No padrão sidecar, cada pod da aplicação carrega seu próprio Collector injetado como container adicional. O isolamento é máximo, porém o custo acompanha: cada réplica consome recursos extras. Por isso, o sidecar costuma ficar restrito a workloads com requisitos fortes de segregação.

Existe ainda o modo StatefulSet, útil quando o Collector precisa de identidade estável entre restarts, como no scraping particionado de métricas. A tabela abaixo resume os critérios de escolha entre os três padrões principais:

Na arquitetura mais comum em produção, DaemonSet e Deployment trabalham juntos. Os agentes por nó coletam e encaminham, enquanto o gateway processa, aplica sampling e exporta. A comunidade chama esse desenho de agent-to-gateway.

Um erro frequente é começar pelo desenho mais complexo. Comece simples: um DaemonSet coletando infraestrutura já responde boa parte das perguntas do dia a dia. O gateway entra depois, quando o volume de dados ou a governança pedirem.

OpenTelemetry Operator: o que ele automatiza

O OpenTelemetry Operator é o componente que gerencia Collectors e auto-instrumentação dentro do cluster com dois recursos customizados: OpenTelemetryCollector e Instrumentation. Ele cria e atualiza Collectors, injeta sidecars e ativa a instrumentação automática via annotations. Tudo sem mudança no código nem nos manifests originais.

A instalação exige o cert-manager, responsável pelos certificados dos webhooks. Depois disso, dois comandos colocam o Operator no ar:

# instala o cert-manager (pré-requisito dos webhooks)
kubectl apply -f https://github.com/cert-manager/cert-manager/releases/latest/download/cert-manager.yaml

# instala o OpenTelemetry Operator
kubectl apply -f https://github.com/open-telemetry/opentelemetry-operator/releases/latest/download/opentelemetry-operator.yaml

Com o Operator ativo, um manifesto OpenTelemetryCollector de poucas linhas cria um Collector completo. O campo mode define o padrão de deployment: daemonset, deployment, sidecar ou statefulset. Upgrades de versão passam a ser responsabilidade do Operator.

O componente também resolve um problema clássico de quem faz scraping de métricas em escala. O Target Allocator distribui os alvos entre réplicas do Collector em modo statefulset. Dessa forma, a coleta particiona automaticamente, sem intervenção manual a cada mudança no cluster.

Os detalhes de cada recurso customizado, bem como o Helm chart de instalação, estão no repositório oficial do projeto.

Auto-instrumentação de aplicações via annotations

A auto-instrumentação é o recurso mais valioso do Operator para times de plataforma. Ela injeta as bibliotecas do OpenTelemetry na aplicação em tempo de deploy, por meio de um init container. Assim, serviços em Java, Python, .NET e Node.js passam a emitir traces e métricas sem alteração de código.

O primeiro passo é criar o recurso Instrumentation, que define o destino dos dados e como o contexto se propaga:

apiVersion: opentelemetry.io/v1alpha1
kind: Instrumentation
metadata:
  name: auto-instrumentacao
spec:
  exporter:
    endpoint: http://otel-collector.observabilidade:4317
  propagators:
    - tracecontext
    - baggage

Em seguida, basta anotar o workload com instrumentation.opentelemetry.io/inject-java: "true" para ativar a injeção. O webhook do Operator intercepta o deploy, adiciona o init container e configura as variáveis de ambiente OTEL_* no pod. Go é a exceção relevante: a instrumentação automática da linguagem ainda depende de abordagens experimentais.

Cada linguagem tem sua annotation correspondente: inject-python, inject-dotnet e inject-nodejs seguem o mesmo padrão da versão Java. O recurso aceita ainda a anotação aplicada ao namespace inteiro, o que ativa a instrumentação de todos os workloads daquele espaço de uma só vez.

Quando usar cada abordagem? A automática resolve rápido a visibilidade básica: chamadas HTTP, bancos de dados e filas aparecem nos traces sem esforço. Já a manual entra quando o time precisa de spans de negócio, atributos customizados ou controle fino da amostragem.

Cabe ressaltar que a auto-instrumentação complementa a instrumentação de aplicações manual, sem eliminá-la. Spans de negócio continuam exigindo código. Além disso, microsserviços dependem de propagação de contexto correta para costurar as requisições de ponta a ponta.

O que coletar do cluster: métricas, logs e eventos

Em um cluster Kubernetes, o OpenTelemetry coleta quatro grupos de dados. As métricas de nós e pods chegam pelo kubeletstats. O estado dos objetos vem do k8s_cluster e os logs passam pelo filelog. Por fim, o k8sobjects captura eventos como restarts e falhas de scheduling.

O processor k8sattributes completa o quadro. Ele enriquece cada métrica, log ou trace com namespace, nome do pod e deployment de origem. Sem esse carimbo, correlacionar sinais entre si vira adivinhação. Um exemplo de configuração do agente por nó:

receivers:
  kubeletstats:
    collection_interval: 30s
  filelog:
    include:
      - /var/log/pods/*/*/*.log

processors:
  k8sattributes: {}
  batch: {}

exporters:
  otlp:
    endpoint: gateway-collector:4317

service:
  pipelines:
    metrics:
      receivers: [kubeletstats]
      processors: [k8sattributes, batch]
      exporters: [otlp]
    logs:
      receivers: [filelog]
      processors: [k8sattributes, batch]
      exporters: [otlp]

Os traces das aplicações entram no mesmo pipeline via OTLP e habilitam o rastreamento distribuído entre os serviços do cluster. A lista completa de receivers e processors disponíveis está na documentação oficial.

Eventos do Kubernetes merecem atenção especial. Um CrashLoopBackOff ou um OOMKilled registrado junto aos traces daquele período reduz drasticamente o tempo de diagnóstico durante um incidente.

Logs pedem uma decisão consciente. O filelog lê a saída dos containers direto do nó, sem sidecars de logging. Para quem já opera outra stack de logs consolidada, vale manter a coleta atual e começar pelo par métricas e traces. A migração pode ser gradual.

Passo a passo: implantação incremental no cluster

Com os conceitos no lugar, a implantação funciona melhor em fases. Cada etapa entrega valor próprio e prepara a seguinte. O roteiro abaixo resume a sequência que costuma funcionar em ambientes corporativos.

Fases 1 e 2: fundação da coleta

A primeira fase instala o Operator com o cert-manager e aplica um manifesto OpenTelemetryCollector em modo daemonset. Nesse momento, o cluster já entrega métricas de infraestrutura e logs de containers. Valide os dados no backend antes de avançar.

Na segunda fase, entra o gateway em modo deployment. Direcione os agentes para ele via OTLP e mova os receivers de escopo único, como o k8s_cluster, para essa camada. Assim, cada dado do cluster passa a ter um único dono.

Fases 3 e 4: aplicações e otimização

A terceira fase ativa a auto-instrumentação nos serviços mais críticos, um namespace por vez. Priorize as aplicações com maior impacto no negócio. Em paralelo, confirme se os traces cruzam corretamente as fronteiras entre os serviços.

Por fim, a quarta fase otimiza o pipeline: políticas de sampling no gateway, filtros de atributos e alertas sobre as métricas internas do Collector. A partir daí, o crescimento do cluster deixa de significar crescimento linear da conta de observabilidade.

Boas práticas de produção: recursos, sampling e custo

Levar essa stack para produção exige disciplina em três frentes: consumo de recursos, volume de dados e observabilidade do próprio pipeline de telemetria.

Proteja o Collector e o cluster

Defina requests e limits para cada Collector, como faria com qualquer workload crítico. Ative o processor memory_limiter para descartar dados antes de um estouro de memória. Além disso, mantenha o processor batch em todos os pipelines para agrupar envios e reduzir a pressão na rede.

Evite coletas duplicadas. Se o DaemonSet já roda o kubeletstats, o gateway não deve repetir o receiver. Dados duplicados inflam custos e distorcem dashboards. Da mesma forma, restrinja o RBAC do Collector ao mínimo: leitura dos objetos que ele realmente monitora.

Controle o volume antes de pagar por ele

Telemetria tem custo por gigabyte em praticamente todos os backends. Por isso, aplique sampling de telemetria no gateway, filtre namespaces irrelevantes e descarte atributos sem valor analítico. O tail sampling centralizado permite manter os traces com erro e amostrar os demais.

Monitore o próprio Collector. Ele expõe métricas internas de filas, descartes e consumo. Um pipeline de telemetria que falha em silêncio é o pior cenário possível: a visibilidade some justamente durante o incidente.

Por fim, avalie o modelo operacional. Manter Collectors, versões e políticas de coleta exige tempo de engenharia dedicado. Equipes enxutas costumam apoiar essa jornada em um serviço de observabilidade gerenciado, que assume a operação do pipeline de ponta a ponta.

Conclusão

O OpenTelemetry transformou a coleta de telemetria em Kubernetes em um problema com padrões claros: DaemonSet para coleta local, gateway para processamento central e Operator para automatizar o ciclo de vida. Com a auto-instrumentação via annotations, até aplicações legadas passam a emitir traces sem mudança de código.

O caminho recomendado é incremental. Comece com um DaemonSet coletando métricas e logs da infraestrutura. Em seguida, adicione o gateway com sampling e tail sampling centralizados. Por último, ative a auto-instrumentação nos serviços mais críticos. Dessa forma, o volume de dados cresce sob controle e a equipe amadurece junto com a stack.

Se a sua operação precisa de visibilidade completa do cluster sem assumir toda a complexidade do pipeline, a OpServices pode ajudar. Nossa equipe implementa e opera stacks de observabilidade com OpenTelemetry em ambientes críticos, do desenho da arquitetura à operação contínua. Fale com um especialista e acelere essa jornada.