Tracing distribuído em microsserviços: guia passo a passo

Tracing distribuído é a forma de acompanhar uma requisição inteira enquanto ela atravessa vários microsserviços. Sem ele, um erro que começa no serviço A pode aparecer como timeout no serviço D, e você fica sem saber onde investigar. Neste guia, vamos mostrar o caminho para implementar tracing distribuído em microsserviços, do contexto inicial à coleta dos dados, com atenção aos detalhes que costumam quebrar a rastreabilidade.

Este guia assume que você já tem seus microsserviços rodando e um backend de observabilidade (como Jaeger, Zipkin ou Grafana Tempo) disponível. Se ainda não tem, comece por aí, porque o tracing depende de um destino para receber os spans.

Passo 1: Defina o contexto de trace

O primeiro passo é estabelecer o que será rastreado. Cada requisição que entra no seu sistema deve receber um trace_id único. Esse ID é a âncora que conecta todos os spans da mesma operação. Além dele, cada serviço dentro do trace recebe um span_id, que identifica uma unidade de trabalho específica, como uma chamada HTTP ou uma consulta ao banco.

Um erro comum aqui é gerar um novo trace a cada salto entre serviços. Se cada microsserviço cria um trace_id próprio, você perde a visão da jornada completa. O trace_id precisa ser criado uma única vez, na borda do sistema, e propagado adiante.

Dica: use o padrão W3C Trace Context para os headers traceparent e tracestate. Ele é aceito pela maioria das ferramentas e evita retrabalho se você trocar de backend depois.

Passo 2: Propague o contexto entre serviços

O contexto de trace não se propaga sozinho. Quando o serviço A chama o serviço B via HTTP, o header traceparent precisa ser enviado na requisição. Sem essa propagação, o serviço B inicia um trace novo e o rastreamento se perde.

A propagação manual é trabalhosa e propensa a erro, principalmente quando você esquece de incluir o header em uma chamada ou o injeta em um endpoint que não deveria. Por isso, o ideal é usar uma biblioteca de instrumentação que faça isso automaticamente.

O OpenTelemetry, por exemplo, oferece SDKs que interceptam as chamadas HTTP e injetam o contexto sem que você precise tocar no código de cada serviço. Isso reduz a chance de falha silenciosa, onde o tracing existe, mas não conecta os pontos.

Erro comum: propagar o contexto apenas nas chamadas síncronas. Se você usa filas (como Kafka ou RabbitMQ), o contexto precisa ser serializado na mensagem e restaurado no consumidor. Caso contrário, o trace termina no produtor e o consumidor começa um novo.

Passo 3: Colete spans em cada serviço

Com o contexto propagado, cada serviço precisa registrar seus spans. Um span representa uma operação específica, com início, fim, status e atributos. Quanto mais rico o span, mais fácil entender o gargalo. Inclua informações como URL, método HTTP, status da resposta e qualquer dado de negócio relevante.

Não exagere na quantidade de spans. Um span por chamada HTTP ou operação de banco já é suficiente na maioria dos casos. Spans em excesso aumentam o volume de dados e o custo de armazenamento, sem trazer valor proporcional.

Dica: defina um nível de amostragem. Você não precisa rastrear 100% das requisições. Em sistemas de alto tráfego, uma amostragem de 10% a 20% já dá uma visão representativa do comportamento, com custo bem menor.

Passo 4: Envie os spans para o backend

Depois de coletados, os spans precisam ser enviados a um backend de observabilidade. O OpenTelemetry Collector é uma opção comum: ele recebe os spans dos serviços, processa e encaminha para o Jaeger, Zipkin, Tempo ou qualquer outro sistema compatível.

Um cuidado aqui é a latência. O envio dos spans não deve bloquear a requisição principal. Use exportação assíncrona, que envia os dados em segundo plano, e monitore a fila de exportação para evitar perda de spans em picos de tráfego.

Erro comum: configurar o endpoint do backend errado ou esquecer de definir o timeout. Isso gera spans descartados silenciosamente e você só percebe quando precisa investigar um incidente e não encontra os dados.

Passo 5: Valide o trace completo

Com tudo configurado, faça um teste de ponta a ponta. Dispare uma requisição que passe por pelo menos três serviços e verifique no backend se o trace completo aparece, com todos os spans conectados pelo mesmo trace_id.

Se algum span estiver faltando, revise a propagação naquele serviço específico. Se o trace aparece dividido em dois, o problema está na geração do trace_id ou na serialização em filas.

Dica: crie um teste automatizado que valide a presença do header traceparent nas chamadas entre serviços. Isso evita regressões quando alguém altera uma chamada HTTP no futuro.

Checklist final

• Contexto de trace definido na borda do sistema, com trace_id único.
• Propagação via header traceparent em todas as chamadas HTTP.
• Contexto serializado em mensagens de fila, se aplicável.
• Spans coletados em cada serviço, com atributos relevantes.
• Exportação assíncrona configurada para o backend.
• Teste de ponta a ponta validando o trace completo.

FAQ

Qual a diferença entre tracing distribuído e logs?

Logs registram eventos isolados em um serviço. Tracing distribuído conecta esses eventos em uma única requisição, mostrando o fluxo completo entre serviços. Eles são complementares: logs ajudam no detalhe, tracing ajuda na visão geral.

Preciso de uma ferramenta específica para implementar tracing?

Você precisa de um backend para armazenar e visualizar os traces, como Jaeger ou Zipkin, e de uma biblioteca de instrumentação, como o OpenTelemetry. A combinação é flexível, e o OpenTelemetry se tornou o padrão de mercado por ser open source e agnóstico de backend.

O que é um span no tracing distribuído?

Um span é uma unidade de trabalho dentro de um trace. Ele representa uma operação específica, como uma chamada HTTP ou uma consulta ao banco, com duração, status e atributos. Vários spans conectados formam um trace completo.

Como o tracing distribuído funciona com mensageria?

Em filas, o contexto de trace precisa ser serializado na mensagem, no header ou no payload, e restaurado no consumidor. Sem isso, o trace termina no produtor e o consumidor começa um novo, quebrando a visão da jornada completa.

Tracing distribuído tem custo alto?

O custo depende do volume de spans e do backend escolhido. Amostragem reduz significativamente o custo, e ferramentas open source como Jaeger eliminam custo de licença, mas exigem infraestrutura própria para armazenamento.

É possível implementar tracing sem OpenTelemetry?

Sim, você pode criar sua própria propagação e coleta, mas isso exige muito trabalho e manutenção. O OpenTelemetry já resolve a instrumentação e a padronização, então é mais seguro adotá-lo do que construir uma solução proprietária.