Tracing distribuído em resumo: spans, IDs de pai e W3C Trace Context

O que é

Um trace registra uma requisição enquanto ela percorre 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 contexto de span (ID do trace e ID do span), atributos, eventos, links e um status. Além disso, cada span tem um tipo (Client, Server, Internal, Producer ou Consumer), que informa 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 IDs atravessarem as fronteiras entre processos. Para isso, a recomendação W3C Trace Context define o cabeçalho HTTP traceparent: version-trace-id-parent-id-trace-flags, em que o ID do trace tem 32 caracteres hexadecimais minúsculos (16 bytes), o ID do pai tem 16 caracteres hexadecimais (o ID do span do chamador) e o byte de flags carrega atualmente um bit, sampled. Um segundo cabeçalho, tracestate, recebe dados específicos de cada fornecedor. A recomendação prevê dois níveis: uma ferramenta deve, no mínimo, repassar os dois cabeçalhos para que os traces não se interrompam, ou pode participar criando um span próprio e reescrevendo o ID do pai. A página do OpenTelemetry sobre Context Propagation descreve o mesmo mecanismo: o chamador transmite o ID do trace e o ID do span, e o serviço chamado cria um span filho que tem o span do chamador como pai.

Por que importa

Logs de dez serviços descrevem dez eventos separados; um trace mostra quais deles pertencem a uma mesma requisição, em que ordem ocorreram e onde o tempo foi gasto. Sem a propagação, cada serviço inicia o próprio span raiz, e o backend exibe fragmentos que não se conseguem ligar entre si.

Como aplicar

• Criar um span de servidor para cada requisição recebida e um span de cliente para cada chamada de saída, cada mensagem publicada e cada consulta ao banco de dados; as bibliotecas de instrumentação dos frameworks fazem isso automaticamente.
• Propagar o contexto por todos os caminhos, não só por HTTP: colocar o traceparent nos cabeçalhos das mensagens de filas e no payload dos jobs em segundo plano, e restaurá-lo no consumidor.
• Gravar o ID do trace em cada linha de log da requisição, para que logs e traces possam ser correlacionados.
• Escolher nomes de span com poucas variações (GET /users/{id}, e não o endereço concreto); colocar as partes variáveis em atributos.
• Serviços sem SDK de tracing repassam traceparent e tracestate sem alterações.

Armadilhas

Em fronteiras assíncronas (pools de threads, timers, escritores em lote), o contexto se perde se a biblioteca ou o código não o transportarem explicitamente. O flag sampled é uma indicação do chamador; uma decisão de amostragem independente em cada serviço gera traces com spans faltando. O desvio de relógio entre hosts pode fazer um span filho começar antes do seu pai. Uma borda pública deve decidir de forma consciente se continua um trace enviado por clientes arbitrários.