Correlacionando rastreamentos do frontend e do backend

O objetivo final da observabilidade do front-end é um único rastreamento que conecte o clique de um usuário no React à rede, aos manipuladores de API, às chamadas de serviço e à consulta ao banco de dados que causou uma resposta lenta. Esse rastreamento de ponta a ponta torna instantânea a análise da causa raiz.

A especificação W3C TraceContext define o formato do cabeçalho traceparent: version-traceId-parentSpanId-flags. Um valor de exemplo é: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01. O ID do rastreamento é compartilhado por todo o rastreamento distribuído; o ID do intervalo pai muda a cada salto.

A instrumentação de solicitações do OpenTelemetry injeta automaticamente o cabeçalho traceparent em cada solicitação de saída. O cabeçalho transporta o ID atual do rastreamento e o ID do intervalo da solicitação do front-end como pai, permitindo que o back-end crie um intervalo filho vinculado ao intervalo do front-end.

No servidor, a instrumentação HTTP do OpenTelemetry para Node.js/Express lê o cabeçalho traceparent recebido e cria intervalos que são filhos do intervalo da solicitação do front-end. O ID do rastreamento é preservado, então o Jaeger ou o Grafana Tempo mostram toda a cadeia — intervalo do navegador → intervalo do Express → intervalo do banco de dados — em uma única visualização em cascata.

Com o front-end e o back-end instrumentados, abra o Jaeger ou o Grafana Tempo e pesquise um ID de rastreamento. Você verá a cascata completa: o intervalo do componente React no topo, o intervalo da solicitação abaixo dele, depois o intervalo do manipulador de rota do Express e, por fim, o intervalo da consulta ao banco de dados — todos com suas durações e atributos.

Defina user.id como um atributo em todos os intervalos do seu aplicativo React usando span.setAttribute('user.id', userId). Faça o mesmo no back-end. Agora você pode filtrar seu back-end de observabilidade para mostrar todos os rastreamentos de um ID de usuário específico, permitindo diagnosticar problemas relatados por um cliente específico.

Gere um ID de sessão exclusivo ao carregar a página e defina-o como session.id em todos os intervalos do front-end. Inclua-o nos cabeçalhos das solicitações para que o back-end também o associe aos intervalos do back-end. A correlação por sessão permite reconstruir a sequência completa de ações realizadas por um usuário em uma única sessão.

Ferramentas comerciais como o Datadog integram sessões RUM a rastreamentos APM de forma nativa. O SDK RUM do Datadog injeta um cabeçalho específico (X-Datadog-Trace-Id) nas solicitações, e o SDK APM do Datadog no back-end o lê para vincular a reprodução da sessão RUM ao rastreamento distribuído — você pode assistir à reprodução da sessão e ver o rastreamento simultaneamente.

Considere um usuário reclamando que o checkout está lento. Com rastreamamentos correlacionados, pesquise por user.id no seu back-end de observabilidade, encontre o rastreamento do checkout e veja imediatamente que a lentidão foi causada por uma consulta de 900 ms ao banco de dados, combinando duas tabelas grandes — algo invisível apenas nas métricas do front-end.

Os navegadores não podem enviar rastreamentos diretamente para o Jaeger ou outros back-ends devido a restrições de CORS e à exposição de credenciais. Em vez disso, execute um OpenTelemetry Collector como proxy: configure OTLPTraceExporter para enviar dados ao ponto de extremidade do Collector, que então os distribui para o Jaeger, o Grafana Tempo ou qualquer outro back-end.

Os rastreamentos do front-end podem capturar inadvertidamente dados sensíveis: valores de campos de formulário em URLs, PII em atributos de intervalos e tokens de sessão nos cabeçalhos. Revise sua instrumentação para garantir que nenhum dado sensível seja incluído nos atributos dos intervalos. Use span.setAttribute com moderação e higienize os parâmetros de consulta das URLs antes de registrá-los.

Qual é o formato do cabeçalho traceparent do W3C TraceContext?

A correlação entre os rastreamentos do front-end e do back-end cria visibilidade de ponta a ponta em toda a jornada da solicitação do usuário. Os cabeçalhos traceparent do W3C TraceContext conectam automaticamente os intervalos das solicitações do navegador aos intervalos do back-end por meio da instrumentação do OpenTelemetry. Enriqueça todos os intervalos com user.id e session.id para uma depuração direcionada. Use um OpenTelemetry Collector como proxy entre o navegador e o back-end para evitar problemas de CORS e exposição de credenciais.