Traces na Observabilidade: o que são, span, trace_id e OpenTelemetry

Em arquiteturas monolíticas, debugar uma requisição lenta era relativamente simples: um único stack trace, um único banco de dados, logs centralizados em um servidor. Em arquiteturas de microsserviços, a mesma requisição pode atravessar 15, 20 ou 30 serviços diferentes antes de retornar uma resposta ao usuário. Quando algo dá errado nessa cadeia, descobrir onde sem as ferramentas certas pode levar horas.

Traces — ou rastreamento distribuído — são o pilar da observabilidade que resolve esse problema. Eles registram a jornada completa de uma requisição por todos os serviços que ela atravessa, tornando a cadeia de dependências visível e navegável.

Este guia técnico explica o que são traces, como a estrutura de span e trace_id funciona, como se integram com logs e métricas e como o padrão OpenTelemetry padroniza a instrumentação.

O que são traces (rastreamento distribuído)?

Um trace é a representação completa e cronológica da jornada de uma requisição por um sistema distribuído — do ponto de entrada até o retorno da resposta, incluindo todas as operações intermediárias em todos os serviços envolvidos.

Cada trace é composto por um conjunto de spans: unidades de trabalho que representam uma operação individual. Um span captura o nome da operação, o serviço que executou, os timestamps de início e fim, o status (sucesso ou falha), atributos de contexto e referência ao span pai.

A estrutura hierárquica de spans forma uma árvore que representa o fluxo da requisição. O span raiz é a requisição original; os spans filhos são as operações que ela disparou em outros serviços ou internamente.

trace_id e span_id: o DNA de uma requisição

O elemento que torna o rastreamento distribuído possível é o trace_id: um identificador único gerado quando a requisição entra no sistema e propagado para todos os serviços que ela atravessa — via headers HTTP, mensagens de fila ou protocolos de RPC.

Cada serviço lê o trace_id do contexto, cria seu próprio span com um span_id único e registra o span_id do serviço anterior como parent_span_id. Esse encadeamento permite reconstruir a árvore completa de spans.

O trace_id é também o elo de correlação com os outros pilares. Quando injetado nos logs gerados durante a requisição, permite filtrar exatamente os logs daquele trace. Quando presente nas métricas de erro, permite navegar do alerta para o trace específico que falhou.

Anatomia de um trace em produção

Um trace típico de uma requisição de e-commerce pode ter a seguinte estrutura:

api-gateway (100ms total)
├── auth-service.validateToken (8ms)
├── product-service.getProduct (45ms)
│ └── database.query (42ms) ← gargalo
├── inventory-service.checkStock (12ms)
└── recommendation-service (30ms)

Esse mapa torna imediatamente visível que 42 dos 100ms da requisição foram gastos em uma query de banco de dados dentro do product-service. Sem o trace, identificar esse gargalo exigiria examinar logs de 4 serviços diferentes e correlacionar timestamps manualmente.

Sampling: não rastrear tudo

Em sistemas de alto tráfego, rastrear 100% das requisições seria proibitivo em volume de dados e overhead de performance. A solução é o sampling: a decisão de quais requisições serão rastreadas.

As duas estratégias principais são: head-based sampling (decisão no início da requisição — simples mas pode perder traces de erros raros) e tail-based sampling (decisão ao final, após conhecer o resultado — permite priorizar traces de erros e requisições lentas, mas exige mais infraestrutura).

Em produção, a estratégia comum é rastrear 100% dos erros, 100% das requisições lentas e uma amostra configurável (1–10%) das demais.

OpenTelemetry e a padronização de traces

O OpenTelemetry é o padrão aberto que unificou a instrumentação de traces — anteriormente fragmentada entre OpenTracing, OpenCensus, Zipkin e Jaeger. Ele define uma API e SDK agnósticos ao backend: instrumentar com OpenTelemetry significa que os traces podem ser exportados para Jaeger, Grafana Tempo, Datadog ou qualquer outro backend compatível sem alterar o código.

A especificação inclui convenções semânticas que padronizam os atributos dos spans: http.method, http.status_code, db.system, db.statement, entre outros. Essa padronização garante que traces de diferentes serviços e linguagens sejam navegáveis em uma única plataforma de observabilidade.

A documentação de referência é a especificação de Distributed Traces do OpenTelemetry, que cobre em detalhe a estrutura de spans, propagação de contexto e semântica de atributos.

Conclusão

Traces são o pilar de navegação da observabilidade: tornam visível o que antes era invisível — o caminho exato de uma requisição por um sistema distribuído e o tempo gasto em cada hop. Sem traces, diagnosticar gargalos de performance em arquiteturas de microsserviços é uma investigação manual e demorada.

A implementação eficaz começa pela instrumentação padronizada com OpenTelemetry, inclui uma estratégia de sampling que prioriza erros e requisições lentas e matura com a correlação automática com logs e métricas pelo trace_id. Para estruturar sua estratégia de rastreamento distribuído e observabilidade, fale com nossos especialistas.