Sentry no Node.js: Guia Prático

Integrar Sentry no Node.js permite capturar exceções, falhas de Promise, traces, perfis e contexto de requisições em uma plataforma de monitoramento de erros. Em vez de procurar uma stack isolada em milhares de linhas de log, a equipe recebe agrupamento por problema, versão afetada, ambiente, frequência e usuários impactados.

A integração precisa ocorrer cedo no processo para instrumentar módulos carregados durante a inicialização. Também exige filtros de dados, definição de release, amostragem e flush no shutdown. Sem esses cuidados, eventos podem conter credenciais, gerar custo excessivo ou não ser enviados antes do processo terminar.

Neste guia, você aprenderá a inicializar o SDK, capturar exceções, adicionar contexto, proteger dados, integrar com Express, usar traces, releases, source maps, sampling, alertas, testes e graceful shutdown.

O que é Sentry?

Sentry é uma plataforma de observabilidade focada em erros e desempenho. A documentação oficial do Sentry para Node.js apresenta instalação e integrações. A documentação de opções do SDK descreve DSN, ambiente, release e filtros.

Para logs estruturados, consulte Logs com Pino no Node.js. Para tracing aberto, veja OpenTelemetry no Node.js.

Instalando

npm install @sentry/node

Recursos adicionais, como profiling, podem exigir pacotes e configuração compatíveis com a versão do SDK.

Inicialização

const Sentry = require('@sentry/node');

Sentry.init({
  dsn: process.env.SENTRY_DSN,
  environment: process.env.NODE_ENV,
  release: process.env.APP_VERSION,
  sendDefaultPii: false
});

Inicialize antes de carregar frameworks e bibliotecas que precisam ser instrumentados, conforme a orientação da versão do SDK.

Arquivo de instrumentação

Uma estrutura comum separa:

// instrument.cjs
const Sentry = require('@sentry/node');

Sentry.init({
  dsn: process.env.SENTRY_DSN,
  environment: process.env.NODE_ENV,
  release: process.env.APP_VERSION
});

Depois, carregue esse arquivo antes da aplicação, usando a estratégia recomendada para CommonJS ou ES Modules.

DSN

O DSN identifica o projeto de destino. Ele não deve ser tratado como senha equivalente a uma chave privada, mas deve ser gerenciado por configuração e não fixado no código.

Consulte Variáveis de Ambiente no Node.js.

Capturando uma exceção

try {
  await processOrder(order);
} catch (error) {
  Sentry.captureException(error);
  throw error;
}

Não capture e silencie sem necessidade. A camada de tratamento HTTP pode registrar e responder de forma consistente.

Capturando mensagem

Sentry.captureMessage(
  'Fila próxima do limite',
  'warning'
);

Use para situações relevantes que não possuem objeto Error. Métricas são melhores para condições frequentes.

Escopo e contexto

Sentry.withScope(scope => {
  scope.setTag('operation', 'create-order');
  scope.setContext('order', {
    id: order.id,
    channel: order.channel
  });

  Sentry.captureException(error);
});

O contexto deve conter IDs e categorias úteis, não o objeto inteiro.

Tags

Tags são indexadas e usadas em filtros. Escolha valores com cardinalidade controlada:

• serviço;
• ambiente;
• rota normalizada;
• tipo de operação;
• provedor;
• feature flag.

Não use requestId ou orderId como tag de alta cardinalidade; coloque-os como contexto quando necessário.

User

Sentry.setUser({
  id: String(user.id)
});

Evite e-mail, IP e nome se não forem necessários. Respeite política de privacidade e retenção.

Limpando usuário

Sentry.setUser(null);

Em processos longos, não mantenha contexto global de um usuário para outra requisição.

Isolamento por requisição

Use integrações do framework e escopos isolados. Contexto global em aplicações concorrentes pode misturar dados entre requisições.

Express

A integração exata varia conforme a versão do SDK. Em geral, inicialize cedo, adicione instrumentação e instale o handler de erro na posição recomendada.

