Instalando o AppSignal para Browser

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.

Use este guia para adicionar rastreamento de erros e Web Vitals do navegador à sua aplicação. Os exemplos em Plain JS e React também cobrem distributed tracing, filtragem de erros, mascaramento e tags. Você pode gerar o código da sua aplicação no Browser SDK install flow, ou seguir os exemplos abaixo. Se você ainda não adicionou sua aplicação ao AppSignal, siga primeiro o guia de instalação.

Encontrar sua Front-end API key

Encontre a Front-end API key em Front-end error monitoring, na página “Push & deploy” das configurações da sua aplicação. Use a chave da aplicação e do ambiente que você quer monitorar. Essa chave deve ser incluída no código do navegador. Ela é diferente das Push API keys usadas pelas integrações de back-end. O install flow já insere sua chave no código gerado. Nos exemplos abaixo, substitua <YOUR_FRONTEND_API_KEY> pela sua própria chave.

Gerar o snippet no AppSignal

O Browser SDK install flow permite escolher Plain JS ou React e selecionar quais recursos incluir. Ele começa com Route template selecionado. Os exemplos completos abaixo incluem todas as opções:

Opções	O que é incluído no seu snippet
Route template	`setRouteTemplate()` roda quando sua rota muda, para que `/users/42` possa ser relatado como `/users/:id`.
Distributed tracing	Adiciona `tracePropagationTargets` para que as requisições de API correspondentes levem um cabeçalho `traceparent`. Substitua o host de exemplo pelo seu. Isso configura apenas o navegador; o serviço de API que recebe a requisição também precisa de instrumentação de tracing.
Error filtering	`beforeError` descarta erros que correspondem aos padrões de exemplo de navegador e extensão. Ajuste os padrões para a sua aplicação.
Error tags	`setTags()` adiciona valores como um plano ou tenant aos erros após o login.
Sensitive data masking	`privacy.dom` mascara texto ou exclui breadcrumbs de clique de elementos selecionados. Substitua os seletores CSS de exemplo pelos seus.

O install flow gera código do Browser SDK. Selecionar Distributed tracing não instrumenta seu serviço de API. Para ver os spans dele junto com um erro de requisição do navegador, siga também a configuração do back-end. As duas versões também mostram como relatar um erro que você mesmo capturar. A versão em React inclui um error boundary para erros de renderização.

Instalar o pacote

Instale o AppSignal para Browser a partir da tag beta. Distributed tracing e o relato de requisições com falha exigem a versão 1.0.0-beta.7 ou posterior. O install flow atualmente mostra um comando sem versão; use um destes comandos para a versão beta:

npm install @appsignal/browser@beta

yarn add @appsignal/browser@beta

pnpm add @appsignal/browser@beta

Faça commit do seu lockfile e revise o snippet ao atualizar durante a beta.

Inicializar o SDK

