Une équipe déployant un runtime Python de 5,5 Mo dans les navigateurs a découvert que 69 % des erreurs enregistrées lors d'un récent sprint relevaient d'un titre unique et trompeur, et que 89 % d'entre elles étaient en réalité des délais d'attente réseau (timeouts). Cette erreur de signalisation a orienté les développeurs vers une mauvaise piste de débogage et a laissé une part importante d'utilisateurs face à des échecs de téléchargement silencieux — un problème que n'importe quelle application web regroupant des ressources volumineuses peut bientôt rencontrer.

Le tableau de bord a induit en erreur

Le système de suivi des erreurs regroupe automatiquement les incidents selon l'emplacement du code où ils apparaissent pour la première fois. Le titre qui en résultait ressemblait à un simple bug dans le chargeur du runtime, l'équipe a donc passé le sprint à traquer des chemins de code qui n'avaient jamais expiré. Lorsque l'équipe a analysé les métadonnées sous-jacentes, la réalité est apparue : la plupart des échecs n'étaient pas des bugs, mais des connexions réseau interrompues qui avaient déclenché un timeout.

À retenir : Un titre d'erreur est une commodité, pas un diagnostic. Analysez périodiquement les données brutes pour vérifier ce que l'intitulé représente réellement.

L'API de connexion du navigateur a fourni un placeholder

Pour éviter de faire subir aux utilisateurs lents un téléchargement de 5,5 Mo, les développeurs ont consulté l'API Network Information du navigateur (navigator.connection). L'API rapportait une bande passante constante de 1,7 Mbps pour chaque nouveau visiteur.

Les navigateurs émettent une valeur par défaut lorsqu'ils n'ont pas de données historiques pour un nouvel utilisateur. Cette valeur est un indice, pas une vitesse définitive. Lorsque ce même placeholder apparaît pour chaque nouvelle session, cela signifie que l'API n'est pas encore calibrée pour cette audience.

À retenir : Traitez tout signal réseau qui ne varie jamais comme une valeur de repli (fallback), et non comme une métrique définitive.

Les instantanés ponctuels ne sont pas fiables

Après avoir écarté l'indice de bande passante peu fiable, l'équipe est passée à un autre signal qui semblait fonctionner dans leur suite de tests. Un passage de test a réussi, mais répéter le test trois fois a produit des échecs à chaque fois. La vitesse du réseau fluctue continuellement. Le code avait pris un instantané unique, avait pris une décision permanente, puis avait continué même si la connexion changeait un instant plus tard.

À retenir : Ne basez pas une action permanente sur une seule lecture d'une cible mouvante. Abonnez-vous aux événements de changement au lieu de procéder à un simple interrogage (polling).

Correctifs pratiques mis en œuvre par l'équipe

  • S'abonner aux changements de connexion. Au lieu de lire navigator.connection une seule fois, le code écoute désormais l'événement change et réagit si la bande passante chute ou augmente pendant le téléchargement.
  • Ajouter un mécanisme de surveillance (watchdog) de « non-progression ». Un minuteur interrompt toute requête qui n'avance pas après un court intervalle, libérant ainsi le navigateur pour qu'il puisse réessayer ou utiliser une solution de repli.
  • Arrêter de changer de CDN en plein téléchargement. Changer la source d'un fichier volumineux sur une connexion lente redémarre le transfert à zéro, gaspillant les octets déjà reçus. Le téléchargement s'en tient désormais au CDN choisi initialement pour toute sa durée.
  • Différer les tâches de mise en cache lourdes. Les tâches qui écrivent de grandes quantités de données dans le cache sont reportées jusqu'à ce que le runtime ait fini de se charger, afin de maintenir un chemin critique court.

Si vos tableaux de bord présentent une image étrangement parfaite, creusez davantage. Si une mesure réseau ne bouge jamais, traitez-la comme un placeholder. Et si un seul instantané décide du sort d'un téléchargement de plusieurs mégaoctets, vous pariez sur un mirage. Ces paris se traduisent par des échecs silencieux qui érodent la confiance des utilisateurs — quelque chose qu'aucun code ingénieux ne pourra pleinement réparer après coup.