Sentry: Monitoramento de Erros e Performance para Aplicações Modernas

O Problema do Debug no Escuro

Você já recebeu a mensagem “O sistema está dando erro” de um cliente e precisou passar horas tentando reproduzir o problema? Em aplicações modernas distribuídas em múltiplos ambientes — navegadores, dispositivos móveis, servidores, edge computing — descobrir o que quebrou, onde quebrou e por que quebrou é um dos maiores desafios do desenvolvimento de software.

O Sentry resolve exatamente esse problema. Ele é uma plataforma open-source de Application Performance Monitoring (APM) e Error Tracking que captura exceções em tempo real, fornece stack traces completos com contexto do ambiente e rastreia o desempenho de transações para identificar gargalos. Tudo integrado em um único dashboard.

O que é o Sentry?

Fundado em 2012 por David Cramer, o Sentry começou como uma ferramenta de rastreamento de erros para Python e Django e evoluiu para uma plataforma completa de observabilidade que suporta mais de 90 linguagens e frameworks. Hoje é utilizado por milhões de desenvolvedores e empresas como Microsoft, Airbnb, Stripe, Reddit e Disney.

Suas principais funcionalidades incluem:

• Captura automática de exceções: erros não tratados são capturados automaticamente sem alteração no código
• Source Maps e Proguard: desofuscação de código minificado para JavaScript e Android
• Performance Tracing: rastreamento distribuído de transações com spans detalhados
• Release Tracking: associe erros a versões específicas do seu software
• Alertas Inteligentes: notificações baseadas em frequência, volume e regras personalizadas
• Breadcrumbs: histórico de eventos que levaram ao erro, como requisições HTTP, cliques e logs
• Integrações nativas: GitHub, GitLab, Bitbucket, Slack, Jira, PagerDuty, Datadog e mais

Arquitetura do Sentry

O Sentry pode operar de duas formas:

• Sentry SaaS (sentry.io): versão gerenciada com todos os recursos, sem necessidade de infraestrutura própria
• Sentry Self-Hosted: instalação on-premises via Docker, ideal para empresas com requisitos de conformidade e privacidade de dados

A arquitetura consiste em três componentes principais:

# Componentes da arquitetura Sentry
#
# 1. SDK (Client-side)
#    Bibliotecas leves instaladas na aplicação que capturam
#    erros e métricas de performance automaticamente
#
# 2. Relay (Proxy)
#    Servidor intermediário que recebe eventos dos SDKs,
#    faz buffer, normalização e envio ao servidor central
#    (Essencial para altos volumes e ambientes offline)
#
# 3. Backend (Sentry Service)
#    Processa, agrega, armazena e indexa eventos.
#    Inclui: ingestão, processamento, armazenamento ClickHouse,
#    busca simbólica e painel web

O Sentry utiliza armazenamento em ClickHouse para dados de eventos, PostgreSQL para metadados e Redis para cache e filas, garantindo desempenho mesmo em escala de milhões de eventos por minuto.

Instalação e Configuração

Criando uma Conta e um Projeto

O primeiro passo é criar uma conta em sentry.io e configurar um novo projeto. O Sentry oferece SDKs específicos para cada plataforma:

• JavaScript: React, Vue, Angular, Next.js, Node.js, Express
• Python: Django, Flask, FastAPI, Celery
• Mobile: iOS (Swift/ObjC), Android (Kotlin/Java), React Native, Flutter
• Backend: Ruby, PHP (Laravel), Go, Java, .NET, Rust

Integração com Node.js (Express)

// 1. Instalar o SDK
// npm install @sentry/node @sentry/profiling-node

const Sentry = require('@sentry/node');
const { nodeProfilingIntegration } = require('@sentry/profiling-node');
const express = require('express');

const app = express();

// 2. Inicializar o Sentry logo no início da aplicação
Sentry.init({
  dsn: 'https://seu-dsn@sentry.io/1234567',
  environment: process.env.NODE_ENV || 'development',
  release: 'api@1.0.0',
  integrations: [
    nodeProfilingIntegration(),
  ],
  // 3. Capturar 100% das transações em produção
  tracesSampleRate: 1.0,
  profilesSampleRate: 1.0,
});

// 4. Middleware do Sentry deve vir ANTES das rotas
app.use(Sentry.Handlers.requestHandler());
app.use(Sentry.Handlers.tracingHandler());

app.get('/api/usuarios', async (req, res) => {
  // Erro intencional para demonstração
  throw new Error('Erro de teste - usuários não encontrados');
});

// 5. Middleware de tratamento de erros (DEVE vir depois das rotas)
app.use(Sentry.Handlers.errorHandler());

app.listen(3000, () => {
  console.log('Servidor rodando na porta 3000');
});

Integração com React (Frontend)

// 1. Instalar o SDK
// npm install @sentry/react @sentry/tracing

import React from 'react';
import * as Sentry from '@sentry/react';
import { BrowserTracing } from '@sentry/tracing';
import { createRoot } from 'react-dom/client';

