Sentinela

Documentação de integração

Conceitos em 60 segundos

  • DSN: endereço público do seu projeto. Só permite ENVIAR eventos — é seguro expor no frontend.
  • Loader: script de ~1,5 KB que baixa o SDK real do CDN em runtime. É a única coisa "congelada" no seu build.
  • Config remota: campos do widget, setores, anexos, branding e sampling — editados no dashboard e aplicados em ~60s, sem redeploy.
  • Token secreto: só no CI/CD (releases, sourcemaps) e em backends. NUNCA no frontend.

Primeiros passos

A instalação leva cerca de 5 minutos e acontece inteira no frontend: um script no HTML e (recomendado) uma chamada após o login. Nada muda no seu backend.

Como o Sentinela se organiza

Sua organização (sua conta)
 └── Cliente   — para quem você mantém o sistema (contrato, SLA, relatório)
      └── Projeto — UM por sistema entregue; é o dono das chaves

Cada projeto nasce com suas próprias chaves, geradas automaticamente — você nunca monta chave ou URL à mão:

  • public_key — identifica o projeto no snippet. Pública: pode ficar no HTML.
  • project_id — o identificador do projeto; junto com a public_key compõe o DSN.
  • token secreto — só para o CI/CD (releases, sourcemaps) e backends. Nunca no frontend.

Passo a passo

  1. Crie sua conta. O Sentinela cria junto a sua organização, um cliente inicial e o seu primeiro projeto — vazio, com chaves reais, pronto para receber eventos. Ele não é descartável: use-o para o primeiro sistema que você quer monitorar.
  2. Copie o snippet. Logo após o cadastro, o onboarding mostra o snippet do projeto — a public_key já vem embutida — com um botão Copiar. A qualquer momento depois, ele está em Clientes → clique no projeto: o painel de chaves traz snippet, public_key, project_id e DSN.
  3. Cole antes do </head> do template base do seu sistema e publique. Isso já é a instalação completa: captura de erros, heartbeat e o widget de chamados (se habilitado) passam a funcionar.
  4. Identifique o usuário (recomendado): chame Sentinela.setUser({ id, email }) após o login e Sentinela.setUser(null) no logout — ver a seção abaixo. Sem isso, erros e chamados entram anônimos.
  5. Confirme. Abra o seu sistema com o snippet publicado: quando o primeiro evento chegar, o onboarding confirma na hora.

O que você NÃO precisa

  • Mexer no backend. O snippet no frontend é a instalação completa. CI/CD (sourcemaps) e o SDK de backend são recursos opcionais, para depois.
  • Ter domínio próprio. Funciona em qualquer página que carregue o script, inclusive localhost durante o desenvolvimento. Para restringir quem pode enviar eventos, cadastre as origens permitidas do projeto (opcional); em branco, aceita de qualquer origem.
  • Montar chaves ou URLs. Snippet e DSN saem prontos do painel.

Um sistema = um projeto. Não reaproveite a mesma public_key em dois sistemas: issues, chamados e relatórios são separados por projeto. Para o próximo sistema, vá em Clientes: cadastre o cliente (se novo), clique em + Novo projeto e copie o snippet — o projeto nasce com chaves próprias, e o token secreto aparece apenas nessa hora (guarde-o se for usar CI/CD). Lá também ficam as origens permitidas e a rotação de chaves.

Instalação rápida (frontend)

Opção A — script tag (recomendada): cole antes do </head>. Zero build, auto-atualizável.

<script async src="https://cdn.SEU_DOMINIO/loader/v1/SEU_PUBLIC_KEY.js"></script>

Opção B — npm (para quem prefere gestão de dependência):

import { load } from '@sentinela/loader';

load({
  dsn: 'https://[email protected]_DOMINIO/PROJECT_ID',
  environment: import.meta.env.MODE ?? 'production',
  release: __APP_VERSION__, // ver Releases & sourcemaps
});

O pacote npm contém APENAS o loader — o SDK real continua vindo do CDN e se atualizando sozinho. Você não precisa atualizar o pacote para receber novidades (só em major novo).

Identificando o usuário

Chame após o login (e a cada restauração de sessão); habilita o e-mail travado no widget:

Sentinela.setUser({ id: usuario.id, email: usuario.email });
// no logout:
Sentinela.setUser(null);

Pode chamar Sentinela.* ANTES de o SDK carregar: o loader enfileira e executa depois (stub queue). Nenhuma chamada se perde.