Análise de Rastreamento de Pilha

Domine a análise de rastreamento de pilha para identificar e corrigir rapidamente erros de JavaScript em sua aplicação.

Entendendo os rastreamentos de pilha

Anatomia de um rastreamento de pilha

TypeError: Cannot read property 'email' of undefined
    at getUserEmail (user-service.js:45:12)    ← Local do erro
    at validateForm (form-handler.js:123:8)    ← Chamado a partir daqui
    at HTMLFormElement.<anonymous> (form.js:67:5) ← Manipulador de evento
    at HTMLFormElement.dispatch (jquery.min.js:3:10456)
    at HTMLFormElement.v.handle (jquery.min.js:3:8765)

Componentes da frame de pilha

Cada linha contém:

Componente	Exemplo	Descrição
Função	getUserEmail	Nome da função
Arquivo	user-service.js	Arquivo fonte
Linha	45	Número da linha
Coluna	12	Posição da coluna

Direção de leitura

Leia os rastreamentos de pilha de cima para baixo:

1. Frame superior: Onde o erro ocorreu
2. Frames do meio: Cadeia de chamadas
3. Frames inferiores: Ponto de entrada

Visualizando rastreamentos de pilha em Zenovay

O rastreamento de erros é um recurso Pro. Uma vez habilitado para um site, os erros capturados são agrupados por impressão digital e exibidos na guia Erros do painel do site (/domains/{your-site}?tab=errors).

Para habilitá-lo, abra as configurações do site, vá para a seção Avançado e ative Rastreamento de Erros em sinalizadores de recurso.

A visualização de detalhes de erro

Abra um grupo de erro na guia Erros para ver suas ocorrências recentes. Para cada ocorrência você pode revisar:

• O tipo e mensagem de erro
• A URL da página onde ocorreu
• Detalhamentos de navegador, SO e dispositivo
• Os breadcrumbs (ações do usuário antes) do erro
• O rastreamento de pilha, mostrado como uma lista expansível de frames

O rastreamento de pilha fica recolhido por padrão. Expanda-o para ver cada frame como:

at getUserById (user-service.js:45:12)
at handleGetUser (api-handler.js:78:5)
at <anonymous> (router.js:23:3)

Rastreamentos longos são truncados para os primeiros frames, com um indicador "mais frames" para o resto. O nome da função, arquivo, linha e coluna são mostrados para cada frame para que você possa ir direto ao código relevante em seu editor.

Source Maps

Os source maps permitem que o Zenovay converta rastreamentos de pilha de produção minificados de volta ao seu arquivo fonte, linha e coluna originais.

Sem source maps

Código minificado produz rastreamentos crípticos:

TypeError: a is not a function
    at e (main.abc123.js:1:34567)
    at t.handleClick (main.abc123.js:1:45678)
    at Object.onClick (main.abc123.js:1:56789)

Com source maps

O mesmo erro, legível:

TypeError: processPayment is not a function
    at handleCheckout (checkout.tsx:89:12)
    at CheckoutButton.handleClick (CheckoutButton.tsx:45:8)
    at onClick (form-events.ts:23:5)

Gerando source maps

O primeiro passo é gerar source maps durante sua build. Use source maps ocultos em produção para que os arquivos .map sejam criados mas nunca referenciados (ou servidos) de seu pacote público.

Webpack – gerar source maps ocultos:

// webpack.config.js
module.exports = {
  devtool: 'hidden-source-map',
  // Os source maps são gerados mas não referenciados na saída
};

Vite – gerar source maps ocultos:

// vite.config.js
export default {
  build: {
    sourcemap: 'hidden'
  }
};

Rollup – gerar source maps ocultos:

// rollup.config.js
export default {
  output: {
    sourcemap: 'hidden'
  }
};

Marque cada build com uma versão de release (veja Correlação de versão abaixo) para que os source maps e os erros se alinhem com o mesmo deploy.

Analisando padrões comuns

Acesso a propriedades indefinidas

TypeError: Cannot read property 'name' of undefined
    at renderUser (user-card.js:23:15)

Análise:

• O objeto esperado na linha 23 é indefinido
• Verifique o fluxo de dados para renderUser
• Provavelmente falta uma verificação nula

Padrão de correção:

// Antes
const name = user.name;

// Depois
const name = user?.name ?? 'Unknown';

Função não definida

ReferenceError: processPayment is not defined
    at handleSubmit (checkout.js:45:5)

