Trace ID, Span e propagação

Objetivos

• Compreender estrutura de trace id e spans
• Propagar contexto entre chamadas HTTP e eventos Kafka
• Garantir correlação de ponta a ponta no fluxo de compra

Pré-requisitos

• Fluxo completo da aplicacao funcionando.
• Conhecimento basico dos pilares de observabilidade.
• Jaeger e OpenTelemetry Collector ativos no ambiente.

Conceito

trace_id identifica a jornada completa da requisicao. Cada operacao dentro dessa jornada cria um span com duracao e metadados.

Para manter continuidade entre servicos, o contexto deve ser propagado no header HTTP (traceparent) e nos headers da mensagem Kafka.

Estrutura de arquivos

• services/*/telemetry
• contracts/events
• docs/observability-tracing.md
• infra/tracing/otel-collector.yaml

Passo a passo com codigo

1. Extraia contexto no endpoint HTTP:

ctx := otel.GetTextMapPropagator().Extract(r.Context(), propagation.HeaderCarrier(r.Header))
ctx, span := tracer.Start(ctx, "order.create")
defer span.End()

2. Injete contexto ao publicar evento no Kafka:

carrier := make(propagation.MapCarrier)
otel.GetTextMapPropagator().Inject(ctx, carrier)
msg.Headers = append(msg.Headers, kafka.Header{Key: "traceparent", Value: []byte(carrier["traceparent"])})

3. No consumer, restaure contexto:

carrier = {"traceparent": headers.get("traceparent", "")}
ctx = propagator.extract(carrier=carrier)
with tracer.start_as_current_span("payment.consume.order_created", context=ctx):
    process_event(payload)

4. Logue trace_id em todos os servicos.

Como testar

1. Crie um pedido no order-service.
2. Verifique se traceparent aparece nos headers Kafka.
3. Confirme que payment, notification e analytics compartilham mesmo trace_id.
4. Abra Jaeger e valide cadeia unica de spans.

Dicas

• Use W3C Trace Context em todas as linguagens.
• Nunca gere novo trace no meio da mesma transacao.
• Defina nomes de span por operacao de negocio.
• Inclua event_id e trace_id em logs estruturados.

Erros comuns

• Gerar trace id novo em cada serviço
• Não propagar contexto no Kafka
• Confundir correlation id com trace id
• Criar spans sem timestamps úteis

Resumo

Propagacao correta de contexto entre HTTP e Kafka e o que transforma traces em visao real de ponta a ponta do fluxo distribuido.