Capturar erros de aplicação

O Farol recebe eventos de erro pelo protocolo dos SDKs do Sentry. Para começar, você precisa do serviço cadastrado e de um DSN emitido para ele.

Obtenha o DSN

Cadastre o serviço e o ambiente no Farol e emita a credencial de erros vinculada ao serviço, com o escopo DATA_PLANE_ERRORS. Copie o DSN exibido no momento da emissão.

Configure o DSN completo, incluindo host, chave e projeto, como SENTRY_DSN no ambiente da aplicação. Não monte esse endereço manualmente nem use uma credencial app_ no lugar da chave do DSN.

Exemplo: Node.js no servidor

O exemplo usa a versão 10.13.0 do SDK, presente na verificação de compatibilidade do Farol. Avalie atualizações do SDK junto com o build e a validação da sua aplicação.

npm install --save-exact @sentry/node@10.13.0

Inicialize o SDK antes do código que deseja observar:

import * as Sentry from '@sentry/node';

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

Use APP_ENV com o slug cadastrado, como production, e APP_VERSION com a versão do deploy. Em uma captura manual:

try {
  throw new Error('Teste controlado de integração com o Farol');
} catch (error) {
  Sentry.captureException(error);
}

// Em scripts curtos, espere o envio antes de encerrar o processo.
await Sentry.flush(5000);

Faça esse teste em um ambiente autorizado e retire o erro intencional depois da validação. Um processo encerrado imediatamente pode terminar antes de o SDK enviar o evento.

Confirme a issue

Abra Erros no Farol e filtre pelo serviço, ambiente e período recente. Confira a mensagem, a stack quando enviada e a versão da aplicação. Ocorrências podem ser agrupadas na mesma issue.

Se estiver usando OpenTelemetry, compare o trace_id do erro com o da requisição. Não crie dois providers OpenTelemetry para tentar obter essa correlação; veja o guia de traces.

Escopo desta integração

Esta integração trata de erros de aplicações no servidor. A compatibilidade com eventos de erro não significa suporte a todas as funcionalidades do Sentry: performance do Sentry, replay de sessão, profiling e anexos não fazem parte deste guia.

O exemplo Node.js não configura captura no navegador ou no runtime Edge. Para Next.js e Spring Boot, a inicialização depende da stack; preserve uma única configuração do OpenTelemetry quando combinar traces e erros.

Evite enviar segredos e dados pessoais nos eventos mesmo quando há redação no servidor. Se o erro não aparecer, confira o DSN, o escopo, a saída HTTPS e o tempo de envio do SDK.