Análise:

• Função chamada mas não em escopo
• Verifique imports/exports
• Verifique a ordem de carregamento do módulo

Erros de tipo

TypeError: users.map is not a function
    at renderUserList (list.js:12:20)

Análise:

• users não é um array
• Verifique o formato de resposta da API
• Verifique as suposições de tipo de dados

Análise avançada

Rastreamentos de pilha assincronizados

JavaScript moderno inclui contexto assincronizado:

Error: API request failed
    at fetchUser (api.js:34:11)
    at async loadUserData (user-loader.js:56:18)
    at async initApp (app.js:12:5)

Frames de origem cruzada

Scripts de terceiros mostram informações limitadas:

Error: Script error.
    at <anonymous> (https://third-party.com/widget.js:1:1)

Solução: Adicione cabeçalhos CORS aos scripts de terceiros:

<script src="https://third-party.com/widget.js" crossorigin="anonymous"></script>

Código de terceiros minificado

Para bibliotecas sem source maps:

• Identifique a biblioteca a partir do padrão de URL
• Verifique a versão da biblioteca
• Procure por problemas conhecidos
• Considere alternativas

Fluxo de depuração

Passo 1: Identificar a localização do erro

1. Olhe para o frame superior de pilha
2. Anote arquivo, linha, coluna
3. Entenda o que o código está fazendo

Passo 2: Rastrear o caminho de chamada

1. Siga os frames descendo na pilha
2. Identifique o fluxo de dados
3. Encontre de onde os dados ruins originam

Passo 3: Verificar o contexto

1. Veja a frequência de ocorrência do erro ao longo do tempo na guia Erros
2. Verifique navegadores/dispositivos afetados no detalhamento
3. Leia os breadcrumbs que levam ao erro

Passo 4: Reproduzir

1. Use relação de sessão (se disponível em seu plano)
2. Verifique as ações do usuário antes do erro
3. Teste com o mesmo navegador/condições

Passo 5: Corrigir e verificar

1. Implemente a correção
2. Faça deploy da nova versão
3. Marque o grupo de erro como resolvido na visualização de detalhes do erro
4. Monitore regressões

Gerenciando status de erro

Na visualização de detalhes do erro você pode alterar o status de um grupo para manter sua lista focada:

• Não resolvido – precisa de atenção (padrão)
• Investigando – alguém está trabalhando nisto
• Resolvido – corrigido e verificado
• Ignorado – conhecido e intencionalmente não acionado

Alterações de status requerem acesso de editor no workspace e são registradas no log de auditoria do workspace.

Correlação de versão

Quando você marca seu rastreamento com uma versão, cada erro capturado registra a versão de onde veio, para que você possa dizer qual deploy introduziu um problema.

Marcar versões

Defina um valor de versão em sua build para que o rastreador o relate com cada evento. O snippet base fica assim:

<script
  defer
  data-tracking-code="YOUR_TRACKING_CODE"
  src="https://api.zenovay.com/z.js"
></script>

Combine isso com os source maps correspondentes de sua build (marcados com a mesma versão) para que os rastreamentos de produção symbolizem contra a versão correta.

Melhores práticas

Gerenciamento de source maps

• Use source maps ocultos em produção
• Mantenha os source maps organizados por versão
• Marque cada build com a versão de release que corresponda ao seu deploy

Qualidade de rastreamento de pilha

• Use nomes de função significativos
• Evite funções anônimas
• Mantenha pilhas de chamadas com profundidade razoável
• Adicione contexto de erro onde necessário

Eficiência de depuração

• Comece com os erros mais impactados
• Use status (investigando, resolvido, ignorado) para focar a lista
• Documente as descobertas
• Compartilhe com sua equipe

Solução de problemas

Source maps faltantes

Verifique:

• Os source maps foram gerados para esta versão
• A versão coincide com o que o rastreador reporta
• Os nomes de arquivo se alinham com seus bundles implantados

Rastreamentos de pilha incompletos

Causas:

• Código assincronizado não rastreado adequadamente
• Erros de eval() ou código dinâmico
• Limitações do navegador

Mensagens "Script error"

Soluções:

• Adicione cabeçalhos CORS
• Use o atributo crossorigin
• Auto-hospede scripts de terceiros

Próximos passos

• Rastreamento de erros JavaScript
• Relação de sessão
• Monitoramento de desempenho