Uma equipe que estava distribuindo um runtime Python de 5,5 MB para navegadores descobriu que 69% dos erros registrados durante um sprint recente caíam sob um único título enganoso, e 89% deles eram, na verdade, timeouts de rede. O erro no relatório enviou os desenvolvedores pelo caminho de depuração errado e deixou uma parcela considerável de usuários com falhas de download silenciosas — um problema que qualquer web-app que agrupa grandes assets pode replicar em breve.

O dashboard induziu ao erro

O sistema de rastreamento de erros agrupa automaticamente os incidentes pela localização do código onde eles aparecem pela primeira vez. O título resultante parecia um simples bug no carregador do runtime, então o sprint foi gasto caçando caminhos de código que nunca sofriam timeout. Quando a equipe analisou os metadados subjacentes, a imagem real surgiu: a maioria das falhas não eram bugs, mas sim conexões de rede travadas que disparavam um timeout.

Lição: Um título de erro é uma conveniência, não um diagnóstico. Periodicamente, analise os dados brutos para verificar o que o título realmente representa.

A API de conexão do navegador forneceu um placeholder

Para evitar arrastar usuários com conexões lentas por um download de 5,5 MB, os desenvolvedores consultaram a Network Information API do navegador (navigator.connection). A API relatou uma largura de banda constante de 1,7 Mbps para cada visitante de primeira viagem.

Os navegadores emitem um valor padrão quando não possuem dados históricos de um novo usuário. Esse padrão é apenas uma dica, não uma velocidade definitiva. Quando o mesmo placeholder aparece em todas as novas sessões, isso sinaliza que a API ainda não está calibrada para aquele público.

Lição: Trate qualquer sinal de rede que nunca varia como um fallback, não como uma métrica definitiva.

Snapshots únicos não são confiáveis

Após descartar a dica de largura de banda não confiável, a equipe mudou para um sinal diferente que parecia funcionar em sua suíte de testes. Uma execução de teste passou, mas repetir o teste três vezes produziu falhas em todas as vezes. A velocidade da rede flutua continuamente. O código havia tirado um único snapshot, tomado uma decisão permanente e então prosseguido, mesmo que a conexão mudasse um momento depois.

Lição: Não baseie uma ação permanente em uma única leitura de um alvo móvel. Inscreva-se em eventos de mudança em vez de fazer polling apenas uma vez.

Correções práticas implementadas pela equipe

  • Inscreva-se em mudanças de conexão. Em vez de ler navigator.connection uma única vez, o código agora escuta o evento change e reage se a largura de banda cair ou subir durante o download.
  • Adicione um watchdog de “sem progresso”. Um timer aborta qualquer requisição que não apresente progresso após um curto intervalo, liberando o navegador para tentar novamente ou usar um fallback.
  • Pare de trocar de CDNs no meio do download. Trocar a fonte de um arquivo grande em uma conexão lenta reinicia a transferência do zero, desperdiçando bytes já recebidos. O download agora permanece no CDN escolhido inicialmente durante toda a sua duração.
  • Adie o trabalho pesado de cache. Tarefas que escrevem grandes quantidades de dados no cache são adiadas até que o runtime termine de carregar, mantendo o caminho crítico curto.

Se seus dashboards pintam um cenário inquietantemente organizado, investigue mais a fundo. Se uma medição de rede nunca se move, trate-a como um placeholder. E se um único snapshot decide o destino de um download de vários megabytes, você está apostando em uma miragem. Essas apostas aparecem como falhas silenciosas que corroem a confiança do usuário — algo que nenhuma quantidade de código inteligente pode reparar totalmente depois que o fato ocorre.