Breadcrumbs Sentry : la piste qui précède une erreur
Breadcrumbs Sentry
Breadcrumbs Sentry : addBreadcrumb, filtres et limites | We.Inc
Fonctionnement des breadcrumbs Sentry dans le SDK JavaScript : breadcrumbs automatiques et manuels, filtrage avec beforeBreadcrumb, valeur par défaut de 100 pour maxBreadcrumbs, et nettoyage des données.
Dans Sentry, les breadcrumbs sont de petits enregistrements de ce qui s'est passé juste avant une erreur : clics, requêtes réseau, messages de console et changements de page. Le SDK en collecte beaucoup automatiquement, vous ajoutez les vôtres avec Sentry.addBreadcrumb(), et ils sont joints au prochain événement d'erreur. Par défaut, le SDK JavaScript conserve les 100 plus récents.
Les réglages des breadcrumbs en bref
Réglage ou appel
Ce qu'il fait
Par défaut
maxBreadcrumbs
Le nombre de breadcrumbs conservés
beforeBreadcrumb
Modifie ou supprime chaque breadcrumb avant son stockage
Non défini
Sentry.addBreadcrumb()
Enregistre votre propre breadcrumb
Sans objet
fatal, error, warning, log, info ou debug
Non défini
Quand un client rencontre une erreur sur votre site, la stack trace indique où le code a planté, mais pas ce que la personne a fait avant. Les breadcrumbs comblent ce manque. Ce guide porte sur le SDK JavaScript pour navigateur ; les autres SDK Sentry suivent le même principe avec leurs propres valeurs par défaut.
Le SDK écoute les clics et les frappes au clavier, les requêtes fetch et XHR, les appels à la console et les changements d'adresse, et transforme chacun en breadcrumb.
Votre propre code peut en ajouter avec Sentry.addBreadcrumb(), par exemple après une connexion ou l'application d'un code promo.
Chaque nouveau breadcrumb passe d'abord par beforeBreadcrumb si vous l'avez défini. Renvoyer null le supprime.
La piste conservée est plafonnée à maxBreadcrumbs ; le SDK retire les plus anciens quand la liste dépasse ce plafond.
Quand une erreur est capturée, la piste en cours est jointe à cet événement et affichée sur la page de l'issue.
Utilisez une catégorie courte et stable comme auth, cart ou payment pour pouvoir filtrer la piste sur la page de l'issue.
Placez les détails dans data, pas dans le message, pour qu'ils s'affichent sous forme de champs.
Ne mettez jamais de mots de passe, de numéros de carte ou d'adresses complètes dans un breadcrumb. Sentry recommande lui-même de ne pas journaliser de données personnelles quand les logs de console deviennent des breadcrumbs.
Si la console est bavarde, supprimez les breadcrumbs de console dans beforeBreadcrumb plutôt que de réduire maxBreadcrumbs pour tout le reste.
Régler maxBreadcrumbs à 0 désactive les breadcrumbs ; le SDK s'arrête immédiatement pour toute valeur inférieure ou égale à 0.
Questions fréquentes
Quelle est la valeur par défaut de maxBreadcrumbs ?
100. La documentation Sentry indique une valeur par défaut de 100 pour le SDK JavaScript, et le code source du SDK utilise le même nombre quand l'option n'est pas définie.
Quels breadcrumbs sont enregistrés automatiquement ?
Dans le SDK navigateur : les clics et frappes au clavier sur les éléments du DOM, les requêtes XHR et fetch, les appels à l'API console et tous les changements d'adresse.
Quelles clés un breadcrumb peut-il avoir ?
type, category, message, level, timestamp et data. La documentation précise que les autres clés sont supprimées lors du traitement.
Comment empêcher l'enregistrement d'un breadcrumb ?
Définissez beforeBreadcrumb dans Sentry.init. La fonction reçoit chaque breadcrumb et un hint facultatif, et peut renvoyer un breadcrumb modifié ou null pour l'écarter.
Les breadcrumbs sont-ils envoyés seuls ?
Non. Ils sont conservés en mémoire et joints au prochain événement envoyé par le SDK, comme une erreur.
Les breadcrumbs manuels qui valent la peine
Les breadcrumbs automatiques vous disent ce qu'a fait le navigateur. Les manuels vous disent ce qu'a fait le parcours métier : un client a choisi la livraison express, un code de réduction a été appliqué, une date de réservation a été sélectionnée.
Ce sont les moments sur lesquels le support pose ses premières questions, donc les enregistrer évite un aller-retour.
Tenir les données personnelles à l'écart
Les breadcrumbs récupèrent souvent du texte que vous ne vouliez pas conserver : un e-mail dans une ligne de console, une requête de recherche dans une URL. Nettoyez-les dans beforeBreadcrumb avant leur stockage, et utilisez beforeSend pour le reste de l'événement.
Sentry propose aussi un nettoyage des données côté serveur, configurable dans son interface, qui sert de second filet.
Exemples de code
Ajouter un breadcrumb manuel
Enregistrez une étape métier avec une catégorie, un message court, un niveau et des champs supplémentaires sous data.
Filtrer et nettoyer les breadcrumbs
Supprimez le bruit de la console, masquez les adresses e-mail et écrivez explicitement la limite par défaut pour pouvoir la modifier facilement.
Simulateur de piste de breadcrumbs
Enregistrez quelques événements, réglez les options, puis déclenchez une erreur pour voir quels breadcrumbs l'accompagneraient. C'est une simulation dans votre navigateur ; rien n'est envoyé à Sentry.