Em algum lugar das suas ferramentas de suporte existe uma resposta pronta que diz: «Você poderia apertar F12, abrir a aba Console e mandar uma captura de tela de qualquer texto em vermelho?» Ela é enviada algumas vezes por semana. Quase nunca volta com algo útil, e cada correção que dependia dela fica parada por dias enquanto a conversa esfria.
Este post é sobre aposentar essa resposta. Não ensinando DevTools aos usuários, mas garantindo que, da próxima vez que um usuário disser «a página quebrou», os erros do console e as requisições que falharam na sessão dele já estejam no relatório.
Por que o pedido de DevTools nunca funciona
A resposta pronta falha por motivos que não têm nada a ver com a boa vontade do usuário:
A maioria dos usuários nunca viu o DevTools. O atalho de teclado muda conforme o sistema e o navegador, a aba Console é uma entre uma dúzia, e stack traces em vermelho parecem ruído. Você está pedindo a alguém que opere um instrumento profissional, uma única vez, sem supervisão, por e-mail.
A evidência já sumiu. A saída do console dura exatamente o tempo de vida da aba. Quando a sua resposta chega, o usuário já fechou a página, e o erro de que você precisava não existe mais em lugar nenhum. Agora você está pedindo que ele reproduza o bug sob demanda, justamente o que você mesmo não consegue fazer.
Captura de tela é o formato errado. Mesmo no melhor caso, você recebe a imagem de um stack trace recolhido, cortada de um jeito que esconde a única linha que importava, sem horários e sem contexto de rede. Não dá para pesquisar, expandir nem cruzar com nada.
Some as idas e vindas, e o pedido de DevTools custa dias de espera para obter, na melhor das hipóteses, uma fração do que o navegador sabia de graça no momento da falha.
Inverta a direção: o navegador reporta, o usuário só descreve
A solução é parar de fazer a evidência passar pela memória e pelas capturas de tela do usuário e coletá-la de onde ela já existe: o navegador dele, no momento do bug.
É isso que um widget de relatório de bug faz. Com o BugDump instalado, a captura já está rodando antes de qualquer coisa quebrar: o SDK mantém uma janela circular com as entradas recentes do console e a atividade de rede enquanto o usuário navega. Quando ele encontra um problema, clica no botão de bug e digita uma frase com as próprias palavras. Essa frase é todo o trabalho dele. Tudo o que você teria pedido vai junto automaticamente:
Logs do console: as últimas 300 entradas, com erros e avisos sinalizados, pesquisáveis no painel. Exceções não capturadas e rejeições de promise não tratadas também são capturadas, inclusive as que o seu código nunca registrou.
Requisições de rede: as últimas 150, com método, código de status e tempo; as falhas ficam destacadas. O 500 que veio antes da quebra visível está ali, logo ao lado.
Ambiente: navegador, SO, dispositivo, viewport e a URL exata da página, para que ninguém nunca mais precise digitar «qual navegador você está usando?».
Replay de sessão: uma reconstrução navegável do que o usuário fez até o relatório, para os bugs em que a sequência de cliques é a causa.
A ordem é o que faz isso funcionar. Qualquer fluxo que começa a coletar depois que o usuário decide reportar já perdeu o erro. Como os buffers rodam o tempo todo, o momento da falha é capturado mesmo que ninguém, muito menos o usuário, soubesse que um bug estava para acontecer.
Lendo um relatório: o diagnóstico de dois minutos
Um relatório com telemetria anexada é lido numa ordem específica, e rápido:
Leia a frase do usuário: ela diz a intenção («eu estava tentando pagar»).
Vá direto às entradas sinalizadas: a exceção não capturada no console, a requisição que falhou na lista de rede.
Veja o que aconteceu logo antes delas: a requisição que devolveu dados inesperados, o aviso disparado na ação anterior.
Se a sequência importa, percorra o replay para ver em que o usuário clicou de fato.
O erro do console aponta o sintoma no seu código; o log de rede costuma apontar a causa; o replay resolve a discussão sobre o que significa «eu só cliquei normalmente». A maioria dos relatórios vai de «aberto» a «sei qual arquivo abrir» sem uma única mensagem para o usuário: a ida e volta de esclarecimentos que levava dias simplesmente não acontece.
Como configurar
A instalação é uma linha em qualquer site, sem etapa de build e sem adaptador de framework:
<script src="https://bugdump.com/sdk/latest.js" async data-api-key="your-api-key"></script>Duas adições valem a pena desde o primeiro dia. Se o seu app tem usuários logados, chame bugdump('identify', { email }) depois do login para que cada relatório traga quem o enviou. E se as suas páginas rodam scripts de terceiros barulhentos (beacons de analytics, polling de feature flags), configure consoleFilter e networkFilter no SDK para que os buffers guardem a atividade do seu app, e não ruído de heartbeat. As entradas filtradas nunca saem do navegador, então os filtros servem tanto à privacidade quanto à higiene dos dados. Os corpos de requisição e de resposta vêm desligados por padrão (captureNetworkBodies os liga); deixe-os desligados a menos que tenha um motivo concreto, e informe na sua política de privacidade que os relatórios de bug incluem logs de diagnóstico.
Depois, verifique o ciclo de ponta a ponta: envie um relatório no seu próprio site, abra-o no painel e confirme que as seções de console e de rede mostram a sua sessão. Esse teste de dois minutos é exatamente a experiência que os seus usuários vão ter.
Aposente a resposta pronta
A resposta pronta não desaparece de vez: ela fica mais curta. «Você poderia clicar no botão de bug na página e enviar um relatório?» é um pedido de uma linha que o usuário consegue cumprir, e o que volta não é uma captura de tela cortada, e sim o console, o log de rede, o ambiente e o replay do momento em que a página quebrou.
Você continua lendo erros todos os dias. Só que vai lê-los no painel, vindos dos navegadores em que os bugs aconteceram de fato, em vez de pedir aos usuários que descrevam um texto vermelho que nunca foi feito para eles entenderem.
Leia também
Como capturar logs do console e requisições de rede do navegador do usuário — como instrumentar console, erros, fetch e XHR sem quebrar a página que você está monitorando.
O que fazer com um relatório de bug que você não consegue reproduzir — as causas habituais de um bug que não se reproduz e o contexto que as revela.
Replay de sessão para depuração: veja o que o usuário fez antes do bug — como o replay de sessão funciona, o que ele captura e por que rende mais ao lado dos logs de console e de rede.