Un playground Python basé sur le navigateur qui embarque un runtime de 5,5 Mo a commencé à échouer silencieusement pour les utilisateurs ayant des connexions lentes. Le coupable était une mauvaise utilisation de l'API Network Information et un tableau de bord de regroupement d'erreurs qui a mal étiqueté le problème. Le bug s'est caché pendant des semaines, a gaspillé du temps de développement et a laissé un segment d'utilisateurs incapables d'exécuter du code.

Comment le problème est apparu

Le traqueur d'erreurs du playground a affiché un message unique et frappant : « undefined is not an object. ». Le titre suggérait une simple faute de frappe JavaScript, l'équipe a donc poursuivi une piste de code inexistante. Lorsqu'ils ont inspecté les métadonnées brutes, ils ont constaté que 89 % de ces incidents étaient en réalité des délais d'attente réseau (timeouts). Le tableau de bord avait pris la première erreur reçue et l'avait utilisée pour nommer tout le lot, masquant ainsi le véritable type d'échec.

Leçon 1 – Les titres de tableaux de bord peuvent être trompeurs

Un tableau de bord qui agrège les incidents n'est utile que si sa logique d'agrégation reflète la cause réelle de chaque événement. Ici, le regroupement par emplacement plutôt que par cause d'erreur a brossé un faux portrait d'un bug côté client. La leçon à retenir : ne réparez jamais un problème en vous basant uniquement sur le titre d'un tableau de bord. Extrayez un échantillon des événements sous-jacents et vérifiez ce qui se passe réellement avant d'allouer des ressources.

Leçon 2 – Les valeurs de substitution ne sont pas des mesures

Pour éviter de charger le runtime volumineux pour les utilisateurs ayant des connexions lentes, le code consultait l'API Network Information et lisait la propriété downlink, qui indique le débit en mégabits par seconde. Lors d'une première visite, Chrome renvoie souvent une valeur de substitution (placeholder) au lieu d'une mesure réelle. La logique a traité cette valeur comme une connexion rapide et a ignoré l'optimisation, bloquant ainsi les utilisateurs mêmes qu'elle était censée aider.

Traitez toute valeur par défaut ou sentinelle comme « aucune donnée ». Une valeur de substitution devrait déclencher une stratégie de repli, et non être interprétée comme une lecture de vitesse réelle.

Leçon 3 – Les conditions réseau changent, un instantané unique est donc peu fiable

Après le problème de downlink, l'équipe est passée à la vérification de effectiveType, qui catégorise les connexions en « 4G », « 3G », etc. Un test rapide en laboratoire a réussi, mais le même test, relancé quelques instants plus tard, a échoué. Les connexions mobiles fluctuent ; un utilisateur peut apparaître sur une connexion 4G rapide une seconde et passer à une 3G plus lente la suivante. Vérifier la connexion uniquement au chargement de la page est un pari risqué.

La bonne approche consiste à s'abonner à l'événement change sur l'objet Network Information et à réagir à tout changement de bande passante plutôt que de prendre une décision ponctuelle.

Ce que l'équipe a modifié

  • Téléchargement en deux étapes – Le runtime commence désormais par un minuscule fichier bootstrap. Si la connexion est identifiée comme lente, le bootstrap récupère le reste du runtime par petits morceaux, réduisant ainsi le risque d'un abandon complet.
  • Surveillance en direct – Au lieu d'une seule lecture de downlink, le code écoute désormais les événements change et ajuste la stratégie de téléchargement à la volée.
  • Sélection de source stable – Auparavant, le système changeait de CDN en plein milieu du téléchargement lorsqu'un point de terminaison plus rapide apparaissait. Sur une connexion lente, cela provoquait le redémarrage du téléchargement à zéro, aggravant le problème. La nouvelle logique verrouille la source pour toute la durée du téléchargement.
  • Écritures de cache différées – Les opérations de cache lourdes qui s'exécutaient avant que l'application ne soit utilisable sont désormais reportées jusqu'à ce que le runtime ait démarré, libérant ainsi la bande passante pour le téléchargement critique.

Les enjeux plus larges

Pour les développeurs qui créent des outils web, la variabilité du réseau est une préoccupation de premier ordre. Un échec silencieux sur une connexion lente frustre les utilisateurs et fausse la télémétrie, orientant les équipes vers une mauvaise piste de débogage. Dans ce cas, une mauvaise interprétation des données a entraîné des semaines d'investigations infructueuses.

À surveiller ensuite

À retenir : Lorsque les données semblent trop propres, il s'agit probablement d'une valeur de substitution ; lorsqu'un titre de tableau de bord pointe vers un bug unique, creusez davantage ; et lorsque vous basez une décision sur une lecture réseau ponctuelle, vous pariez sur une cible mouvante. S'adapter à ces réalités transforme les échecs silencieux en événements prévisibles et récupérables.