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.