app.get('/api/orders/:id', async (req, res) => {
  const order = await repository.find(req.params.id);
  res.json(order);
});

// handler da aplicação e integração do Sentry

Consulte a documentação da versão para middleware e setup atuais.

Erro centralizado

app.use((error, req, res, next) => {
  Sentry.captureException(error);

  res.status(500).json({
    code: 'INTERNAL_ERROR',
    message: 'Erro interno'
  });
});

Não retorne event ID, stack ou mensagem interna sem uma razão de suporte bem definida.

Veja Express 5: Erros Assíncronos.

Unhandled rejection

O SDK pode capturar falhas não tratadas, mas a aplicação precisa ter política de shutdown. Uma Promise rejeitada sem captura pode indicar estado inconsistente.

Uncaught exception

Capture, faça flush e encerre:

process.on('uncaughtException', async error => {
  Sentry.captureException(error);
  await Sentry.flush(2000);
  process.exitCode = 1;
});

Evite continuar atendendo após uma exceção não capturada.

Flush

await Sentry.flush(2000);

O método aguarda eventos pendentes até o timeout. Não use prazo infinito durante shutdown.

Close

close() pode desabilitar o cliente após enviar pendências. Use quando o processo realmente está terminando.

Graceful shutdown

Feche servidor, banco e filas antes do flush final. Consulte Graceful Shutdown no Node.js.

Release

release: 'orders-api@1.8.0'

Release permite identificar quando o erro começou e acompanhar regressões. Use o mesmo identificador no deploy e nos source maps.

Dist

Quando uma release possui artefatos diferentes, dist ajuda a distingui-los. Mantenha o valor estável e documentado.

Environment

Separe development, staging e production. Não misture eventos de testes locais com alertas de produção.

Source maps

Aplicações TypeScript ou bundled precisam enviar source maps para traduzir stacks compiladas. Os arquivos devem corresponder exatamente à release e ao artefato.

Não publique source maps abertos

Faça upload para a plataforma e evite servi-los publicamente quando contêm código fonte sensível.

TypeScript

Configure sourceMap e, quando adequado, hiddenSourceMap. Teste uma exceção após o deploy e confirme a linha original.

Tracing

Sentry.init({
  dsn,
  tracesSampleRate: 0.1
});

O valor representa uma fração dos traces. Taxa 1.0 pode gerar alto volume em produção.

Traces sampler

tracesSampler(context) {
  if (context.name?.startsWith('GET /health')) {
    return 0;
  }

  if (context.name?.startsWith('POST /payments')) {
    return 0.5;
  }

  return 0.05;
}

Use regras estáveis e não baseadas em dados pessoais.

Health checks

Exclua rotas frequentes para reduzir custo e ruído. Consulte Health Checks no Node.js.

Profiling

Profiling pode adicionar custo e coletar mais detalhes. Ative com amostragem baixa e valide impacto no ambiente real.

beforeSend

beforeSend(event) {
  if (event.request?.headers) {
    delete event.request.headers.authorization;
    delete event.request.headers.cookie;
  }

  return event;
}

Retornar null descarta o evento.

beforeSendTransaction

Permite filtrar ou modificar transações. Use para remover rotas de probes e métricas.

Dados pessoais

Revise:

• headers;
• cookies;
• query strings;
• corpos;
• IP;
• e-mail;
• nomes;
• variáveis locais.

Desabilite coleta que não possui finalidade legítima.

sendDefaultPii

Ativar essa opção pode incluir informações identificáveis. Mantenha false por padrão e só altere após revisão jurídica e técnica.

Ignore errors

É possível ignorar padrões conhecidos, mas filtros por texto são frágeis. Prefira corrigir a origem ou filtrar por tipo e contexto controlado.

Erro esperado

Validação de usuário e 404 não precisam virar issue. Capture falhas inesperadas, indisponibilidade e invariantes quebradas.

