Existe um ponto cego em praticamente toda operação de aplicação web: o que acontece depois que a página chega ao navegador do usuário.
O servidor registra que entregou a página com sucesso. Os indicadores de disponibilidade mostram tudo normal. E, na tela de alguém, a aplicação travou, um botão não fez nada, ou uma tela ficou em branco.
Nada disso aparece em nenhum registro do servidor — porque não aconteceu no servidor. Este guia trata de como enxergar essa camada.
Por que o servidor não vê
Vale entender o mecanismo, porque ele explica o tamanho do ponto cego.
Em uma aplicação que roda no navegador, boa parte da lógica é executada no dispositivo do usuário. O servidor entregou os arquivos e, a partir dali, o que acontece é invisível para ele.
Isso significa que os seguintes problemas não geram nenhum registro do lado do servidor:
- Erro de execução que interrompe a interface.
- Chamada a uma API que falhou e não foi tratada.
- Recurso externo que não carregou — uma fonte, um script, uma imagem.
- Comportamento diferente em um navegador específico ou em uma versão antiga.
- Lentidão no dispositivo do usuário, mesmo com o servidor respondendo rápido.
- Falha em uma extensão do navegador interferindo na aplicação.
O caso mais grave é o primeiro: um erro não tratado pode interromper a renderização e deixar a tela em branco. O usuário vê nada, não sabe reportar o que aconteceu, e frequentemente apenas vai embora.
A consequência comercial é direta: problemas que ninguém relata também não são corrigidos. A maior parte dos usuários não abre chamado — ela desiste.
O que é possível capturar
A técnica é conhecida: a própria aplicação reporta os problemas que encontra.
Os navegadores oferecem mecanismos para interceptar erros que acontecem na execução, e a aplicação pode enviá-los para um destino onde alguém consiga vê-los.
O que vale capturar:
| O que | Por que importa |
|---|---|
| Erros de execução | Interrompem a interface |
| Falhas de chamadas à API | Revelam problemas de integração |
| Recursos que não carregaram | Indicam dependência externa instável |
| Contexto do erro | Navegador, dispositivo, rota, ação |
| Métricas de experiência | O que o usuário percebe de velocidade |
| Versão publicada | Relaciona o erro a uma publicação específica |
O quarto item é o que transforma dado em informação útil. Um erro sem contexto não permite investigar nada. Saber que aconteceu em uma rota específica, em um navegador específico, depois de uma ação específica é o que torna o problema reproduzível.
E o sexto merece destaque: registrar qual versão do código estava carregada permite responder à pergunta mais útil de todas — esse erro começou depois de qual publicação?
Os erros que você vai encontrar
Quem ativa esse tipo de captura pela primeira vez costuma se surpreender com o volume. Vale saber o que esperar, porque boa parte não é problema real.
Ruído que pode ser ignorado
- Extensões de navegador interferindo na página — geram erros que não vêm do seu código.
- Robôs e rastreadores executando a aplicação de formas inesperadas.
- Navegadores muito antigos que não suportam recursos usados.
- Erros de rede do usuário, como conexão interrompida no meio de uma chamada.
- Tradutores automáticos de página, que alteram a estrutura e quebram a aplicação.
O último é frequente e pouco conhecido: funções de tradução automática modificam o conteúdo da página e podem quebrar aplicações que esperam encontrar a estrutura original. É uma categoria inteira de erro que parece grave e não tem correção do seu lado.
O que merece atenção
- Erros recorrentes na mesma rota, que indicam um problema real de código.
- Erros que aparecem depois de uma publicação — a correlação mais valiosa.
- Falhas concentradas em um navegador ou versão, que apontam incompatibilidade.
- Chamadas à API falhando em volume, que podem indicar problema no back-end.
- Erros afetando muitos usuários distintos, em oposição a um único caso.
A distinção prática: um erro que aconteceu mil vezes com um usuário é diferente de um que aconteceu mil vezes com mil usuários. O primeiro pode ser um caso isolado; o segundo é prioridade.
Cuidado com dados pessoais
Um ponto que precisa ser tratado antes de ativar qualquer captura.
Informações de erro podem carregar dados que não deveriam sair do navegador: conteúdo de formulários, identificadores de sessão, informações pessoais presentes na tela ou no endereço acessado.
O que observar:
- Não capturar conteúdo de campos de formulário, especialmente os de senha e dados pessoais.
- Filtrar endereços que carreguem informação sensível em parâmetros.
- Não registrar credenciais que possam aparecer em chamadas capturadas.
- Definir retenção para os dados coletados.
- Avaliar para onde os dados vão, já que serviços externos de captura recebem informação da sua aplicação.
- Considerar as obrigações aplicáveis, porque dados pessoais capturados de usuários estão sob a LGPD.
O quinto item merece decisão consciente: um serviço externo de captura de erros recebe dados da sua aplicação e dos seus usuários. Isso é aceitável em muitos casos e exige avaliação em operações com dados sensíveis. Para as questões de base legal e tratamento, vale orientação especializada.
O problema do código otimizado
Uma dificuldade prática específica de aplicações modernas.
O build de produção transforma o código: nomes são encurtados, arquivos são unidos, espaços removidos. Isso é bom para o desempenho e torna as mensagens de erro praticamente ilegíveis — uma falha reportada aponta para uma posição em um arquivo que não se parece com o código original.
A solução é gerar, durante o build, um arquivo de mapeamento que permite traduzir a posição no código otimizado de volta para o código original. Duas observações sobre ele:
- Ele precisa ser enviado ao serviço de captura, para que a tradução aconteça na hora de exibir o erro.
- Ele não deve ficar publicamente acessível no servidor, porque permite reconstruir boa parte do código original.
O segundo ponto é o que mais gera descuido: publicar esses arquivos junto com a aplicação expõe o código-fonte. Gerá-los e enviá-los ao serviço de captura sem deixá-los acessíveis ao público é o procedimento correto, e é uma verificação que vale fazer — o processo de build está detalhado no artigo sobre build de produção React.
Além dos erros: o que o usuário percebe
Uma extensão natural da mesma infraestrutura.
Os mesmos mecanismos que capturam erros permitem medir a experiência real: quanto tempo a página levou para exibir o conteúdo principal, quanto demorou para responder à primeira interação, se elementos se moveram durante o carregamento.
A diferença em relação a uma ferramenta de teste de velocidade é importante: a ferramenta mede uma vez, em condições controladas; a captura no navegador mede o que os seus usuários reais experimentam — em dispositivos modestos, conexões instáveis e navegadores diversos.
Essa diferença costuma ser reveladora. Uma aplicação que pontua bem em teste sintético pode ter experiência ruim para boa parte dos usuários, e só a medição real mostra isso. Os limites dessas métricas estão no artigo sobre por que o WordPress fica lento, e valem igualmente aqui.
O que fazer com os dados
Capturar sem processo produz um painel que ninguém olha. O que torna útil:
- Agrupar erros iguais, para ver quantos usuários distintos foram afetados.
- Alertar sobre novidades, e não sobre tudo — um erro novo importa mais que um conhecido.
- Alertar sobre aumento, quando um erro conhecido dispara em volume.
- Silenciar o ruído identificado, para que ele não esconda o que importa.
- Revisar periodicamente, com alguém responsável.
- Correlacionar com publicações, verificando o que mudou quando algo apareceu.
O item 4 é o que determina se a prática sobrevive: um painel cheio de erros de extensões e robôs faz com que ninguém olhe. Silenciar o ruído conhecido é o que mantém o sinal visível.
E o item 2 segue a mesma lógica dos alertas de servidor tratada no artigo sobre monitoramento de site: alerta que dispara demais deixa de ser lido.
Conclusão
O servidor registra que entregou a página. O que acontece depois — erro que trava a interface, chamada que falhou, tela em branco — é invisível para ele, e a maior parte dos usuários afetados não relata nada: apenas vai embora.
Capturar erros no navegador fecha esse ponto cego, e duas decisões determinam se a prática funciona: registrar contexto suficiente para tornar o problema reproduzível, incluindo a versão publicada, e silenciar o ruído conhecido de extensões, robôs e tradutores automáticos, para que o sinal continue visível.
E uma verificação de segurança que vale fazer hoje: os arquivos de mapeamento do seu build não devem estar publicamente acessíveis, porque permitem reconstruir o código original. Conheça o Cloud Server para React da TBF Host e avalie o ambiente adequado ao seu projeto.
Perguntas frequentes
Por que erros no navegador não aparecem nos logs do servidor?
Porque não acontecem no servidor. Ele entregou os arquivos e, a partir dali, a execução ocorre no dispositivo do usuário. Erros de execução, chamadas que falharam, recursos que não carregaram e incompatibilidades de navegador são invisíveis do lado do servidor.
Como saber o que quebra na tela do usuário?
Fazendo a própria aplicação reportar. Os navegadores oferecem mecanismos para interceptar erros de execução, e a aplicação pode enviá-los para um destino onde alguém os veja — com contexto de navegador, dispositivo, rota, ação e versão publicada.
Que contexto preciso registrar junto com o erro?
Navegador, dispositivo, rota acessada, ação realizada e, principalmente, a versão do código que estava carregada. Um erro sem contexto não permite investigar nada, e a versão é o que responde à pergunta mais útil: esse problema começou depois de qual publicação?
Por que aparecem tantos erros quando ativo a captura?
Boa parte é ruído: extensões de navegador interferindo na página, robôs executando a aplicação de formas inesperadas, navegadores muito antigos, conexões interrompidas e tradutores automáticos, que alteram a estrutura da página e quebram aplicações que esperam o conteúdo original.
Como priorizar os erros capturados?
Agrupando erros iguais e observando quantos usuários distintos foram afetados. Um erro que aconteceu mil vezes com um usuário é diferente de um que aconteceu mil vezes com mil usuários. Também vale priorizar os que apareceram logo após uma publicação.
Por que as mensagens de erro são ilegíveis em produção?
Porque o build otimiza o código, encurtando nomes e unindo arquivos. A solução é gerar um arquivo de mapeamento que traduz a posição no código otimizado de volta para o original — e enviá-lo ao serviço de captura sem deixá-lo publicamente acessível no servidor.
Capturar erros pode expor dados dos usuários?
Pode, se não houver cuidado. Informações de erro carregam conteúdo de formulários, identificadores de sessão e dados presentes na tela ou no endereço acessado. É preciso filtrar campos sensíveis, definir retenção e avaliar para onde esses dados vão, já que serviços externos os recebem.
Qual a diferença entre medir velocidade com uma ferramenta e medir no navegador?
A ferramenta mede uma vez, em condições controladas. A captura no navegador mede o que seus usuários reais experimentam, em dispositivos modestos e conexões instáveis. Uma aplicação que pontua bem em teste sintético pode ter experiência ruim para boa parte dos usuários.