OpenTelemetry observabilidade: guia de configuração

Configurar OpenTelemetry para observabilidade exige decidir o que instrumentar, subir um coletor e exportar dados para um backend. O resultado esperado é enxergar uma requisição atravessando seus serviços sem precisar caçar log em três máquinas. Antes de começar, tenha a aplicação rodando localmente, Docker disponível e um backend de destino (Jaeger, Prometheus ou outro).

Passo 1: instrumente a aplicação com o SDK

Adicione o SDK do OpenTelemetry ao serviço e ative a instrumentação automática da sua stack (HTTP, banco, filas). Em Node, por exemplo, é o pacote @opentelemetry/sdk-node com os instrumentations correspondentes. Erro comum: inicializar o SDK depois de importar o framework web. A instrumentação precisa rodar antes, senão os spans não são criados e você jura que o código está quebrado.

Passo 2: suba o OpenTelemetry Collector

O Collector recebe, processa e exporta a telemetria. Rode-o via Docker com um config.yaml apontando receiver OTLP e exporter para o seu backend. Dica: comece com o exporter debug para ver os dados chegando no terminal antes de configurar o destino final. Isso evita debugar dois problemas ao mesmo tempo quando nada aparece no Jaeger.

Passo 3: conecte e valide ponta a ponta

Aponte o SDK para o endpoint do Collector (OTEL_EXPORTER_OTLP_ENDPOINT) e gere tráfego real. Abra o backend e confirme se o trace tem os spans esperados e o trace_id bate entre serviços. Se faltar span, geralmente é propagação de contexto ausente entre chamadas HTTP.

Checklist rápido

• SDK inicializado antes do framework
• Collector rodando com receiver OTLP
• Exporter configurado para o backend
• Trace validado com trace_id consistente
• Amostragem definida (não deixe 100% em produção)

FAQ

Preciso instrumentar tudo de uma vez?

Não. Comece por um serviço crítico e valide o fluxo completo. Expandir depois é mais seguro do que instrumentar dez serviços e não saber onde está o erro.

OpenTelemetry substitui Prometheus ou Jaeger?

Nenhum dos dois. O OpenTelemetry padroniza a coleta e o formato dos dados; Prometheus e Jaeger seguem sendo backends que armazenam e consultam a telemetria.

Qual a diferença entre SDK e Collector?

O SDK roda dentro da aplicação e gera os dados. O Collector é um processo separado que recebe, processa e exporta essa telemetria para um ou mais destinos.

Dá para usar só métricas sem traces?

Dá, mas você perde a correlação entre uma métrica anômala e a requisição que a causou. Para investigar incidente, trace e métrica juntos economizam tempo.

Como controlar o volume de dados em produção?

Configure amostragem no SDK ou no Collector. Sem isso, o custo de armazenamento cresce rápido e o backend fica lento para consultar.

OpenTelemetry funciona com aplicações legadas?

Funciona via instrumentação manual ou agentes que interceptam chamadas. O esforço depende da stack; linguagens sem suporte automático exigem mais código.

Para quem está começando: vale se o time já sente dor para correlacionar falhas entre serviços. Para quem tem um monólito simples e logs suficientes, o ganho é menor e o custo operacional do Collector pode não se pagar.