Rastreamento Distribuído

Quando Usar

Rastreie uma solicitação entre serviços, diagnostique a propagação de latência e erros, ou adicione limites observáveis a uma nova integração.

Entradas e Pré-requisitos

Registre as versões do SDK e do backend instalados, os endpoints permitidos do coletor, o gráfico de serviços e uma solicitação de staging. Inspecione a documentação principal da versão instalada antes de selecionar APIs de exportação ou configuração de implantação. Este pacote não instala um backend de rastreamento.

Procedimento

1. Leia resources/implementation-playbook.md e identifique uma jornada do usuário.
2. Configure o SDK OpenTelemetry correspondente e o exportador OTLP antes de carregar os frameworks instrumentados. Use references/instrumentation.md para propagação, encerramento e verificações de privacidade.
3. Configure o Jaeger usando references/jaeger-setup.md, ou a configuração suportada da implantação existente do Tempo/coletor. Revise listeners, autenticação, proteção de transporte, armazenamento e retenção antes de qualquer implantação.
4. Propague o contexto por meio de mensagens HTTP e assíncronas. Use nomes de operação estáveis e atributos permitidos. Não registre credenciais, corpos de solicitação brutos ou valores de consulta sensíveis.
5. Envie solicitações de staging bem-sucedidas e falhas e verifique os spans conectados no backend. Registre a identidade do serviço, a parentesco, as unidades de duração e os erros do exportador.
6. Meça a perda e a sobrecarga da fila. Selecione a amostragem com base nessas observações; nenhuma porcentagem fixa garante cobertura ou desempenho.

Exemplo

Um checkout chama o inventário e o pagamento. Verifique se a solicitação raiz e ambas as operações downstream compartilham um rastreamento, que um tempo limite simulado de pagamento é registrado e que nenhum dado de cartão está presente. Repita com a conectividade do exportador indisponível: o tratamento da solicitação deve reter o comportamento definido da aplicação.

Verificação

• Evidência de rastreamento real para cada limite exercido, incluindo consumidores de fila.
• Apenas campos permitidos; cardinalidade de atributos limitada.
• Comportamento de flush de encerramento e falha do exportador observado.
• Acesso, armazenamento e retenção verificados independentemente da disponibilidade da UI.

Limitações

A amostragem de cabeça pode descartar erros antes que a amostragem de cauda os veja. Demonstrações em memória não comprovam armazenamento durável. A propagação de contexto e os relógios entre serviços precisam de testes de integração reais; este guia não é uma aplicação multisserviço executável.

Fontes

• Documentação do exportador OpenTelemetry — use a documentação correspondente do SDK instalado.