Fingerprint

Fingerprint customizado altera agrupamento. Use com cuidado: um valor amplo mistura causas diferentes; um valor muito específico cria milhares de issues.

Breadcrumbs

Sentry.addBreadcrumb({
  category: 'order',
  message: 'Reserva criada',
  level: 'info',
  data: {
    orderId: order.id
  }
});

Breadcrumbs ajudam a reconstruir passos anteriores. Não inclua payloads completos.

Integração com logs

Inclua o event ID no log:

const eventId = Sentry.captureException(error);
logger.error({ err: error, sentryEventId: eventId });

Isso permite navegar entre log e issue.

Métricas

Sentry complementa Prometheus. Prometheus alerta pela taxa de erros; Sentry agrupa stacks e versões. Consulte Métricas Prometheus no Node.js.

OpenTelemetry

Se usar Sentry e OpenTelemetry, evite instrumentação duplicada e confirme propagação de contexto. Defina qual plataforma é fonte principal de traces.

Alertas

Crie alertas para:

• nova issue em produção;
• regressão;
• crescimento rápido;
• erro em rota crítica;
• release recém-implantada;
• usuários afetados acima de limite.

Não notifique a equipe por cada ocorrência individual.

Ownership

Associe módulos ou caminhos a equipes. Uma issue sem responsável tende a permanecer aberta.

Deploy tracking

Registre deploys para correlacionar aumento de falhas com uma versão. Automatize no pipeline.

Kubernetes

Defina release e ambiente por ConfigMap, mas DSN e tokens de upload devem vir de Secret. Consulte ConfigMaps e Secrets no Node.js.

Offline e falhas de rede

A aplicação não deve falhar porque o Sentry está indisponível. O transporte deve descartar ou limitar pendências sem bloquear requisições.

Timeout

Envio de telemetria precisa de prazo. Em encerramento fatal, prefira perder um evento a manter o processo indefinidamente.

Ambiente local

Você pode desabilitar o SDK sem DSN:

enabled: Boolean(process.env.SENTRY_DSN)

Ou enviar para um projeto separado de desenvolvimento.

Testes

Cubra:

• captura de exceção;
• release e environment;
• redaction de authorization;
• erro esperado ignorado;
• request context isolado;
• source map;
• sampling;
• flush;
• falha de transporte;
• shutdown fatal.

Transport de teste

Use transporte customizado ou mock do SDK para verificar o evento sem enviar para a internet.

Teste de privacidade

test('remove Authorization', () => {
  const event = applyBeforeSend({
    request: {
      headers: {
        authorization: 'Bearer secret'
      }
    }
  });

  assert.equal(
    event.request.headers.authorization,
    undefined
  );
});

Erros comuns

• Inicializar tarde: integrações não instrumentam módulos.
• Release ausente: regressões ficam difíceis de identificar.
• Sample rate 100%: custo aumenta.
• Enviar PII: ocorre risco de privacidade.
• Capturar 404: issues ficam ruidosas.
• Sem flush: eventos fatais são perdidos.
• Source map errado: stacks apontam linhas incorretas.

Boas práticas

• Inicialize cedo.
• Defina release e environment.
• Mantenha sendDefaultPii desativado.
• Use beforeSend.
• Amostre traces.
• Exclua health checks.
• Envie source maps correspondentes.
• Correlacione com logs.
• Faça flush no shutdown.
• Teste privacidade e transporte.

Conclusão

Integrar Sentry no Node.js centraliza exceções, stacks, releases e contexto operacional. O agrupamento transforma ocorrências repetidas em problemas rastreáveis e ajuda a identificar regressões após deploys.

O valor depende da qualidade dos dados. Inicialização precoce, release correta, sampling, redaction e source maps confiáveis evitam ruído e vazamentos. Com alertas por impacto e correlação com logs e métricas, Sentry acelera diagnóstico sem substituir as demais camadas de observabilidade.