OpenTelemetry rastreia uma request do frontend ao banco e mostra onde quebrou. Sem instrumentação distribuída, debugar um fluxo que atravessa cinco serviços exige leitura manual de logs em cada sistema. A especificação do OpenTelemetry (projeto da CNCF) define três pilares: traces, metrics e logs.
Os três pilares
Traces: o caminho completo de uma request. Cada serviço adiciona um span. O trace mostra onde o tempo foi gasto e onde o erro aconteceu.
Metrics: números agregados. Requests por segundo, latência p99, taxa de error. Métricas indicam que algo está errado.
Logs: eventos estruturados. Logs indicam o que aconteceu. Traces indicam onde. Metrics indicam quanto.
Instrumentação automática
OTel oferece instrumentação automática para frameworks populares. Em Node.js, o pacote @opentelemetry/auto-instrumentations-node instrumenta Express, PostgreSQL, Redis, Kafka sem mudar código. A documentação do OpenTelemetry lista pacotes de auto-instrumentação para Java, Python, Go, .NET e outras linguagens.
Instrumentação manual
Para código manual, você adiciona spans explicitamente. Um span é uma operação com nome, timestamp e atributos. Ex: span "process-payment" com atributos "payment-method", "amount", "currency".
O que instrumentar
Fronteiras de serviço: toda chamada HTTP, gRPC ou de fila entra e sai de span. Sem esse rastreamento, você não sabe qual serviço causou o problema.
Operações de banco: queries lentas são a causa número um de problemas de performance. Instrumente queries com nome, tabela e duração.
Operações de negócio: checkout, pagamento, onboarding. Essas operações têm impacto direto no negócio. Instrumente-as com atributos de negócio.
Erros comuns
Instrumentação excessiva: operações triviais, cache hits e health checks não precisam de span. Instrumente o que importa para debugging.
Contexto não propagado: se o trace ID não propaga entre serviços, você tem traces quebrados. Garanta que o cabeçalho traceparent é propagado em todas as chamadas.
Custo ignorado: tracing tem custo. Amostragem (sampling) reduz o custo. Amostre 100% dos erros, 10% dos successes. Você não precisa de todos os traces para debugging.
Limitações
OTel não resolve falta de logs, falta de métricas ou falta de instrumentação manual em código legado. A ferramenta padroniza coleta e exportação, mas a qualidade da instrumentação depende do time.
Curtiu o conteúdo?
Construo produtos web e soluções com IA do jeito certo — arquitetura sólida, código sustentável e entrega real.
Vamos conversar