Analyse des traces de pile

Maîtrisez l'analyse des traces de pile pour identifier et corriger rapidement les erreurs JavaScript dans votre application.

Comprendre les traces de pile

Anatomie d'une trace de pile

TypeError: Cannot read property 'email' of undefined
    at getUserEmail (user-service.js:45:12)    ← Emplacement de l'erreur
    at validateForm (form-handler.js:123:8)    ← Appelé à partir d'ici
    at HTMLFormElement.<anonymous> (form.js:67:5) ← Gestionnaire d'événements
    at HTMLFormElement.dispatch (jquery.min.js:3:10456)
    at HTMLFormElement.v.handle (jquery.min.js:3:8765)

Composants d'une frame de pile

Chaque ligne contient :

Composant	Exemple	Description
Fonction	getUserEmail	Nom de la fonction
Fichier	user-service.js	Fichier source
Ligne	45	Numéro de ligne
Colonne	12	Position de colonne

Sens de lecture

Lisez les traces de pile de haut en bas :

1. Frame supérieur : Où l'erreur s'est produite
2. Frames du milieu : Chaîne d'appel
3. Frames du bas : Point d'entrée

Affichage des traces de pile dans Zenovay

Le suivi des erreurs est une fonctionnalité Pro. Une fois activée pour un site web, les erreurs capturées sont groupées par empreinte et affichées sur l'onglet Erreurs du tableau de bord du site (/domains/{your-site}?tab=errors).

Pour l'activer, ouvrez les paramètres du site web, accédez à la section Avancé et activez Suivi des erreurs sous les drapeaux de fonctionnalités.

La vue des détails d'erreur

Ouvrez un groupe d'erreurs depuis l'onglet Erreurs pour voir ses occurrences récentes. Pour chaque occurrence, vous pouvez consulter :

