Monitoramento de Elite: Rastreando Erros Críticos com Sentry

No mundo amador, quando um erro acontece em produção, o usuário envia um e-mail reclamando: "Apertei o botão e a tela ficou branca". O desenvolvedor abre o código e tenta adivinhar o que aconteceu com base no console.log.

Na nossa arquitetura de sistemas críticos, antes mesmo do usuário perceber que a tela travou, a equipe de engenharia já recebeu um alerta no Slack apontando exatamente qual foi o arquivo, a função e a linha de código que disparou a exceção. Esse é o poder do Sentry.

1. Por que o Sentry é Obrigatório?

Quando você faz o deploy (Build) do Next.js, o seu código TypeScript bonito e indentado é transformado em um código minificado ilegível para os navegadores. Se ocorrer um erro lá, o erro dirá algo como: TypeError: a.b is undefined at chunk-345.js:1:344.

O Sentry resolve isso armazenando os Source Maps do seu projeto durante o deploy. Quando o erro minificado chega, ele o "traduz" de volta para o código original, te mostrando: Erro ao buscar perfil do usuário em src/components/Profile.tsx na linha 42.

2. A Cobertura Full-Stack (O Padrão Híbrido)

Diferente de sistemas legados, nossa aplicação não roda em um só lugar. O erro pode ocorrer no navegador do usuário, na Vercel (Server Actions) ou no Supabase (Edge Functions).

O Sentry deve ser espetado em todos os tentáculos da arquitetura:

• Frontend (Navegador): Captura erros de React (Telas brancas, variáveis nulas, falhas de rede de terceiros).
• Backend (Next.js API / Server Actions): Captura falhas de conexão com o banco ou parâmetros inválidos bloqueados pelo Zod.
• Edge Functions (Deno): Captura falhas invisíveis em rotinas assíncronas (como um webhook da Stripe que falhou ao tentar atualizar a assinatura).

3. O Padrão de Tratamento de Erros

Ao escrever blocos try/catch de ações críticas do sistema, você nunca deve engolir o erro silenciosamente. A regra é proteger o usuário e dedurar a falha para a engenharia.

import * as Sentry from "@sentry/nextjs";

export async function processPayment(userId: string) {
  try {
    // Lógica pesada de pagamento...
    const result = await externalApi.charge(userId);
    return { success: true };
  } catch (error) {
    // 1. DEDURA A FALHA PARA O MONITORAMENTO
    Sentry.captureException(error, {
      tags: { service: "payment_gateway" },
      user: { id: userId }
    });

    // 2. PROTEGE O USUÁRIO (Graceful Degradation)
    return { 
      success: false, 
      message: "Ocorreu uma instabilidade na operadora, nossa equipe já foi notificada." 
    };
  }
}

[!TIP] Alerta de Sobrecarga: O Sentry não é um repositório de lixo. Não utilize Sentry.captureException para erros de validação comum (ex: usuário digitou senha errada ou CPF inválido). Guarde o Sentry exclusivamente para exceções de infraestrutura e bugs de código (Internal Server Errors 500).