> ## Documentation Index
> Fetch the complete documentation index at: https://docs.appsignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Browser error tracking

<Note>
  Browser monitoring é uma funcionalidade em beta do [AppSignal Labs](/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](https://discord.gg/EjF6ykYx63).
</Note>

Depois que `init()` roda, o AppSignal para Browser relata erros não capturados por conta própria. Não há nada para envolver nem handler para registrar.

Ele escuta duas coisas no `window` principal da página:

* Erros que seu código lança e nunca captura, pelo evento `error`.
* Promises que falham sem nada para tratar a falha, pelo evento `unhandledrejection`.

O SDK começa a enviar cada erro assim que ele é capturado, sem esperar por um lote de web vitals. A entrega ainda depende do navegador e da rede.

<h2 id="what-is-reported">
  O que é relatado
</h2>

* **Nome e mensagem do erro.** O tipo de erro, por exemplo `TypeError`, e a mensagem que veio com ele.
* **Backtrace.** O stack trace, uma linha por frame. Vazio se o navegador não fornecer nenhum.
* **Action.** A rota em que o erro aconteceu. Os erros são agrupados por ela.
* **Revisão.** A `appVersion` que você definiu. Usada para filtrar por versão e para encontrar os sourcemaps corretos.
* **Tags.** Tudo que você definiu com `setTags()`.
* **Nome do serviço.** O `serviceName` que você definiu, ou `Browser`. Ele identifica o front-end entre os serviços de um trace.
* **Breadcrumbs.** Até 25 [breadcrumbs](/browser/breadcrumbs) recentes que ajudam a explicar o erro.
* **URL e user agent.** A página em que o erro aconteceu, com os parâmetros de query removidos conforme a sua [allowlist](/browser/privacy#urls-and-query-parameters), e o user agent do navegador.

Uma promise rejeitada pode conter um valor diferente de um `Error`. O SDK transforma esse valor em uma mensagem de erro quando consegue.

Os erros são relatados no namespace `browser` (veja [namespaces](/guides/namespaces)), o que os mantém separados dos seus erros de back-end e das configurações de notificação deles.

<h2 id="how-errors-are-grouped">
  Como os erros são agrupados
</h2>

Os erros se agrupam por action. Esse é o template definido com `setRouteTemplate()`, ou o caminho bruto da página quando nenhum foi definido.

Declarar um template é o que impede uma rota cheia de IDs de se fragmentar em um grupo de erros por ID:

<CodeGroup>
  ```js JavaScript theme={null}
  import { setRouteTemplate } from "@appsignal/browser";

  // Every error on this route now groups under "/orders/:id"
  setRouteTemplate("/orders/:id");
  ```
</CodeGroup>

Chame-o em cada navegação do roteador. É o mesmo valor ao qual [as web vitals são atribuídas](/browser/web-vitals#how-values-are-attributed-to-routes), então uma chamada cobre os dois.

<h2 id="reporting-errors-manually">
  Relatando erros manualmente
</h2>

Use `captureError()` para erros que você mesmo captura. Ele passa pelo mesmo pipeline de um erro não capturado, incluindo breadcrumbs, tags, amostragem e `beforeError`:

<CodeGroup>
  ```js JavaScript theme={null}
  import { captureError } from "@appsignal/browser";

  try {
    await submitOrder(order);
  } catch (error) {
    captureError(error);
  }
  ```
</CodeGroup>

O SDK atual aceita um segundo argumento de contexto, mas não o inclui em relatórios de erro comuns. Use [`setTags()`](#tags) para valores que devem aparecer em erros subsequentes.

Aplicações React podem capturar erros de renderização com o [error boundary](/browser/react) em vez de envolver componentes manualmente.

<h2 id="failed-requests">
  Requisições com falha
</h2>

Com [`tracePropagationTargets`](/browser/configuration#tracepropagationtargets) definido, uma requisição para a sua API que responde com 5xx ou expira é relatada por conta própria. Ela chega como um `HTTPError` ou um `TimeoutError`, carregando o ID de trace que a requisição enviou para o back-end. Se o back-end continuou o trace, seus spans aparecem abaixo do erro de navegador na linha do tempo do trace. Leia mais em [distributed tracing para Browser](/browser/distributed-tracing).

<h2 id="tags">
  Tags
</h2>

Tags são pares de chave e valor em texto anexados a todo erro relatado a partir daquele ponto. É por elas que você filtra e busca erros no AppSignal:

<CodeGroup>
  ```js JavaScript theme={null}
  import { setTags, clearTags } from "@appsignal/browser";

  // After authentication, once the values are known
  setTags({ plan: user.plan, org_id: user.orgId });

  // On sign-out. Tags survive a reload, so clear them explicitly
  clearTags();
  ```
</CodeGroup>

Cada chamada soma às tags que você já definiu, em vez de substituí-las. Os valores viram texto. Um valor vazio remove sua tag. Você pode manter até 32 tags; a mais antiga é descartada quando necessário. Valores longos são reduzidos para 256 bytes na chegada. Leia mais no nosso [guia de tagging](/application/tagging).

Alguns nomes de tag fazem mais do que filtrar. As tags `country_code`, `country` e `browser` produzem [distribuições de atributos](/guides/tagging/attribute-distributions). Qualquer tag pode ser transformada em link com [templates de link](/application/link-templates).

<h2 id="rate-limits">
  Limites de taxa
</h2>

Uma página presa em um loop pode lançar milhares de erros por segundo. Dois limites evitam que o SDK se torne o problema que deveria relatar:

* **O mesmo erro repetidas vezes.** A mensagem e a primeira linha de stack trace determinam se dois erros são repetições. O AppSignal o relata no máximo cinco vezes a cada 10 segundos.
* **Erros demais de uma vez.** No total, não são relatados mais de 100 erros a cada 10 segundos. Isso pega uma página que lança muitos erros *diferentes*, o que o primeiro limite deixaria passar.

Se erros desaparecem enquanto uma página se comporta mal, um desses dois é o motivo. Para enviar menos erros de propósito, defina [`errors.sampleRate`](/browser/configuration#errors-samplerate).

<h2 id="sourcemaps">
  Sourcemaps
</h2>

Um bundle minificado produz stack traces cheios de nomes de uma letra e números de linha enormes. Os [sourcemaps](/front-end/sourcemaps) os transformam de volta nos nomes de arquivo, funções e números de linha que você escreveu. Cada erro envia `appVersion` como sua revisão. O AppSignal usa isso para encontrar os sourcemaps daquele build. Sem ela, os stack traces permanecem minificados.

Se seus sourcemaps são públicos, ao lado dos seus arquivos JavaScript, não há mais nada a fazer. Se você preferir não publicá-los, envie-os para o [endpoint de API de sourcemaps](/api/sourcemaps) usando a mesma revisão.

<h2 id="errors-that-are-not-reported">
  Erros que não são relatados
</h2>

<Warning>
  Alguns erros nunca chegam ao SDK. A maioria são restrições do navegador, e não
  limitações do AppSignal, e cada uma tem uma solução alternativa.
</Warning>

**Erros de scripts em outro domínio.** Quando um script carregado de outro lugar lança um erro, o navegador se recusa a compartilhar os detalhes. Tudo que sua página vê é a mensagem `Script error.`, sem stack trace e sem número de linha. O SDK descarta esses erros opacos porque não contêm nenhum detalhe útil. Para capturar erros de scripts de um CDN, envie um cabeçalho `Access-Control-Allow-Origin` a partir do CDN. Adicione `crossorigin="anonymous"` às tags de script.

**Erros dentro de iframes.** O SDK escuta apenas o `window` em que roda. Para monitorar um iframe que você controla, inicialize o SDK também dentro daquele frame. A página pai não consegue capturar erros de um iframe de origem cruzada.

**Erros antes de `init()`.** Tudo que é lançado antes de `init()` rodar é perdido. Importe sua configuração do AppSignal primeiro, antes de outras bibliotecas e do seu próprio código.

<h2 id="filtering-out-browser-noise">
  Filtrando ruído do navegador
</h2>

Alguns erros vêm do navegador ou de suas extensões, não do seu código, e você não consegue corrigi-los. A opção **Error filtering** do fluxo de instalação os descarta com `beforeError`:

<CodeGroup>
  ```js appsignal.js theme={null}
  import { init } from "@appsignal/browser";

  const IGNORED = [
    /ResizeObserver loop/,
    /^Script error\.?$/,
    /-extension:\/\//,
    /webkit-masked-url/,
  ];

  init({
    key: "<YOUR_FRONTEND_API_KEY>",
    beforeError: (error) => {
      const text = [error.message, error.stack, error.filename].join(" ");
      return IGNORED.some((pattern) => pattern.test(text)) ? null : error;
    },
  });
  ```
</CodeGroup>

Cada padrão é verificado contra a mensagem, o stack trace e o nome de arquivo do erro:

* `ResizeObserver loop`: um aviso do navegador de que notificações de redimensionamento foram adiadas para o próximo frame. Geralmente inofensivo.
* `Script error.`: um erro de um script em outro domínio, sem detalhes para depurar. O SDK já descarta os que chegam sem stack trace.
* `-extension://`: um erro de uma extensão de navegador, como um script `chrome-extension://` ou `moz-extension://`.
* `webkit-masked-url`: o endereço que o Safari exibe no lugar do script de uma extensão.

Adicione um padrão a `IGNORED` para qualquer outro erro que você tenha decidido ignorar. Um erro descartado não deixa breadcrumb e não conta como repetição. Ele conta para o [limite](#rate-limits) de 100 erros a cada 10 segundos. Leia mais em [filtrando erros e breadcrumbs](/browser/privacy#filtering-errors-and-breadcrumbs).

<h2 id="reviewing-errors-in-appsignal">
  Analisando erros no AppSignal
</h2>

A visualização Errors agrupa esses erros em issues que você pode filtrar por versão e intervalo de tempo, atribuir e sobre as quais pode ser notificado. Leia mais em [erros de front-end no AppSignal](/browser-monitoring/errors).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.