• Le type d'erreur et le message
• L'URL de page où elle s'est produite
• Les répartitions navigateur, système d'exploitation et appareil
• Les breadcrumbs (actions de l'utilisateur avant) l'erreur
• La trace de pile, affichée comme une liste dépliable de frames

La trace de pile est réduite par défaut. Développez-la pour voir chaque frame comme :

at getUserById (user-service.js:45:12)
at handleGetUser (api-handler.js:78:5)
at <anonymous> (router.js:23:3)

Les longues traces sont tronquées aux premières frames, avec un indicateur « plus de frames » pour le reste. Le nom de la fonction, le fichier, la ligne et la colonne sont affichés pour chaque frame afin que vous puissiez accéder directement au code pertinent dans votre éditeur.

Source Maps

Les source maps permettent à Zenovay de convertir les traces de pile minifiées de production en votre fichier source d'origine, ligne et colonne.

Sans source maps

Le code minifié produit des traces cryptiques :

TypeError: a is not a function
    at e (main.abc123.js:1:34567)
    at t.handleClick (main.abc123.js:1:45678)
    at Object.onClick (main.abc123.js:1:56789)

Avec les source maps

La même erreur, lisible :

TypeError: processPayment is not a function
    at handleCheckout (checkout.tsx:89:12)
    at CheckoutButton.handleClick (CheckoutButton.tsx:45:8)
    at onClick (form-events.ts:23:5)

Générer les source maps

La première étape consiste à générer les source maps lors de votre build. Utilisez les source maps cachées en production afin que les fichiers .map soient créés mais jamais référencés (ou servis) depuis votre bundle public.

Webpack – générer les source maps cachées :

// webpack.config.js
module.exports = {
  devtool: 'hidden-source-map',
  // Les source maps sont générées mais non référencées dans la sortie
};

Vite – générer les source maps cachées :

// vite.config.js
export default {
  build: {
    sourcemap: 'hidden'
  }
};

Rollup – générer les source maps cachées :

// rollup.config.js
export default {
  output: {
    sourcemap: 'hidden'
  }
};

Étiquetez chaque build avec une version de release (voir Corrélation de version ci-dessous) afin que les source maps et les erreurs s'alignent contre le même déploiement.

Analyse des patterns courants

Accès à des propriétés indéfinies

TypeError: Cannot read property 'name' of undefined
    at renderUser (user-card.js:23:15)

Analyse :

• L'objet attendu à la ligne 23 est indéfini
• Vérifiez le flux de données vers renderUser
• Probablement une vérification null manquante

Motif de correction :

// Avant
const name = user.name;

// Après
const name = user?.name ?? 'Unknown';

Fonction non définie

ReferenceError: processPayment is not defined
    at handleSubmit (checkout.js:45:5)

Analyse :

• Fonction appelée mais pas en scope
• Vérifiez les imports/exports
• Vérifiez l'ordre de chargement des modules

Erreurs de type

TypeError: users.map is not a function
    at renderUserList (list.js:12:20)

Analyse :

• users n'est pas un tableau
• Vérifiez le format de la réponse API
• Vérifiez les hypothèses de type de données

Analyse avancée

Traces de pile asynchrones

JavaScript moderne inclut un contexte asynchrone :

Error: API request failed
    at fetchUser (api.js:34:11)
    at async loadUserData (user-loader.js:56:18)
    at async initApp (app.js:12:5)

Frames cross-origin

Les scripts tiers montrent des informations limitées :

Error: Script error.
    at <anonymous> (https://third-party.com/widget.js:1:1)

Solution : Ajoutez les en-têtes CORS aux scripts tiers :

<script src="https://third-party.com/widget.js" crossorigin="anonymous"></script>

Code tiers minifié

Pour les bibliothèques sans source maps :

• Identifiez la bibliothèque à partir du motif d'URL
• Vérifiez la version de la bibliothèque
• Recherchez les problèmes connus
• Envisagez des alternatives

Flux de débogage

Étape 1 : Identifier l'emplacement de l'erreur

1. Regardez la frame de pile supérieure
2. Notez le fichier, la ligne, la colonne
3. Comprendre ce que fait le code

Étape 2 : Tracer le chemin d'appel

1. Suivez les frames vers le bas de la pile
2. Identifiez le flux de données
3. Trouvez d'où proviennent les mauvaises données

Étape 3 : Vérifier le contexte

1. Consultez la fréquence d'occurrence de l'erreur au fil du temps sur l'onglet Erreurs
2. Vérifiez les navigateurs/appareils affectés dans la répartition
3. Lisez les breadcrumbs menant à l'erreur

Étape 4 : Reproduire

1. Utilisez la relecture de session (si disponible sur votre plan)
2. Vérifiez les actions de l'utilisateur avant l'erreur
3. Testez avec le même navigateur/conditions

Étape 5 : Corriger et vérifier

1. Implémentez la correction
2. Déployez la nouvelle version
3. Marquez le groupe d'erreurs comme résolu dans la vue des détails d'erreur
4. Surveillez les régressions

Gestion du statut d'erreur

À partir de la vue des détails d'erreur, vous pouvez modifier le statut d'un groupe pour garder votre liste focalisée :

• Non résolu – nécessite une attention (par défaut)
• En investigation – quelqu'un travaille dessus
• Résolu – corrigé et vérifié
• Ignoré – connu et intentionnellement non traité

Les modifications de statut nécessitent un accès en édition sur l'espace de travail et sont enregistrées dans le journal d'audit de l'espace de travail.

Corrélation de version

Lorsque vous étiquetez votre suivi avec une version, chaque erreur capturée enregistre la version d'où elle provient, afin que vous puissiez dire quel déploiement a introduit un problème.

Étiqueter les versions

Définissez une valeur de version dans votre build afin que le tracker le rapporte avec chaque événement. L'extrait de base ressemble à ceci :

<script
  defer
  data-tracking-code="YOUR_TRACKING_CODE"
  src="https://api.zenovay.com/z.js"
></script>

Associez cela aux source maps correspondantes de votre build (étiquetées avec la même version) afin que les traces de production se symbolisent par rapport à la version correcte.

Bonnes pratiques

Gestion des source maps

• Utilisez les source maps cachées en production
• Gardez les source maps organisées par version
• Étiquetez chaque build avec la version de release qui correspond à votre déploiement

Qualité des traces de pile

• Utilisez des noms de fonction significatifs
• Évitez les fonctions anonymes
• Gardez les piles d'appels à une profondeur raisonnable
• Ajoutez du contexte d'erreur si nécessaire

Efficacité du débogage

• Commencez par les erreurs les plus impactées
• Utilisez le statut (en investigation, résolu, ignoré) pour focaliser la liste
• Documentez les conclusions
• Partagez avec votre équipe

Dépannage

Source maps manquantes

Vérifiez :

• Les source maps ont été générées pour cette version
• La version correspond à ce que rapporte le tracker
• Les noms de fichiers correspondent à vos bundles déployés

Traces de pile incomplètes

Causes :

• Code asynchrone non tracé correctement
• Erreurs de eval() ou code dynamique
• Limitations du navigateur

Messages « Script error »

Solutions :

• Ajouter les en-têtes CORS
• Utiliser l'attribut crossorigin
• Auto-héberger les scripts tiers

Étapes suivantes

• Suivi des erreurs JavaScript
• Relecture de session
• Surveillance des performances