Migrando do AppSignal para JavaScript

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.

@appsignal/browser substitui @appsignal/javascript, suas integrações com frameworks e seus pacotes de plugins. Este guia mapeia a API antiga para a nova. O novo SDK coleta breadcrumbs e web vitals depois de init() e relata erros nas visualizações Browser. Migre quando estiver pronto para adotar a API dele e revise as mudanças abaixo.

O que muda

Um pacote em vez de vários. Error tracking, breadcrumbs e web vitals estão todos em @appsignal/browser. O novo SDK não tem pacotes de plugins ou de frameworks correspondentes. Alguns recursos vêm embutidos; outros exigem código da aplicação. Funções em vez de uma instância. Não há objeto de cliente para criar, passar adiante ou entregar a um componente. Você chama init() uma vez e importa as funções de que precisa onde precisar delas. Erros não capturados são relatados sem pedir. @appsignal/plugin-window-events existia porque era preciso ativá-los explicitamente. Agora eles estão ligados por padrão. O SDK descarta erros opacos de scripts cross-origin. Use beforeError para filtrar outros ruídos de navegador ou extensão. Os erros são relatados no namespace browser. @appsignal/javascript relatava em frontend, e não existe mais uma opção namespace. Novos erros aparecem na seção Browser. Os erros existentes em frontend permanecem na lista atual deles. Incidents existentes no namespace frontend permanecem onde estão.

As configurações de notificação são definidas por namespace, então as que você configurou para frontend não se aplicam a browser. Configure-as novamente depois de migrar, ou os erros de front-end vão chegar sem notificar ninguém.

Seus incidents existentes em frontend mantêm seus responsáveis, estados e severidades. O novo pacote relata no namespace browser. As novas issues dele começam sem responsável, como qualquer outra issue nova. Sem spans, decorators ou overrides. O novo SDK não tem equivalente para a antiga API de span. Use setTags() para tags nos erros seguintes, e beforeError ou beforeBreadcrumb para remover dados sensíveis. O contexto opcional passado para captureError() não é incluído nos relatórios de erro comuns nesta beta.

Configuração

`@appsignal/javascript`	`@appsignal/browser`
`new Appsignal({ ... })`	`init({ ... })`
`key`	`key`, sem mudança. A mesma Front-end API key.
`revision`	`appVersion`
`namespace`	Sem equivalente. Os erros são sempre relatados em `browser`.
`ignoreErrors: [/pattern/]`	`beforeError`, retornando `null` quando houver correspondência.
`matchBacktracePaths`	Sem equivalente. Fale com a gente se você depende disso.
Sem equivalente	`active`, para desligar o SDK completamente fora de produção.
Sem equivalente	`endpoint`, `errors.sampleRate`, `breadcrumbs.`, `privacy.`.

Antes:

import Appsignal from "@appsignal/javascript";
import { plugin as windowEvents } from "@appsignal/plugin-window-events";
import { plugin as consoleBreadcrumbs } from "@appsignal/plugin-breadcrumbs-console";
import { plugin as networkBreadcrumbs } from "@appsignal/plugin-breadcrumbs-network";

export const appsignal = new Appsignal({
  key: "<YOUR_FRONTEND_API_KEY>",
  revision: "<YOUR_APP_REVISION>",
  ignoreErrors: [/ResizeObserver/],
});

appsignal.use(windowEvents());
appsignal.use(consoleBreadcrumbs());
appsignal.use(networkBreadcrumbs());

Depois:

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>",
  beforeError: (event) => (/ResizeObserver/.test(event.message) ? null : event),
});

Exceções não capturadas, breadcrumbs de console e breadcrumbs de rede são todos cobertos por essa única chamada.

Métodos

`@appsignal/javascript`	`@appsignal/browser`
`appsignal.sendError(error)`	`captureError(error)`
`appsignal.sendError(error, (span) => span.setTags({ ... }))`	Sem equivalente direto para tags por erro. `setTags({ ... })` se aplica aos erros seguintes, até que essas tags sejam limpas.
`appsignal.wrap(fn)`	Sem equivalente. Use `try`/`catch` com `captureError`.
`appsignal.addBreadcrumb({ category, action, message, metadata })`	`addBreadcrumb({ category, message, data })`. Não existe campo `action`, e `metadata` agora é `data`.
`appsignal.createSpan()`, `appsignal.send(span)`	Sem equivalente.
`appsignal.addDecorator(fn)`	`setTags()` para tags, `beforeError` para todo o resto.
`appsignal.addOverride(fn)`	`beforeError` e `beforeBreadcrumb`.
`appsignal.use(plugin())`	Sem equivalente. Já embutido.
Sem equivalente	`setRouteTemplate()`, que agrupa erros e web vitals por rota.
Sem equivalente	`setTags()`, `clearTags()`, `destroy()`.

appsignal.wrap() executava seu código e relatava os erros lançados. A promise devolvida rejeitava com o mesmo erro, para que seu código pudesse capturá-lo. A substituição direta torna as duas metades explícitas:

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

try {
  await riskyOperation();
} catch (error) {
  captureError(error);
  throw error;
}

Integrações com frameworks

Pacote	Substituição
`@appsignal/react`	`@appsignal/browser/react`. Passe `captureError` em vez de uma prop `instance`. Não existe prop `override` nem um componente `LegacyBoundary` separado.
`@appsignal/vue`, `@appsignal/angular`, `@appsignal/preact`, `@appsignal/ember`, `@appsignal/stimulus`	Sem equivalente. Erros que esses frameworks deixam passar são relatados automaticamente. Relate os que o framework captura por conta própria com `captureError()` a partir do handler de erros dele.
`@appsignal/urql`	Sem equivalente. Relate erros de GraphQL com `captureError()` a partir do error exchange do seu cliente.
`@appsignal/plugin-path-decorator`	`setRouteTemplate()`, o equivalente embutido.

O error boundary do React muda de forma:

import { ErrorBoundary } from "@appsignal/react";
import { appsignal } from "./appsignal";

<ErrorBoundary instance={appsignal} action="Dashboard" tags={{ plan: "pro" }}>
  <Dashboard />
</ErrorBoundary>

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

<ErrorBoundary captureError={captureError}>
  <Dashboard />
</ErrorBoundary>

O novo boundary não tem prop action. Chame setRouteTemplate() para a rota usada para agrupar erros. Se você usa setTags(), chame-a depois de init() e limpe-a quando essas tags não devem mais valer.

Passos para migrar

Instale @appsignal/browser@beta e remova @appsignal/javascript junto com todos os pacotes @appsignal/plugin-* e de integração com frameworks.
Substitua sua chamada new Appsignal({ ... }) por init({ ... }), usando a tabela de configuração deste guia. Adicione endpoint e active.
Substitua sendError por captureError, e wrap por try/catch.
Mova padrões de ignoreErrors, decorators e overrides para beforeError e beforeBreadcrumb.
Chame setRouteTemplate() em cada navegação do roteador.
Troque o import do error boundary do React, se você usa um.
Configure as notificações para o namespace browser.
Publique e depois confirme que erros e web vitals chegam na seção Browser da sua aplicação.

Sourcemaps não precisam de mudança. Eles continuam sendo correspondidos pela string de revisão, que agora appVersion fornece.

SDKs & telemetria

SDKs de linguagem

Ferramentas de telemetria

O que muda

Configuração

Métodos

Integrações com frameworks

Passos para migrar

​O que muda

​Configuração

​Métodos

​Integrações com frameworks

​Passos para migrar

O que muda

Configuração

Métodos

Integrações com frameworks

Passos para migrar