# OpenTelemetry observabilidade: guia de configuração

> OpenTelemetry é um framework de observabilidade que unifica a coleta de traces, métricas e logs por meio de instrumentação e de um coletor central. A configuração típica envolve instrumentar a aplicação, executar o OpenTelemetry Collector e exportar os dados para um backend de análise.

*Digitorack · Apps e Software · 16 de setembro de 2026 · Letícia Sampaio Khoury*

Configurar OpenTelemetry para observabilidade exige decidir o que instrumentar, subir um coletor e exportar dados para um backend. Neste guia mostro o caminho que uso em projetos reais, com os erros que aparecem no meio.

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.

---

Fonte (canonical): https://digitorack.com.br/apps-e-software/opentelemetry-observabilidade-guia-de-configuracao/