Capture automaticamente erros de JavaScript em todo o seu site com contexto detalhado para depuração mais rápida.
Habilitando rastreamento de erros
O rastreamento de erros captura automaticamente erros de JavaScript não detectados e rejeições de promessas não tratadas assim que está ativado para um site. É parte do mesmo script de rastreamento que você já instalou:
<script
defer
data-tracking-code="YOUR_TRACKING_CODE"
src="https://api.zenovay.com/z.js"
></script>
Ativação
O rastreamento de erros é controlado por uma flag de recurso em cada site:
- Abra o painel do seu site e vá para Configurações → Avançado
- Sob Sinalizadores de Recurso, ative Rastreamento de Erros
Pronto. Não há alterações de script a fazer, a flag é entregue ao rastreador automaticamente. Novos erros começam a aparecer na aba Erros.
Informação
O rastreamento de erros é um recurso Pro. Se o botão mostrar um crachá de plano obrigatório, você precisará estar no Pro, Scale ou Enterprise para habilitá-lo.
O que é capturado
Informações de erro
Para cada erro, o Zenovay captura:
| Dados | Descrição |
|---|---|
| Mensagem de erro | A descrição do erro |
| Tipo de erro | TypeError, ReferenceError, etc. |
| Rastreamento de pilha | Pilha de chamadas completa |
| Arquivo de origem | Arquivo onde o erro ocorreu |
| Linha e coluna | Posição exata |
| URL | Página onde o erro ocorreu |
| Agente do usuário | Navegador e sistema operacional |
| ID do visitante | Link para sessão |
| Timestamp | Quando o erro ocorreu |
Dados contextuais
Contexto adicional capturado com cada erro:
- URL da página e referente
- Informações do navegador e dispositivo
- Breadcrumbs: navegação recente, cliques, saída do console e solicitações de rede que levaram ao erro
- A versão e o ambiente no qual o erro foi reportado (se seu código os definir)
Visualizando erros
Painel de erros
Abra o painel do seu site e selecione a aba Erros (sob Confiabilidade na barra lateral):
- Veja tendências de contagem de erros ao longo do tempo
- Visualize grupos de erros principais por ocorrência
- Filtre por status
- Clique em qualquer grupo de erros para obter detalhes
Lista de erros
A lista de erros mostra:
| Coluna | Descrição |
|---|---|
| Erro | Mensagem de erro (truncada) |
| Contagem | Número de ocorrências |
| Primeiramente visto | Quando ocorreu primeiro |
| Visto pela última vez | Ocorrência mais recente |
| Status | Não resolvido, Investigando, Resolvido ou Ignorado |
Visualização de detalhes do erro
Clique em um grupo de erros para ver:
- Mensagem de erro completa
- Rastreamento de pilha
- Navegadores, sistemas operacionais e dispositivos afetados
- Páginas onde o erro ocorre
- Cronograma de ocorrências
- Breadcrumbs levando ao erro
Você também pode alterar o status de um grupo (marcá-lo como Investigando, Resolvido ou Ignorado) para manter sua lista focada no que ainda precisa de atenção.
Tipos de erros
Tipos de erros comuns
| Tipo | Descrição | Causas comuns |
|---|---|---|
TypeError | Erro relacionado ao tipo | Acesso a propriedades indefinidas |
ReferenceError | Referência a indefinido | Variáveis indefinidas |
SyntaxError | Sintaxe inválida | JSON malformado, erros de digitação |
RangeError | Valor fora do intervalo | Comprimento de matriz inválido |
URIError | Erro de tratamento de URI | URIs malformados |
EvalError | Erro eval() | Obsoleto, raramente visto |
Os erros também são classificados por categoria (JavaScript, rede, recurso ou personalizado) e gravidade, que o painel usa para ajudá-lo a priorizar.
Rejeições de promessa
// Rejeição não tratada - capturada automaticamente
Promise.reject(new Error('Something failed'));
// Rejeição tratada - não capturada
Promise.reject(new Error('Something failed'))
.catch(error => handleError(error));
Mapas de origem
Código minificado produz rastreamentos de pilha ilegíveis:
Error: undefined is not a function
at a.b (main.min.js:1:2345)
at c.d (main.min.js:1:3456)
Com mapas de origem enviados, o painel pode mostrar seu código original:
Error: undefined is not a function
at processPayment (checkout.js:45:12)
at handleSubmit (form.js:123:8)
Os mapas de origem são carregados através da API de rastreamento de erros e correspondidos com erros por um identificador release. Integre o upload em seu pipeline de compilação para que cada versão seja entregue com seus mapas.
Para a referência completa de upload (endpoint, campos e exemplo de CI), ver Mapas de origem para erros JS.
Filtrando erros
Erros que se originam da própria infraestrutura de rastreamento do Zenovay são descartados automaticamente, portanto você só vê erros do seu próprio código.
Para reduzir o ruído restante, concentre-se no que é acionável no painel:
- Use o status Ignorado para silenciar um erro conhecido de terceiros ou extensão de navegador para que ele pare de abarrotar sua lista.
- Resolva grupos que você corrigiu para que novas ocorrências se destaquem.
Alertas de erro
Receba notificações quando os erros aumentem usando uma regra de automação:
- Abra o painel do seu site e vá para Configurações → Automação
- Crie uma regra com o gatilho Limite de taxa de erro
- Defina o limite (erros por hora)
- Escolha como deseja ser notificado: e-mail, webhook ou Slack
Quando a taxa de erro cruza seu limite, o Zenovay dispara a ação que você configurou.
Integração com repetição de sessão
Se a repetição de sessão estiver habilitada para o site, os erros podem ser vinculados a gravações para que você possa ver o que o usuário estava fazendo quando um erro ocorreu. A repetição de sessão tem um modo de gatilho Apenas erros (em Configurações → Avançado → Sinalizadores de recurso) que registra sessões especificamente em torno de erros, o que mantém o armazenamento focado nas sessões que vale a pena assistir.
Isso ajuda você a entender:
- O que o usuário estava fazendo
- Estado da interface do usuário quando o erro ocorreu
- Passos para reproduzir
Melhores práticas
Tratamento deliberado de erros
Capture e trate erros de que você pode se recuperar, e deixe os que você não consegue se recuperar chegar ao rastreador:
// Bom: tratamento específico e recuperável
try {
const data = JSON.parse(userInput);
} catch (error) {
if (error instanceof SyntaxError) {
showValidationError('Invalid JSON format');
} else {
throw error; // irrecuperável - deixar ser capturado
}
}
Redução de ruído
- Marcar erros de extensão de navegador e de terceiros conhecidos como Ignorados
- Resolver grupos conforme você faz correções
- Priorizar por gravidade e contagem de ocorrências
Solução de problemas
Erros não aparecendo
Verifique:
- O script carrega antes de erros ocorrerem
- O rastreamento de erros está habilitado em Configurações → Avançado → Sinalizadores de recurso
- Um bloqueador de anúncios não está bloqueando solicitações para
api.zenovay.com
Rastreamentos de pilha faltando
Verifique:
- Mapas de origem são carregados para código minificado (ver Mapas de origem para erros JS)
- Cabeçalhos CORS são definidos para scripts cross-origin
- O erro não vem de um script de terceiros
Muitos erros
Considere:
- Marcar grupos ruidosos conhecidos como Ignorados
- Revisar e corrigir erros de alto volume primeiro