Rastreamentos OpenTelemetry do navegador

O SDK JavaScript do OpenTelemetry para navegadores consiste em vários pacotes: @opentelemetry/sdk-trace-web fornece a implementação central de rastreamento, @opentelemetry/instrumentation-fetch cria automaticamente intervalos para todas as chamadas da API fetch e @opentelemetry/exporter-trace-otlp-http envia intervalos a um coletor.

O TracerProvider é o objeto central de configuração no OpenTelemetry. Ele contém a lista de SpanProcessors (que determinam o que acontece com os intervalos concluídos), o recurso que descreve sua aplicação (nome e versão do serviço) e qualquer configuração de amostragem.

O BatchSpanProcessor coleta intervalos concluídos na memória e os exporta em lotes, em vez de enviar cada intervalo individualmente. Isso reduz drasticamente o número de solicitações HTTP ao coletor, melhorando o desempenho do navegador e reduzindo a carga no endpoint do coletor do OpenTelemetry.

OTLPTraceExporter envia intervalos agrupados a um coletor compatível com OpenTelemetry via HTTP no formato JSON ou protobuf. Você configura a URL do coletor (por exemplo, o endpoint de proxy do coletor do OpenTelemetry), e o exportador cuida automaticamente da serialização e da lógica de novas tentativas.

Um intervalo representa uma unidade de trabalho dentro de um rastreamento: a montagem de um componente, uma chamada de API ou uma interação do usuário. Os intervalos têm um nome, horário de início, horário de término, status (OK ou ERROR) e um conjunto de atributos de chave-valor. Intervalos relacionados são vinculados por um ID de rastreamento compartilhado e por relações pai-filho.

Você cria um rastreador com provider.getTracer('react-app') e inicia intervalos com tracer.startSpan('component-mount'). Depois que o trabalho termina, chame span.end() para registrar o horário de término. Sempre encerre os intervalos — intervalos não encerrados desperdiçam memória e produzem dados incompletos no seu sistema de observabilidade.

Os atributos enriquecem os intervalos com dados contextuais: span.setAttribute('user.id', userId) ou span.setAttribute('route', location.pathname). Os atributos podem ser pesquisados no seu sistema de observabilidade, permitindo consultas como "mostre todos os intervalos lentos do usuário 42" ou "mostre todos os erros na rota /checkout".

@opentelemetry/instrumentation-fetch modifica dinamicamente a função fetch global para criar automaticamente intervalos para cada solicitação HTTP de saída. O intervalo captura a URL, o método, o código de status HTTP e a duração sem exigir alterações nas suas chamadas fetch existentes.

Quando a instrumentação de solicitações cria um intervalo para uma solicitação de saída, ela injeta o cabeçalho traceparent do W3C TraceContext na solicitação. O back-end receptor lê esse cabeçalho e dá continuidade ao mesmo rastreamento, criando um rastreamento conectado que abrange o navegador e o servidor.

A inicialização do OpenTelemetry deve ocorrer antes da montagem de qualquer componente — normalmente no arquivo de entrada do aplicativo (main.tsx), antes da chamada ReactDOM.createRoot. Crie o provedor, registre os processadores e exportadores e chame provider.register() para torná-lo o TracerProvider global.

Registrar cada interação do usuário em aplicativos com alto tráfego gera enormes quantidades de dados de rastreamento. Configure um amostrador TraceIdRatioBased (por exemplo, amostrando 10% dos rastreamentos) no TracerProvider para reduzir o volume. Sempre amostre 100% dos rastreamentos de erro usando um amostrador ParentBased para garantir que nenhum erro seja perdido.

Por que o BatchSpanProcessor é usado em vez do SimpleSpanProcessor em aplicativos de navegador?

O SDK JavaScript do OpenTelemetry instrumenta navegadores com TracerProvider, BatchSpanProcessor e OTLPTraceExporter. Os intervalos representam unidades de trabalho enriquecidas com atributos. A instrumentação de solicitações cria automaticamente intervalos para chamadas de API e injeta cabeçalhos W3C TraceContext para o rastreamento distribuído de ponta a ponta. Inicialize cedo, faça a amostragem adequadamente e sempre finalize os intervalos para manter dados de rastreamento organizados.