Rastreamento distribuído em resumo: spans, IDs de pai e propagação do W3C Trace Context

O que é

Um trace registra uma requisição à medida que ela passa por vários serviços. Ele é uma árvore de spans. A documentação do OpenTelemetry lista o que um span contém: um nome, o ID do span pai (vazio no span raiz), timestamps de início e de fim, um span context (trace ID e span ID), atributos, eventos, links e um status. Cada span também tem um tipo (Client, Server, Internal, Producer ou Consumer), que indica ao backend como montar a árvore: o pai de um span de servidor costuma ser um span de cliente remoto.

A árvore só se forma se os identificadores atravessarem as fronteiras entre processos. A recomendação W3C Trace Context define para isso o cabeçalho HTTP traceparent: version-trace-id-parent-id-trace-flags, em que o trace ID tem 32 caracteres hexadecimais minúsculos (16 bytes), o parent ID tem 16 caracteres hexadecimais (o ID do span que faz a chamada) e o byte de flags carrega atualmente um único bit, sampled. Um segundo cabeçalho, tracestate, guarda dados específicos de cada fornecedor. A recomendação define dois níveis: uma ferramenta deve, no mínimo, propagar os dois cabeçalhos para que os traces não se quebrem (repasse), ou pode participar ativamente, criando o próprio span e reescrevendo o parent ID. A página de propagação de contexto do OpenTelemetry descreve o mesmo mecanismo: quem chama envia o trace ID e o span ID, e quem é chamado cria um span filho que tem o span do chamador como pai.

Por que importa

Logs de dez serviços descrevem dez eventos isolados; um trace mostra quais deles pertencem à mesma requisição, em que ordem ocorreram e onde o tempo foi gasto. Sem propagação, cada serviço inicia o seu próprio span raiz, e o backend exibe fragmentos que não podem ser ligados entre si.

Como aplicar

• Crie um span de servidor para cada requisição recebida e um span de cliente para cada chamada de saída, publicação de mensagem ou consulta ao banco de dados; as bibliotecas de instrumentação de frameworks fazem isso automaticamente.
• Propague o contexto por todos os canais, não só por HTTP: coloque o traceparent nos cabeçalhos das mensagens de filas e no payload dos jobs em segundo plano, e restaure-o no consumidor.
• Grave o trace ID em cada linha de log da requisição, para que logs e traces possam ser relacionados.
• Mantenha os nomes dos spans com baixa cardinalidade (GET /users/{id}, e não a URL concreta); coloque as partes variáveis em atributos.
• Serviços que não executam um SDK de tracing devem, mesmo assim, repassar traceparent e tracestate sem alterações.

Armadilhas

O contexto se perde em fronteiras assíncronas (thread pools, timers, escritores em lote), a menos que a biblioteca ou o código o transporte de forma explícita. O flag sampled é uma indicação de quem chama; se cada serviço tomar a sua própria decisão de amostragem, os traces ficam com spans faltando. O desvio de relógio (clock skew) entre hosts pode fazer um span filho parecer começar antes do seu pai. Uma borda pública deve decidir de forma deliberada se continua um trace enviado por um cliente qualquer.