// 2. Inicializar antes de renderizar a aplicação
Sentry.init({
  dsn: 'https://seu-dsn@sentry.io/1234567',
  integrations: [
    new BrowserTracing({
      tracePropagationTargets: ['localhost', /^https:\/\/api\.meudominio\.com/],
    }),
  ],
  // 3. Amostragem: 20% das transações em produção
  tracesSampleRate: 0.2,
  // 4. Capturar apenas erros reais, não erros de extensões
  allowUrls: ['https://app.meudominio.com'],
  // 5. Habilitar replay de sessão para erros críticos
  replaysSessionSampleRate: 0.1,
  replaysOnErrorSampleRate: 1.0,
});

// 6. Envolver o componente raiz com ErrorBoundary
const AppRoot = () => (
  <Sentry.ErrorBoundary
    fallback={({ error, componentStack }) => (
      <div>
        <h1>Ops! Algo deu errado</h1>
        <p>Nossa equipe já foi notificada.</p>
      </div>
    )}
  >
    <App />
  </Sentry.ErrorBoundary>
);

createRoot(document.getElementById('root')).render(<AppRoot />);

Captura de Erros Avançada

Além da captura automática, o Sentry permite que você capture erros manualmente com contexto rico:

Captura Manual com Contexto

// Python: captura manual de exceção
from sentry_sdk import capture_exception, push_scope
import sentry_sdk

try:
    resultado = servico.externo.executar_operacao()
    return resultado
except Exception as e:
    with push_scope() as scope:
        scope.set_tag("servico_externo", "api-pagamentos")
        scope.set_tag("operacao", "cobranca_recorrente")
        scope.set_level("error")
        scope.set_extra("usuario_id", usuario.id)
        scope.set_extra("tentativas", 3)
        capture_exception(e)
    raise

Mensagens com Contexto

// JavaScript: mensagem com contexto
Sentry.withScope((scope) => {
  scope.setTag("database", "postgresql");
  scope.setLevel("warning");
  scope.setExtra("query_time_ms", 12500);
  Sentry.captureMessage("Query lenta detectada", "warning");
});

Performance Monitoring: Rastreamento Distribuído

O recurso de Performance Monitoring do Sentry permite rastrear transações completas — desde a requisição inicial no frontend até as chamadas de banco de dados no backend:

// Python: transação personalizada com spans
import sentry_sdk
from sentry_sdk import start_transaction
from sentry_sdk.tracing import Span

with start_transaction(
    op="task",
    name="processar_pedido",
    tags={"pedido_id": "ORD-12345", "canal": "web"}
) as transaction:
    # Span 1: validar estoque
    with Span(op="db.query", description="verificar_estoque") as span:
        span.set_tag("produto_sku", "SKU-42069")
        estoque = banco.verificar_estoque("SKU-42069")

    # Span 2: processar pagamento
    with Span(op="http.client", description="cobrar_cartao") as span:
        span.set_tag("gateway", "stripe")
        pagamento = gateway.cobrar(299.90)

    # Span 3: atualizar banco
    with Span(op="db.write", description="atualizar_pedido") as span:
        pedido = banco.atualizar_status("ORD-12345", "confirmado")

print(f"Pedido {pedido.id} processado em {transaction.timestamp}s")

Com o rastreamento distribuído, você pode visualizar no dashboard do Sentry exatamente quanto tempo cada operação levou e identificar qual serviço está causando lentidão.

Release Tracking e Source Maps

Uma das funcionalidades mais importantes para desenvolvimento web moderno é a integração com Source Maps. Código JavaScript minificado (React, Vue, Angular em produção) gera stack traces ilegíveis. O Sentry desofusca automaticamente:

# Exemplo de configuração com Webpack/Vite
# sentry.yml (arquivo de configuração CLI)
org: minha-org
project: meu-projeto
auth_token: sntrys_YOUR_TOKEN_HERE

# Comando para criar release e enviar source maps:
sentry-cli releases new api@1.0.0
sentry-cli releases files api@1.0.0 \
  upload-sourcemaps ./dist/assets/ \
  --url-prefix '~/assets/' \
  --validate
sentry-cli releases set-commits \
  api@1.0.0 --auto
sentry-cli releases finalize api@1.0.0

Com isso, no dashboard do Sentry você vê o código original (TypeScript/JSX), não o código minificado, facilitando a depuração.

Alertas Inteligentes e Regras

O Sentry oferece um sistema de alertas configurável que evita o cansaço de notificações (alert fatigue):

• Alertas por frequência: notifique quando um erro ocorre mais de X vezes em Y minutos
• Alertas por usuário afetado: notifique quando mais de N usuários únicos são impactados
• Alertas por nova edição: notifique na primeira ocorrência de um novo erro
• Escalonamento: integração com PagerDuty/Opsgenie para incidentes críticos
• Regras de supressão: ignore erros conhecidos ou em ambientes de desenvolvimento

# Exemplo de regra de alerta (via API)
# Disparar quando:
#   - Evento é 'error' level
#   - Tag 'ambiente' = 'producao'
#   - Frequência > 100 ocorrências em 15 minutos
# Notificar: Slack (#ops-alerts) + PagerDuty

Self-Hosted: Instalação com Docker

