Como usar o serviço de rastreamento de erros Sentry integrado do GitLab

O Sentry é uma plataforma popular de rastreamento de erros que oferece visibilidade em tempo real dos problemas em seus ambientes de produção. O recurso Error Reporting do GitLab permite trazer relatórios do Sentry para sua plataforma de controle de origem, oferecendo uma visão centralizada que unifica os erros do Sentry e os problemas do GitLab.

O recurso originalmente contava com uma integração com um serviço Sentry existente, seja o Sentry.io oficial ou seu próprio servidor auto-hospedado. Isso mudou com o GitLab 14.4, que adicionou um back-end leve compatível com Sentry ao próprio GitLab. Você não precisa mais de uma instalação real do Sentry para obter relatórios de erro no GitLab.

Veja como começar com o back-end Sentry integrado. Antes de prosseguirmos, vale a pena mencionar que esse recurso pode não ser adequado para você se já estiver familiarizado com o painel do Sentry. O back-end do GitLab é uma solução básica que apresenta erros como uma lista simples. É melhor para aplicativos menores onde você não deseja a sobrecarga de gerenciar um projeto Sentry separado.

Começando

Crie um novo projeto no GitLab.com ou em seu próprio servidor GitLab. Navegue até Configurações > Monitor na barra lateral do seu projeto e expanda a seção “Rastreamento de erros”. Ative a caixa de seleção em Ativar rastreamento de erros. Certifique-se de que o botão de opção Error tracking back-end esteja definido como GitLab. Pressione o botão azul Salvar alterações para continuar.

A página será recarregada. Agora você pode expandir a seção “Rastreamento de erros” novamente para revelar sua string DSN. Essa URL é usada para configurar sua biblioteca cliente Sentry para enviar eventos ao servidor GitLab.

Configurando o Cliente

Agora você pode adicionar o Sentry ao seu código. Aqui está um exemplo básico usando a biblioteca oficial do cliente Sentry para Node.js. Você pode instalar o pacote executando npm install @sentry/node. A documentação sobre todos os clientes disponíveis está disponível no Sentry.

const sentry = require("@sentry/node");
 
sentry.init({
    dsn: "https://glet_abc123@gitlab.example.com/api/v4/error_tracking/collector/1"
});

Substitua o valor DSN pela string que você copiou da IU do GitLab. A parte antes do @ é um token de autenticação especial que permite acesso ao servidor GitLab. O restante consiste no ponto de extremidade de API de ingestão de rastreamento de erro exclusivo para seu projeto.

Testando sua integração

As bibliotecas oficiais do cliente Sentry começam a capturar erros não tratados assim que são configuradas com um DSN. Se algum código a seguir lançar um erro que você não detectou, o evento será relatado ao seu servidor GitLab.

Você pode testar a integração capturando eventos manualmente. Aqui está um exemplo que cria e reporta uma instância Error:

Sentry.captureException(new Error("Sentry test"));

Use a barra lateral do seu projeto na interface do usuário da Web do GitLab para navegar até a página Monitor > Error Tracking. O erro que você capturou deve aparecer na lista. Clique em sua entrada para visualizar o relatório completo e o rastreamento de pilha.

Os problemas do GitLab podem ser criados a partir de relatórios usando o botão azul Criar problema no canto superior direito. Isso permite que você atribua o trabalho de correção aos membros da equipe e inicie uma discussão sobre o problema. O problema manterá um link para o relatório de erros e o rastreamento de pilha será exibido abaixo da descrição do problema.

Depois de corrigir um problema, use a página Rastreamento de erros para marcá-lo como resolvido. Os problemas também podem ser ignorados se você não pretende remediá-los, talvez porque foram transitórios ou registrados por um cliente desatualizado.

Limitações

O back-end Sentry integrado do GitLab é atualmente destinado a situações de pequena escala em que a implantação do Sentry é vista como muito complexa ou desnecessária. A plataforma Sentry completa é um sistema amplo que pode levar tempo para configurar e manter. A integração do GitLab é uma única caixa de seleção nas configurações do seu projeto, mas essa simplicidade tem um custo.

A lista de Rastreamento de Erros é sua única visualização nos relatórios. No momento, você não pode grafá-los, visualizar alterações nos volumes de relatórios ao longo do tempo ou filtrar por usuários ou clientes individuais. Informações detalhadas mostradas pela interface do usuário do Sentry, como dados do navegador e do servidor, não são suportadas ou exibidas em nenhum lugar do GitLab.

Você também deve estar ciente de que o GitLab ainda não pode enviar e-mails para novos relatórios de erros. Você deve monitorar manualmente a página Error Tracking para ficar à frente dos eventos gerados por suas implantações.

Como o GitLab implementa os principais recursos da Sentry API, ele é compatível com a maioria dos principais SDKs e bibliotecas de clientes. A partir do GitLab 14.5, está confirmado que funciona com Ruby, JavaScript, Java e Python; outros idiomas têm suporte parcial ou serão adicionados em versões futuras do GitLab.

Resumo

O back-end Sentry do GitLab fornece uma maneira simples de capturar relatórios de erros de seu aplicativo e armazená-los junto com seu código. Embora suas limitações atuais o tornem inadequado para todos, exceto para os casos de uso mais simples, ainda é uma opção atraente para sites menores e projetos pessoais que não precisam da complexidade de um serviço Sentry completo.

O back-end integrado também pode ser útil ao testar a integração do Sentry com seu código. Se você estiver configurando um novo cliente ou modificando as configurações de um existente, poderá usar seu servidor GitLab como um back-end temporário para não poluir sua implantação principal do Sentry.