Como usar o Sentry e o GitLab para capturar erros de reação

O Sentry é uma plataforma de rastreamento de erros que permite monitorar problemas em suas implantações de produção. Ele suporta as linguagens e estruturas de programação mais populares.

O GitLab é uma plataforma DevOps baseada em Git para gerenciar todo o ciclo de vida do desenvolvimento de software. O GitLab pode se integrar ao Sentry para exibir os erros capturados. Neste artigo, usaremos os dois serviços para ficar à frente dos problemas em um aplicativo React.

Preparando

O GitLab e o Sentry têm opções auto-hospedadas e SaaS. As etapas neste guia se aplicam a ambas as variantes. Vamos supor que você já tenha um projeto React pronto para usar em sua instância do GitLab.

Faça login no Sentry e clique no botão Criar projeto no canto superior direito. Clique em “Reagir” sob o cabeçalho “Escolher uma plataforma”. Isso permite que o Sentry adapte trechos de código de exemplo ao seu projeto.

Escolha quando receber alertas usando as opções abaixo de Definir suas configurações de alerta padrão. Selecione “Alertar-me sobre cada novo problema” para receber um e-mail sempre que um erro for registrado. A opção “Quando houver mais de” filtra o ruído criado por eventos duplicados em uma determinada janela de tempo.

Dê um nome ao seu projeto no campo Nome do projeto. Clique em “Criar Projeto” para finalizar a configuração.

Adicionando Sentry à sua base de código

Agora, você precisa integrar o Sentry ao seu código React. Adicione a biblioteca Sentry às dependências do seu projeto usando npm:

npm install @sentry/react

Você precisará inicializar o Sentry o mais rápido possível no JavaScript do seu aplicativo. Isso dá ao Sentry visibilidade dos erros que ocorrem no início do ciclo de vida do React. Adicione o script bootstrap do Sentry antes de sua primeira chamada ReactDOM.render(). Isso geralmente está em index.js:

import App from "./App.js";
import React from "react";
import ReactDOM from "react-dom";
import * as Sentry from "@sentry/react";
 
Sentry.init({
    dsn: "my-dsn"
});
 
ReactDOM.render(<App />, document.getElementById("react"));

Substitua my-dsn pelo DSN que o Sentry exibe na tela de criação do projeto. O DSN identifica exclusivamente seu projeto para que o serviço possa atribuir eventos corretamente.

Capturando erros

O Sentry irá capturar e relatar automaticamente erros de JavaScript não tratados. Embora não possa evitar a falha, ele permite que você saiba que algo deu errado antes que o relatório do usuário chegue.

Aqui está um exemplo de App.js:

import React from "react";
 
export default () => {
    const data = null;
    return data.map((val, key) => {
        <h1 key={key}>{val}</h1>;
    });
};

Este código está quebrado—data está definido como null, então a propriedade map será indefinida. Tentamos chamar data.map() de qualquer maneira para que o aplicativo trave. Você deve ver um problema aparecer no Sentry.

Os problemas do sentry incluem o máximo possível de dados sobre o erro. Você pode ver o URL da página, bem como informações sobre o dispositivo do usuário. O Sentry combinará automaticamente os problemas duplicados. Isso ajuda você a ver se um evento foi único ou uma ocorrência regular que está afetando vários usuários.

O Sentry busca automaticamente os mapas de origem JavaScript quando eles estão disponíveis. Se você estiver usando create-react-app, os mapas de origem são gerados automaticamente por npm run build. Certifique-se de copiá-los para o seu servidor web para que o Sentry possa encontrá-los. Você verá belos rastreamentos de pilha do código-fonte original em vez da pilha ofuscada produzida pela saída de compilação minificada.

Você pode marcar os erros do Sentinela como Resolvidos ou Ignorados assim que forem resolvidos. Você encontrará esses botões abaixo do título do problema e na página de visão geral dos problemas. Use Resolvido quando tiver certeza de que um problema foi corrigido. Ignorado é para casos em que você não pretende abordar a causa raiz. Em sites React, esse pode ser o caso de erros causados por versões antigas do navegador.

Limites de erro

Os limites de erro do React permitem renderizar uma interface do usuário de fallback quando um erro é gerado em um componente. O Sentry fornece seu próprio wrapper de limite de erro. Isso renderiza uma interface do usuário de fallback e registra o erro detectado no Sentry.

import * as Sentry from "sentry";
 
export default () => {
    const data = null;
    return (
        <Sentry.ErrorBoundary fallback={<h1>Something went wrong.</h1>}>
            {
                data.map((val, key) => {
                    <h1 key={key}>{val}</h1>;
                });
            }
        </Sentry.ErrorBoundary>
    );
};

Agora, você pode exibir um aviso aos usuários quando ocorrer um erro. Você ainda receberá o relatório de erro em seu projeto Sentry.

Adicionando integração com o GitLab

