Pular para o conteúdo principal
Browser monitoring é uma funcionalidade em beta do AppSignal Labs. O pacote @appsignal/browser é publicado sob a tag beta no npm, e sua configuração e API ainda podem mudar entre releases beta. Compartilhe seu feedback na nossa comunidade no Discord.
Uma página de produto relata uma requisição GET /api/boom/ com falha: HTTP 500. Você sabe que a requisição falhou, mas não o motivo. O distributed tracing segue essa requisição do navegador até o back-end que a tratou e lançou um RuntimeError. Neste exemplo, esse é um app Django. Qualquer back-end que suporte distributed tracing funciona da mesma forma. O mapa de serviços mostra os dois lados desse trace:
Mapa de serviços do trace com duas caixas, Browser e django, ambas marcadas com um erro, conectadas por uma aresta de 81 ms.

O mapa de serviços para este trace: o erro de back-end conectado ao erro de navegador que o iniciou.

Para conectar o erro do navegador ao trabalho no back-end, configure os dois lados:
  1. Navegador: adicione os padrões de URL da sua API a tracePropagationTargets. As requisições correspondentes carregam um cabeçalho traceparent e um cabeçalho tracestate que identifica o serviço do navegador e sua rota. Uma resposta 5xx ou um timeout qualificado vira um erro de navegador.
  2. Back-end receptor: instrumente o serviço que trata essas requisições. A instrumentação lê traceparent e reporta spans por um collector hospedado do AppSignal. Use uma integração suportada ou instrumentação OpenTelemetry para o framework dele.
A etapa 1 sozinha só relata o erro de navegador. A linha do tempo do trace permanece vazia até que o back-end seja instrumentado na etapa 2, porque os spans do servidor vêm dessa instrumentação, não do SDK do navegador. As duas etapas são necessárias para ver a requisição como um único trace.
Distributed tracing é uma funcionalidade em beta do AppSignal Labs. O SDK do navegador não precisa de collector. O serviço receptor precisa de um collector hospedado do AppSignal para seus spans.

Antes de começar

Seu front-end precisa apenas do SDK do Browser. O resto da configuração fica no back-end: o serviço que trata as requisições do seu front-end. No exemplo acima, esse é o serviço Django. Pode ser uma API em seu próprio host, ou o mesmo app que serve suas páginas. Configure-o primeiro, para que seus spans apareçam no trace quando uma requisição falhar:
  • Reportar por um collector hospedado. Na página “Hosted Collectors” nas configurações da sua organização, abra um collector e copie sua Collector URL. Envie os dados do serviço para essa URL. Se a lista estiver vazia, crie um collector lá primeiro. O distributed tracing só funciona por um collector hospedado. Em Python e Ruby, defina a URL como a opção collector_endpoint. O Ruby também precisa da gem appsignal-opentelemetry.
  • Definir um nome de serviço. Dê ao serviço seu próprio nome. O trace o usa para diferenciar o serviço do navegador e de outros serviços. Onde você o define depende da linguagem do back-end:
  • Instrumentar o servidor HTTP dele. Use uma integração para o framework dele que leia traceparent nas requisições recebidas. É assim que o serviço se junta ao trace do navegador em vez de iniciar o seu próprio. No Go, também registre um propagator com otel.SetTextMapPropagator.
  • Permitir traceparent e tracestate entre origens. Um back-end pode estar em outra origem, como api.example.com chamado a partir de www.example.com. O navegador pode então enviar um preflight CORS antes da requisição. Permita os dois cabeçalhos na resposta do back-end ao preflight. Se ele permitir apenas traceparent, o navegador bloqueia a requisição:
Node.js e Elixir ainda não são suportados. Com um back-end Node.js, como Express ou rotas de API do Next.js, requisições com falha ainda são relatadas como erros de navegador. Os traces delas não mostram spans de back-end.

Ativar