Importe sua configuração do AppSignal antes do código da aplicação que você quer monitorar. Substitua process.env.NODE_ENV e process.env.APP_REVISION pelos valores equivalentes do seu sistema de build. Defina appVersion como sua tag de release ou SHA do commit, para o AppSignal associar os erros aos sourcemaps. Esses exemplos incluem todas as opções do install flow. Substitua api.example.com/** pelo host e caminho da sua API para o distributed tracing. Substitua os seletores CSS, as tags e o exemplo de roteador pelos valores da sua aplicação.

Plain JS
React

1. Inicialize o AppSignal em appsignal.js.

appsignal.js

import { init } from "@appsignal/browser";

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

init({
  key: "<YOUR_FRONTEND_API_KEY>",
  endpoint: "https://appsignal-endpoint.net",
  // Inactive builds send nothing. Replace these with your build values.
  active: process.env.NODE_ENV === "production",
  appVersion: process.env.APP_REVISION,
  // Match your API host and path.
  tracePropagationTargets: ["api.example.com/**"],
  privacy: {
    // Mask text or exclude clicks on these elements.
    dom: { maskText: [".user-email"], blockElement: ["#card-form"] },
  },
  beforeError: (error) => {
    const text = [error.message, error.stack, error.filename].join(" ");
    return IGNORED.some((pattern) => pattern.test(text)) ? null : error;
  },
});

Importe este arquivo primeiro no seu ponto de entrada:

main.js

import "./appsignal";

// Start your application after this import.

2. Relate mudanças de rota a partir do seu roteador. Substitua router.on pelo hook de navegação do seu roteador. Relate também a rota inicial e, depois, relate o modelo dela a cada navegação.

router.js

import { setRouteTemplate } from "@appsignal/browser";

router.on("navigate", (route) => {
  setRouteTemplate(route.pattern); // "/users/:id", not "/users/42"
});

3. Adicione tags após o login. Use valores do usuário ou da conta autenticada. Chame clearTags() no logout para limpar as tags armazenadas.

account.js

import { setTags } from "@appsignal/browser";

setTags({ plan: "pro", tenant: "acme" });

4. Relate erros que você mesmo capturar. Substitua save() pela sua própria operação.

save.js

import { captureError } from "@appsignal/browser";

try {
  save();
} catch (error) {
  captureError(error);
}

1. Inicialize o AppSignal em appsignal.js. Importe este arquivo antes de sua aplicação React iniciar.

appsignal.js

import { init } from "@appsignal/browser";

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

init({
  key: "<YOUR_FRONTEND_API_KEY>",
  endpoint: "https://appsignal-endpoint.net",
  // Inactive builds send nothing. Replace these with your build values.
  active: process.env.NODE_ENV === "production",
  appVersion: process.env.APP_REVISION,
  // Match your API host and path.
  tracePropagationTargets: ["api.example.com/**"],
  privacy: {
    // Mask text or exclude clicks on these elements.
    dom: { maskText: [".user-email"], blockElement: ["#card-form"] },
  },
  beforeError: (error) => {
    const text = [error.message, error.stack, error.filename].join(" ");
    return IGNORED.some((pattern) => pattern.test(text)) ? null : error;
  },
});

Importe este arquivo primeiro no seu ponto de entrada:

main.jsx

import "./appsignal";

// Start your React application after this import.

2. Relate mudanças de rota. Renderize RouteReporter dentro do seu roteador e passe o modelo de rota atual como routePattern. Hooks do React precisam rodar dentro de um componente.

RouteReporter.jsx

import { useEffect } from "react";
import { setRouteTemplate } from "@appsignal/browser";

export function RouteReporter({ routePattern }) {
  useEffect(() => {
    setRouteTemplate(routePattern); // "/users/:id", not "/users/42"
  }, [routePattern]);

  return null;
}

Veja os exemplos de rota do React para React Router e Next.js.3. Adicione tags após o login. Use valores do usuário ou da conta autenticada. Chame clearTags() no logout para limpar as tags armazenadas.

account.js

import { setTags } from "@appsignal/browser";

setTags({ plan: "pro", tenant: "acme" });

4. Capture erros de renderização na raiz da sua aplicação. O boundary relata erros de renderização que não chegam ao handler de erro global do navegador.

AppRoot.jsx

import { captureError } from "@appsignal/browser";
import { ErrorBoundary } from "@appsignal/browser/react";

<ErrorBoundary
  captureError={captureError}
  fallback={<p>This page didn't load. Reload to try again.</p>}
>
  <App />
</ErrorBoundary>

5. Relate erros que você mesmo capturar. Substitua save() pela sua própria operação.

save.js

import { captureError } from "@appsignal/browser";

try {
  save();
} catch (error) {
  captureError(error);
}

Se você só precisa de rastreamento de erros, breadcrumbs e web vitals, pode começar com um arquivo appsignal.js menor. Substitua <YOUR_APP_REVISION> pela sua tag de release ou SHA do commit:

import { init } from "@appsignal/browser";

init({
  key: "<YOUR_FRONTEND_API_KEY>",
  endpoint: "https://appsignal-endpoint.net",
  active: process.env.NODE_ENV === "production",
  appVersion: "<YOUR_APP_REVISION>",
});

Importe appsignal.js primeiro no seu ponto de entrada, como mostrado acima. Essa configuração menor não adiciona cabeçalhos traceparent às suas requisições de API. Para qualquer configuração, active: false impede que o SDK colete ou envie dados. endpoint usa por padrão a origem da página atual. Defina-o como https://appsignal-endpoint.net, a menos que você faça proxy das requisições do AppSignal pelo seu próprio domínio. Veja todas as opções de configuração.

Instalação sem bundler

Se o seu site carrega JavaScript com tags <script> e não usa um bundler, use o build UMD. Ele expõe o SDK como AppsignalBrowser em window:

<script src="https://cdn.jsdelivr.net/npm/@appsignal/browser@1.0.0-beta.7/dist/browser.umd.js"></script>
<script>
  AppsignalBrowser.init({
    key: "<YOUR_FRONTEND_API_KEY>",
    endpoint: "https://appsignal-endpoint.net",
    appVersion: "<YOUR_APP_REVISION>",
  });
</script>

Substitua a versão na URL ao atualizar. Uma versão fixa evita uma mudança inesperada do SDK no seu site.

Reportar a rota atual

Use esta etapa para uma aplicação de página única com rotas como /users/42. Passe o modelo de rota, como /users/:id, quando seu roteador navegar. O AppSignal o usa para agrupar erros e web vitals por rota. Os exemplos completos acima mostram onde chamar setRouteTemplate(). Se você não definir um modelo de rota, o SDK relata o caminho atual da página. Isso significa que /users/42 e /users/43 podem aparecer como grupos de erro separados. Veja os exemplos de rota do React para React Router e Next.js.

Verificar a instalação

Implante um build com active definido como true. Você pode usar active: true temporariamente em desenvolvimento.
Abra a página e execute este código no console do navegador:
JavaScript
setTimeout(() => { throw new Error("AppSignal test error"); }, 0);
O timer permite que o erro chegue ao handler de erro global da página. Um erro lançado diretamente no console geralmente é tratado pelo próprio console.
Abra Browser > Errors no AppSignal e encontre AppSignal test error.

As web vitals aparecem depois que o SDK as envia. Isso acontece, por exemplo, quando a página fica oculta ou a rota muda. Se nenhum dado aparecer, veja a solução de problemas do Browser.

Content Security Policy

Se o seu site usa uma Content Security Policy, permita o endpoint do AppSignal configurado na diretiva connect-src. Por exemplo, adicione o endpoint às suas origens já permitidas:

Content-Security-Policy: connect-src 'self' https://appsignal-endpoint.net

Assets hospedados em CDN

Use esta etapa se o JavaScript do seu site carrega de outra origem, como um CDN. Sem acesso cross-origin, o navegador pode relatar apenas Script error., sem stack trace e sem número de linha. O SDK descarta esses erros opacos porque não é possível rastreá-los até o seu código. Sirva o script com um cabeçalho Access-Control-Allow-Origin que permita a origem da sua página, e adicione crossorigin="anonymous" à tag de script:

<script src="https://cdn.example.com/bundle.js" crossorigin="anonymous"></script>

<%= javascript_include_tag "application", :crossorigin => :anonymous %>

Desinstalação

Remova o import de appsignal.js e outras chamadas a @appsignal/browser do seu código. Remova qualquer ErrorBoundary importado de @appsignal/browser/react.
Remova o pacote e atualize seu lockfile com npm uninstall @appsignal/browser, yarn remove @appsignal/browser ou pnpm remove @appsignal/browser. Se você instalou o build UMD, remova a tag <script> dele.
Implante a mudança. O novo build para de relatar dados do navegador.
Se essa aplicação do AppSignal era usada só para browser monitoring, você pode opcionalmente remover a aplicação.

Para parar a coleta sem desinstalar, chame destroy(). Isso envia os dados pendentes e para a coleta até init() rodar novamente, por exemplo após um reload da página.

SDKs & telemetria

SDKs de linguagem

Ferramentas de telemetria

Encontrar sua Front-end API key

Gerar o snippet no AppSignal

Instalar o pacote

Inicializar o SDK

Instalação sem bundler

Reportar a rota atual

Verificar a instalação

Content Security Policy

Assets hospedados em CDN

Desinstalação

​Encontrar sua Front-end API key

​Gerar o snippet no AppSignal

​Instalar o pacote

​Inicializar o SDK

​Instalação sem bundler

​Reportar a rota atual

​Verificar a instalação

​Content Security Policy

​Assets hospedados em CDN

​Desinstalação

Encontrar sua Front-end API key

Gerar o snippet no AppSignal

Instalar o pacote

Inicializar o SDK

Instalação sem bundler

Reportar a rota atual

Verificar a instalação

Content Security Policy

Assets hospedados em CDN

Desinstalação