Existem dois lados para integrar o GitLab e o Sentry. Primeiro, os projetos do GitLab têm um recurso de “rastreamento de erros” que exibe sua lista de erros do Sentry. Você pode marcar erros como Resolvidos ou Ignorados no GitLab. A segunda parte envolve conectar o Sentry ao GitLab. Isso permite que o Sentry crie automaticamente problemas GitLab quando um novo erro é registrado.

Vejamos primeiro a tela de rastreamento de erros do GitLab. Você precisará criar uma chave de API Sentry. Clique no seu nome de usuário no canto superior esquerdo da interface do usuário do Sentry e, em seguida, nas Chaves de API no menu. Clique em “Criar novo token” no canto superior direito.

Adicione os seguintes escopos de token:

alertas:ler
alertas:escrever
evento:admin
evento:ler
evento:escrever
projeto:ler

Isso permite que o GitLab leia e atualize seus erros do Sentry.

Em seguida, vá para o seu projeto GitLab. Clique em Configurações no menu lateral e depois em Operações. Expanda a seção Rastreamento de erros. Cole seu token de autenticação Sentry no campo “Auth Token” e pressione “Connect”. Se você estiver usando uma instância auto-hospedada do Sentry, também precisará ajustar o campo “Sentry API URI” para corresponder ao URI do seu servidor.

O menu suspenso “Projeto” será preenchido com uma lista de seus projetos do Sentry. Selecione o projeto correto e pressione “Salvar alterações”. Agora você está pronto para usar o Error Tracking no GitLab.

Clique em Operações > Rastreamento de erros na barra lateral esquerda. Você verá sua lista de erros do Sentry. Ele é filtrado para problemas não resolvidos por padrão. Isso pode ser alterado usando os menus suspensos no canto superior direito. Clique em um erro para ver seu rastreamento de pilha detalhado sem sair do GitLab. Existem botões para ignorar, resolver e converter em um problema do GitLab. Depois de abrir um problema no GitLab, você pode atribuir esse item a um membro da equipe para que o bug seja resolvido.

Agora, você pode adicionar o segundo componente de integração - um link do Sentry de volta para o GitLab. Clique em Configurações na barra lateral do Sentry e depois em Integrações. Encontre o GitLab na lista e clique no botão roxo “Adicionar instalação” no canto superior direito. Clique em “Avançar” para ver as informações de configuração.

De volta ao GitLab, clique no ícone do usuário no canto superior direito, seguido de “Preferências”. Clique em “Aplicativos” no menu do lado esquerdo e adicione um novo aplicativo. Use os detalhes mostrados pelo Sentry no pop-up de configuração da instalação.

O GitLab exibirá um ID de aplicativo e uma chave secreta. Retorne ao pop-up Sentinela e insira esses valores. Adicione o URL do servidor GitLab (gitlab.com para GitLab SaaS) e insira o caminho do URL relativo ao seu grupo GitLab (por exemplo, my-group). A integração não funciona com projetos pessoais.

Clique no botão roxo Enviar para criar a integração. O Sentry agora poderá exibir informações do GitLab ao lado de seus erros. Isso inclui a confirmação que introduziu o erro e os rastreamentos de pilha vinculados aos arquivos do GitLab. Os usuários do Sentry em planos pagos podem associar os problemas do GitLab e do Sentry entre si.

Desativando o Sentinela no Desenvolvimento

Você não necessariamente deseja usar o Sentry ao executar seu aplicativo localmente em desenvolvimento. Não chame Sentry.init() se quiser rodar com o Sentry desabilitado. Você pode verificar a presença de uma variável de ambiente local e desabilitar o Sentry se estiver definido.

if (process.env.NODE_ENV === "production") {
    Sentry.init({
        dsn: "my-dsn"
    });
}

NODE_ENV é definido automaticamente por create-react-app. A produção compila a variável em código fixo para produção. Você pode usar isso para habilitar seletivamente o Sentry.

Ativando o Perfil de Desempenho

O Sentry também pode analisar o desempenho do navegador do seu aplicativo. Embora este não seja o foco principal deste artigo, você pode configurar o rastreamento com algumas linhas extras na inicialização da biblioteca do Sentry:

npm install @sentry/tracing

import {Integrations} from "@sentry/tracing";
 
Sentry.init({
    dsn: "my-dsn",
    integrations: [new Integrations.BrowserTracing()],
    tracesSampleRate: 1.0
});

Agora, você poderá ver dados de desempenho em seu projeto Sentry. Isso pode ajudá-lo a identificar o código de execução lenta na produção.

Conclusão

O Sentry permite que você encontre e corrija erros antes que os usuários os reportem. Você pode receber alertas em tempo real conforme surgem problemas na produção. Os rastreamentos de pilha e os dados do navegador são exibidos em linha em cada problema, fornecendo um ponto de partida imediato para a resolução.

A combinação do Sentry com o GitLab fornece uma integração ainda mais estreita com o processo de desenvolvimento de software. Se você já estiver usando o GitLab para gerenciamento de projetos, adicionar a integração do Sentry permite gerenciar alertas no GitLab e criar problemas do GitLab para novos erros do Sentry.