Adicione um padrão para cada host e caminho de back-end em tracePropagationTargets. A lista vazia padrão deixa o tracing desligado:
Os padrões correspondem ao host e ao caminho de cada chamada fetch e XMLHttpRequest. O SDK se conecta a essas APIs do navegador. Por isso, a configuração é a mesma em React, Vue ou JavaScript puro. Isso inclui bibliotecas construídas sobre eles, como axios. Os padrões ignoram o esquema e a query string. Uma URL relativa é resolvida em relação ao endereço da página. Por isso, uma chamada para /api/orders a partir de www.example.com corresponde a www.example.com/api/**. Use * dentro de um segmento de caminho, ou ** por vários segmentos. Inclua tanto um host quanto um caminho: Na linha do tempo do trace, serviceName identifica o span de erro do navegador. Por exemplo, Checkout UI identifica erros do seu front-end de checkout. O padrão é Browser. Use um nome diferente para cada front-end que você monitora. O SDK envia o nome com todo relatório de erro. O fluxo de instalação do SDK do Browser oferece Distributed tracing como opção. Está desligada por padrão. Selecioná-la adiciona tracePropagationTargets: ["api.example.com/**"] ao snippet do navegador. Substitua o host de exemplo pelo host do seu back-end e, depois, instrumente o serviço receptor. O assistente não instala nem configura esse serviço. Para verificar a propagação, carregue uma página que chama sua API e inspecione a requisição no painel Network do seu navegador. Uma requisição correspondente deve carregar os cabeçalhos traceparent e tracestate. Depois, inspecione uma requisição com falha no AppSignal para conferir se os spans de back-end aparecem no trace dela. O SDK não adiciona nenhum cabeçalho a uma requisição feita no modo no-cors, porque o navegador o removeria. Essas requisições nunca são relatadas como requisições com falha.

O que é relatado

O SDK relata esses resultados para uma requisição correspondente que enviou um cabeçalho traceparent:
  • Uma resposta 5xx é relatada como HTTPError.
  • Um timeout é relatado como TimeoutError. Isso é um fetch que rejeita com um TimeoutError, como o que é limitado por AbortSignal.timeout(). Também é um XMLHttpRequest cujo timeout dispara. O servidor pode ter recebido e rastreado uma requisição que expirou.
A mensagem nomeia a requisição e seu resultado, por exemplo POST https://api.example.com/orders: HTTP 503 ou GET https://api.example.com/orders: timed out. Além de tudo que um erro de navegador comum carrega, o relatório inclui:
  • A requisição, como params.request: a url, o method, o status quando uma resposta chegou, e a duration_ms. Os parâmetros de query são removidos da URL conforme sua allowlist.
  • O span: o ID de trace e o ID de span a partir do traceparent da requisição, com sua hora de início e duração. O AppSignal constrói o span do navegador a partir deles, então ele cobre a requisição como o navegador a viu. Depois de um timeout, os spans do back-end podem durar mais do que o span do navegador.
  • O nome de serviço que você definiu, ou Browser.
Nada é relatado para:
  • Uma requisição bem-sucedida. O cabeçalho é enviado, mas o navegador fica em silêncio, então o trace de back-end se sustenta sozinho.
  • Uma resposta 4xx. O SDK não a classifica como uma requisição com falha para o tracing.
  • Uma requisição que o navegador não conseguiu entregar: recusada, falha de DNS, ou bloqueada por uma extensão. Nenhum servidor a tratou, então não há trace de back-end para se juntar.
  • Um timeout enquanto o dispositivo está offline, o que não diz nada sobre o back-end.
  • Uma requisição que seu código cancelou.
Essas requisições ainda podem deixar um breadcrumb de rede, a menos que correspondam a privacy.networkBlocklist ou a coleta de breadcrumbs esteja desativada. Um breadcrumb de uma requisição que propagou contexto inclui seu ID de trace. Seu botão Open trace abre a linha do tempo desse trace. Uma requisição com falha passa pelo mesmo pipeline que qualquer outro erro. errors.enabled, errors.sampleRate, os limites de taxa e a deduplicação de repetições se aplicam todos. beforeError a recebe como HTTPError ou TimeoutError, com a requisição em context.request. Você pode descartá-la ou redigi-la ali. Uma requisição que corresponde a privacy.networkBlocklist nunca é relatada. O SDK evita relatar a mesma rejeição de fetch duas vezes quando ela também chega a um handler de rejeição não tratada ou a captureError(). Se seu código lançar um novo erro depois de uma resposta 500, esse erro tem seu próprio trace. A requisição com falha permanece um relatório separado.

Lendo no AppSignal

Requisições com falha aparecem na visualização Errors da seção Browser como issues HTTPError e TimeoutError. Elas são agrupadas pela rota em que o usuário estava, como qualquer outro erro de front-end. Leia mais em erros de front-end no AppSignal. Abra uma issue para ver sua mensagem, breadcrumbs e tags no painel lateral. Sua aba Sample também mostra o trace: os cards Trace service map, Trace timeline e as linhas de log relacionadas. Selecione Fullscreen no card Trace timeline para abrir a visualização abaixo. Se a prévia omitir spans, o botão mostra All spans. Open full trace page, o ícone ao lado do número da issue, abre a página completa da issue. Na linha do tempo em tela cheia, Browser identifica o serviço do span do navegador. Selecione esse span para ver os detalhes da requisição e do erro. No exemplo da página de produto, GET /api/boom/ retornou HTTP 500. Na linha do tempo do trace, você pode seguir a requisição com falha do navegador até o serviço Django:
  • Browser mostra uma HTTPError em /product/chocolate-stroopwafel (85 ms). Os detalhes do span selecionado mostram a URL da requisição e a resposta HTTP 500.
  • Abaixo, django mostra GET api/boom/ com um RuntimeError (81 ms).
  • A requisição Django contém dois spans SELECT e um span POST, com suas durações.
Linha do tempo do trace ligando uma HTTPError de navegador de 85 ms para GET /api/boom/ (HTTP 500) a uma RuntimeError do Django de 81 ms, com spans filhos SELECT e POST.

A requisição com falha do navegador e os spans relacionados do Django em um único trace.

Juntando-se a um trace que seu código iniciou

Sua aplicação pode já definir um traceparent válido em uma requisição, por exemplo através de um SDK de navegador OpenTelemetry. O AppSignal para Browser então deixa esse cabeçalho intacto, e uma requisição com falha se junta ao trace que seu código iniciou. Isso vale tanto para fetch quanto para XMLHttpRequest. Na aba Traces da issue, abra a linha do tempo do trace em tela cheia para inspecionar o trabalho de back-end.