Para empresas que precisam manter os dados internamente, o Sentry oferece instalação self-hosted via Docker Compose:

# Pré-requisitos: Docker, Docker Compose, Git

# Clonar o repositório oficial de instalação
git clone https://github.com/getsentry/self-hosted.git
cd self-hosted

# Instalar (baixa imagens, configura banco, cria admin)
sudo ./install.sh

# Iniciar todos os serviços
docker compose up -d

# Acessar: http://localhost:9000
# Login: admin@exemplo.com / senha definida na instalação

# Serviços iniciados:
# - Sentry Web (porta 9000)
# - ClickHouse (armazenamento de eventos)
# - PostgreSQL (metadados)
# - Redis (cache/fila)
# - Kafka (mensageria interna)
# - Relay (proxy de ingestão, porta 3000)
# - Workers (processamento assíncrono)

Requisitos mínimos para self-hosted: 4 vCPUs, 8 GB RAM, 50 GB de disco SSD. Para produção, recomenda-se 8 vCPUs, 32 GB RAM e armazenamento dimensionado conforme volume de eventos (cerca de 1 KB por evento).

Integração com CI/CD e Git

Uma prática recomendada é associar cada release a commits do git. Isso permite que o Sentry mostre exatamente qual commit introduziu um bug:

# Adicionar ao pipeline do GitHub Actions
- name: Criar release no Sentry
  run: |
    npm install -g @sentry/cli
    sentry-cli releases new ${{ github.sha }}
    sentry-cli releases set-commits \
      ${{ github.sha }} --auto
    sentry-cli releases finalize \
      ${{ github.sha }}
  env:
    SENTRY_AUTH_TOKEN: ${{ secrets.SENTRY_AUTH_TOKEN }}
    SENTRY_ORG: minha-org
    SENTRY_PROJECT: meu-projeto

Com essa integração, cada erro no Sentry exibe: “Introduzido no commit abc1234 por usuário@exemplo.com” — permitindo responsabilização rápida e correção direcionada.

Session Replay: Veja o Erro Acontecer

Um dos recursos mais impactantes do Sentry é o Session Replay. Ele grava a interação do usuário (cliques, navegação, inputs) nos segundos anteriores a um erro, permitindo que você veja exatamente o que o usuário fez antes da falha:

// Habilitar no init do frontend
Sentry.init({
  dsn: '...',
  // Replay em 10% das sessões normais
  replaysSessionSampleRate: 0.1,
  // Replay em 100% das sessões com erro
  replaysOnErrorSampleRate: 1.0,
});

// Iniciar replay manualmente
import { Replay } from '@sentry/replay';
const replay = new Replay();
replay.start();

O replay é gravado no próprio navegador do usuário e incluído no evento de erro — sem expor dados sensíveis (campos de senha e cartão de crédito são automaticamente mascarados).

Boas Práticas

• Defina níveis de severidade: use fatal para falhas catastróficas, error para exceções, warning para comportamentos inesperados não críticos
• Configure amostragem adequada: em produção com alto tráfego, use tracesSampleRate: 0.1 (10%) para performance tracing e 100% para captura de erros
• Use tags para filtrar: adicione tags como ambiente, versao, regiao, usuario_plano para segmentar erros
• Ignore erros esperados: configure filtros no dashboard para ignorar erros de bots, extensões de navegador ou erros já conhecidos em tratamento
• Não capture dados sensíveis: configure beforeSend para remover credenciais, tokens e informações PII antes do envio
• Mantenha o SDK atualizado: novas versões trazem melhorias de performance, novos recursos e correções de segurança
• Acompanhe tendências: use o dashboard de “Events” para identificar picos de erro após deploys

Sentry vs. Alternativas

• vs. Datadog APM: Datadog é mais completo em infraestrutura, mas Sentry é muito mais focado em erros de código e experiência do desenvolvedor. Sentry tem melhor integração com source maps e stack traces.
• vs. New Relic: New Relic é excelente para monitoramento de infraestrutura; Sentry brilha na captura e organização de exceções com contexto rico de release e commit.
• vs. Rollbar: Ambos focam em error tracking. Sentry oferece Session Replay e Performance Monitoring integrados que Rollbar não tem.
• vs. OpenTelemetry (OTel): OTel é um padrão aberto de observabilidade; Sentry é uma plataforma pronta para uso que consome dados OTel nativamente.

Conclusão

O Sentry se consolidou como a ferramenta padrão de mercado para monitoramento de erros e performance em aplicações modernas. Sua combinação de captura automática de exceções, rastreamento distribuído de performance, source maps, release tracking e session replay oferece ao desenvolvedor tudo o que precisa para entender e corrigir problemas de forma rápida e eficiente.

Seja você um desenvolvedor individual trabalhando em um projeto pessoal ou uma equipe de centenas de engenheiros em uma grande empresa, o Sentry escala conforme sua necessidade — desde o plano gratuito (5 mil eventos/mês) até planos enterprise com SLAs, conformidade SOC 2 e suporte dedicado.

Integre o Sentry no seu próximo deploy e nunca mais debugue no escuro.