Sentry dans Magento 2 : observabilite technique de la boutique avec le module Kowal_Sentry

Qu est-ce que Sentry et a quoi sert-il concretement

Sentry est le plus souvent associe au suivi des erreurs, mais dans la pratique c est une plateforme d observabilite qui relie plusieurs couches de diagnostic applicatif :

• remontée des exceptions et des erreurs d execution,
• tracing des performances et des dependances entre operations,
• breadcrumbs montrant la sequence des actions avant une panne,
• Session Replay cote navigateur,
• User Feedback venant de l utilisateur final,
• surveillance des processus periodiques comme cron,
• release tracking et rattachement des erreurs a un deploiement precis.

Dans un projet correctement mis en oeuvre, Sentry n est pas seulement l endroit ou arrive une stack trace. C est un outil qui permet de repondre a des questions comme :

• qu est-ce qui s est casse exactement,
• ou le probleme est apparu : backend, frontend, checkout, cron, integration,
• depuis quand le probleme existe et a quel release il est lie,
• si l erreur concerne tous les utilisateurs, une boutique precise, un mode de paiement ou un processus,
• a quoi ressemblait le contexte de la requete et ce qui s est passe juste avant l erreur.

Cela est particulierement important dans Magento, ou une panne est rarement une exception isolee dans un seul controleur. Elle touche souvent tout le flux : storefront, AJAX, checkout, prestataire de paiement, cron de synchronisation des donnees et traitement ulterieur de la commande.

Pourquoi Sentry est particulierement utile dans les projets Magento

Magento 2 est une plateforme vaste, en couches et fortement integree. Une boutique typique fonctionne en meme temps comme :

• application backend PHP,
• application frontend avec beaucoup de JavaScript,
• systeme d integration reliant ERP, PIM, WMS, OMS, passerelles de paiement et transporteurs,
• environnement multi-boutique avec differents scopes et configurations par website ou store view,
• plateforme qui supporte des processus de vente critiques, ou un probleme de checkout ou de cron a un impact direct sur le revenu.

En pratique, cela signifie qu un simple log fichier ne suffit pas. Une stack trace PHP seule ne suffit pas non plus. Le diagnostic a besoin d un modele d observation plus large :

• exceptions backend avec contexte metier,
• erreurs JavaScript issues d une vraie session utilisateur,
• tracing des requetes et des dependances HTTP,
• surveillance des cron et de la CLI,
• correlation avec le release apres deploiement,
• sanitisation des donnees afin que l observabilite ne compromette pas la securite.

C est exactement le domaine dans lequel Sentry s adapte bien a Magento, a condition que l integration soit mise en place de maniere consciente et non comme un simple wrapper autour de captureException().

Comment utiliser Sentry dans Magento 2

1. Surveillance des erreurs du backend PHP

Le scenario le plus evident consiste a remonter les exceptions PHP provenant du storefront, de l admin, de l API, des cron et de la CLI. Dans Magento, cela donne un acces rapide a :

• la stack trace,
• l environnement et le release,
• le route name et le full action name,
• le contexte du store view,
• les donnees liees au client, au quote, a la commande ou au produit si l integration les ajoute.

Cela permet non seulement de voir qu une erreur est apparue, mais aussi de distinguer un probleme de checkout d un probleme d integration ou d une erreur dans le panneau d administration.

2. Surveillance du frontend JavaScript

De nombreuses pannes critiques dans Magento n apparaissent pas en PHP, mais dans le navigateur :

• une erreur RequireJS,
• un probleme avec un composant Knockout,
• des XHR en echec dans le checkout,
• une Promise rejection non geree,
• une erreur dans un widget personnalise sur la PDP ou dans le panier.

Le Sentry Browser SDK peut enregistrer cela avec les breadcrumbs, les requetes reseau, l URL de la page, l environnement et le release. En pratique, cela donne une image bien meilleure de ce que l utilisateur voit reellement.

3. Performance Monitoring et tracing

Sentry peut collecter des transactions et des spans, ce qui permet d analyser :

• la duree des requetes HTTP,
• les commandes CLI lentes,
• les cron jobs longs ou instables,
• les appels HTTP externes depuis le backend,
• les appels AJAX et fetch dans le navigateur.

Cela ne remplace pas un APM complet au niveau de l infrastructure, mais dans les projets Magento c est tres precieux pour le diagnostic, car cela relie performance, contexte applicatif et release.

4. Surveillance du checkout

Le checkout est la zone technique la plus importante d une boutique. C est la que les erreurs coutent le plus. Sentry peut etre utilise pour :

• enregistrer les erreurs dans les etapes du checkout,
• taguer le mode de paiement et de livraison,
• ajouter des breadcrumbs pour les appels AJAX declenches par le checkout,
• analyser les problemes autour de placeOrder,
• Session Replay pour les sessions qui se terminent par une erreur.

Cela se traduit directement par un temps de diagnostic plus court pour les problemes qui impactent la conversion.

5. Cron Monitoring et check-ins

Magento s appuie fortement sur cron. C est lui qui execute de nombreux processus que l utilisateur ne voit pas directement :

• exports et imports,
• synchronisations avec des systemes externes,
• generation d alertes,
• nettoyage des donnees,
• taches d indexation et de maintenance.

Sentry permet de surveiller les check-ins cron, leur temps d execution et leur statut. On peut ainsi remarquer rapidement qu une tache ne s execute plus, dure trop longtemps ou se termine en erreur.

6. Release tracking et source maps

L une des plus grandes valeurs de Sentry est de rattacher les erreurs a un deploiement concret. Si le release est defini de maniere coherente pour le backend, le frontend et les source maps, l equipe peut :

• distinguer une ancienne erreur d une regression apres le dernier deploy,
• restreindre plus vite le perimetre des changements,
• symboliser correctement les stack traces des assets frontend,
• evaluer l impact d un release donne sur la stabilite de la boutique.

Dans les projets Magento, c est particulierement important, car le deployment inclut souvent en meme temps le backend, le static content et les integrations.

Qu est-ce que le module Kowal_Sentry

Kowal_Sentry est un module Magento 2 de production qui integre la boutique avec Sentry cote backend et frontend. Il a ete concu comme une couche d integration conforme a l architecture Magento :

Le module est disponible ici : Kowal_Sentry for Magento 2.

• sans modification du core,
• avec usage de la dependency injection,
• avec des plugins autour des points d entree clefs de l application,
• avec configuration via Stores -> Configuration,
• avec separation du backend et du frontend,
• avec un fort accent sur la securite des donnees.

Ce n est pas un simple helper qui envoie une exception. C est un ensemble de mecanismes qui relient PHP SDK, Browser SDK, strategie de release, context providers, sanitisation et surveillance des processus Magento.

Comment l integration fonctionne exactement dans notre module

Bootstrap du backend PHP

Le module initialise le PHP SDK une fois par requete ou par processus. Pendant le bootstrap, il definit notamment :

• dsn,
• environment,
• release,
• sample_rate,
• traces_sample_rate,
• profiles_sample_rate,
• enable_logs,
• send_default_pii,
• des hooks before_send,
• des hooks de sanitisation pour les breadcrumbs, transactions, check-ins, logs et metriques.

Cela compte, car la politique de ce qui peut etre envoye a Sentry et de ce qui doit etre filtre ou redacte est definie des l entree.

Transactions pour les requetes HTTP

Le plugin autour de Magento\Framework\App\Http enveloppe la requete dans une transaction de type http.server. La transaction est nommee a partir de la requete Magento et recoit des tags et des donnees comme :

• route_name,
• full_action_name,
• chemin de la requete,
• methode HTTP,
• area_code.

Si la requete se termine par une exception, le module la remonte a Sentry et ferme la transaction avec un statut d erreur.

Surveillance CLI

Le plugin autour de Magento\Framework\Console\Cli demarre des transactions de type cli.command pour les commandes bin/magento. Cela apporte de l observabilite pour :

• les reindexations,
• les imports,
• les taches lancees manuellement,
• les commandes d integration personnalisees.

En pratique, c est tres utile en staging et en production, ou les problemes CLI ne sont pas toujours visibles dans la supervision standard de l application.

Surveillance des cron et check-ins

Le plugin autour de Magento\Cron\Model\Observer lance une transaction cron.job, remonte le temps d execution de la tache et envoie des check-ins a Sentry. Cela permet de :

• surveiller tous les cron ou seulement certains job_code,
• definir un timeout par tache,
• definir une duree maximale attendue,
• construire des noms de moniteurs coherents via un slug prefix,
• auto-enregistrer le moniteur au premier check-in si besoin.

C est l une des parties les plus solides de l integration, car elle relie la supervision technique de Sentry au mode de fonctionnement reel de Magento.

Instrumentation du checkout

Le plugin autour de Magento\Quote\Model\QuoteManagement::placeOrder() ajoute des breadcrumbs et remonte les exceptions liees a la finalisation de la commande. L evenement peut ainsi contenir un contexte supplementaire, par exemple :

• cart_id,
• payment_method,
• les informations necessaires pour diagnostiquer plus vite les incidents du checkout.

Cote frontend, le module peut aussi suivre les breadcrumbs du checkout et les erreurs AJAX, ce qui donne ensemble une vision plus coherente du parcours de commande.

Spans et breadcrumbs pour les appels HTTP via le client Curl

Le plugin autour de Magento\Framework\HTTP\Client\Curl ajoute un span http.client pour les appels GET, POST, PUT et DELETE. Sont enregistres notamment :

• l URL,
• la methode,
• l hote,
• le statut de la reponse,
• le breadcrumb correspondant a l appel.

C est utile pour diagnostiquer les integrations avec des API externes, ou l erreur ne vient pas de Magento lui-meme, mais du temps de reponse, d un probleme d autorisation ou d un payload invalide cote partenaire.

Browser SDK pour storefront et admin

Cote navigateur, le module charge dynamiquement le Browser SDK via Magento et RequireJS. L initialisation inclut :

• dsn,
• environment,
• release,
• tracesSampleRate,
• Replay,
• User Feedback,
• tracePropagationTargets,
• beforeSend avec sanitisation de l evenement.

En plus, le module :

• se branche sur les erreurs RequireJS,
• ajoute des breadcrumbs AJAX,
• definit des tags et contextes Magento,
• initialise l instrumentation du checkout uniquement sur checkout_index_index,
• peut fonctionner sur le storefront et optionnellement dans l admin.

Strategie de release

Notre module prend en charge quatre strategies de release :

• manual,
• env,
• file,
• generated.

En pratique, cela signifie que l integration peut s adapter aussi bien a un deploiement manuel simple qu a un CI/CD mature. Le module prend egalement en charge des variables d environnement telles que :

• KOWAL_SENTRY_RELEASE,
• SENTRY_RELEASE,
• RELEASE_NAME,
• GIT_COMMIT.

Si le release n est pas fourni de l exterieur, le module peut le generer a partir de la version Magento, de la version du module et du hash court du commit.

Sanitisation et confidentialite

L un des elements les plus importants de l integration est le sanitiseur d evenements. Dans notre module, la sanitisation couvre :

• les headers de requete,
• les cookies,
• le body POST,
• les query params,
• les contextes et extra,
• les tags,
• user,
• les breadcrumbs,
• les logs,
• les metriques.

Selon la configuration, le module peut :

• bloquer Authorization,
• bloquer les cookies,
• supprimer les bodies des requetes,
• masquer les donnees client,
• anonymiser l IP,
• rediger des cles sensibles supplementaires comme token, api_key, customer_email.

En e-commerce, ce n est pas un supplement. C est une condition d une integration correcte.

Portee de la configuration du module

La configuration est disponible dans le panneau Magento :

Stores -> Configuration -> Kowal -> Sentry

La configuration a ete volontairement decoupee en sections correspondant a differents aspects de l observabilite.

1. General

La section de base controle l activation du module et les parametres communs :

• activation ou desactivation globale du module,
• Environment,
• Release Strategy,
• Release Name Override,
• Project Name,
• Debug Mode,
• commandes CLI de test.

Cette section pose les fondations du diagnostic. Sans environment et release corrects, les donnees dans Sentry ont moins de valeur, car il devient plus difficile de distinguer les environnements et les deploiements.

2. Backend SDK

Ici se configure la supervision cote PHP :

• Backend DSN,
• Error Sample Rate,
• Trace Sample Rate,
• Profile Sample Rate,
• Enable Logs,
• Enable Metrics API,
• Enable Cron Monitoring,
• Enable CLI Monitoring,
• Enable Adminhtml Monitoring,
• Enable API Monitoring.

Cette section decide si la boutique remonte les exceptions backend et le tracing, ainsi que de l ampleur de l observation pour les processus s executant hors storefront.

Il faut garder a l esprit que les metriques backend dans sentry/sentry 4.24.x sont considerees comme depreciees ou no-op. Le champ Enable Metrics API doit donc etre vu comme une facade de compatibilite du module, et non comme un pipeline complet de metriques backend.

3. Frontend SDK

La section frontend concerne le Browser SDK :

• Frontend DSN,
• Enable Storefront JS,
• Enable Admin JS,
• JS Trace Sample Rate,
• JS Replay Session Sample Rate,
• JS Replay On Error Sample Rate,
• Enable Session Replay,
• Enable User Feedback Widget,
• Enable Checkout Instrumentation,
• Enable Ajax Instrumentation,
• Browser SDK CDN URL.

Cette separation est tres importante. Dans de nombreux projets Magento, les besoins d observabilite du storefront et de l admin sont differents, c est pourquoi le module permet de les gerer separement.

4. Privacy / Security

Cette section definit la politique de securite des donnees :

• Send Default PII,
• Anonymize IP,
• Mask Customer Data,
• Mask Checkout Fields,
• Mask Payment Fields,
• Block Authorization Headers,
• Block Cookies,
• Block POST Bodies,
• Redact Query Params,
• Additional Redacted Keys,
• Replay Mask Selectors,
• Replay Block Selectors,
• Allowed Domains for Replay Network Details.

C est une section critique dans toute mise en oeuvre en production. Des reglages d observabilite trop permissifs peuvent conduire a envoyer vers Sentry des donnees qui ne devraient jamais s y retrouver.

5. Filtering

La section de filtrage permet de reduire le bruit :

• regex pour ignorer les exceptions,
• regex pour ignorer les URL,
• transactions ignorees,
• filtrage des bots,
• filtrage des health checks,
• filtrage d une partie du trafic admin,
• filtrage d une partie des erreurs d assets statiques.

Dans un projet bien maintenu, le filtrage n est pas optionnel. Sans cela, l equipe perd tres vite la qualite du signal dans Sentry.

6. Context

Ici, nous definissons la quantite de contexte metier Magento jointe aux evenements :

• contexte store,
• contexte website,
• contexte client,
• contexte quote,
• totaux du panier,
• contexte commande,
• contexte produit,
• contexte categorie,
• mode de paiement et de livraison,
• version du module,
• version Magento,
• metadonnees de deploiement.

Cette section est particulierement precieuse dans les projets avec un checkout complexe et de nombreuses integrations, car elle permet de repondre beaucoup plus vite a la question de savoir qui et quoi est impacte.

7. Source Maps / Release

La section release et source maps organise les donnees necessaires au workflow de release frontend :

• flag d utilisation des source maps,
• mode d upload des source maps,
• Assets Base URL,
• Release Dist,
• Organization,
• Project Slug,
• Release File Path.

Le module lui-meme n upload pas les source maps pendant le runtime Magento. Et c est une bonne chose. Cela doit etre gere par le pipeline CI/CD, par exemple via sentry-cli.

8. User Feedback

La section feedback permet de controler le widget cote navigateur :

• theme du widget,
• langue,
• ouverture automatique pour certaines erreurs,
• presence sur la success page,
• presence sur la contact page,
• trigger dans le footer,
• selecteur de trigger personnalise.

Cette fonction est utile lorsque l equipe souhaite recuperer plus rapidement des signaux des utilisateurs finaux sans construire un mecanisme separe de signalement technique.

9. Cron Monitoring

La section cron structure la supervision des taches Magento :

• auto-enregistrement des moniteurs,
• liste des job_code surveilles,
• seuil de timeout par tache,
• runtime maximal par tache,
• prefixe de slug des moniteurs.

C est important car, en pratique, tous les cron ne sont pas egalement critiques. Le module permet de concentrer la supervision sur les processus qui ont un impact reel sur les ventes, les integrations et la continuite de fonctionnement de la boutique.

A quoi ressemble un scenario de mise en oeuvre raisonnable

En pratique, le processus recommande ressemble a ceci :

1. Demarrer la supervision backend avec une politique de confidentialite restrictive.
2. Ajouter la supervision frontend pour le storefront.
3. Activer le tracing avec un sample rate modere.
4. Activer la surveillance cron pour les taches les plus importantes.
5. Configurer une strategie de release coherente avec le deploiement.
6. Ajouter les source maps dans le CI/CD.
7. Etendre Replay et le feedback seulement ensuite.

Cet ordre a du sens, car il permet d abord de construire un signal de diagnostic stable et securise, puis d augmenter seulement apres le niveau de detail des donnees.

Ce que cette integration apporte a l equipe technique

Du point de vue de l equipe de maintenance, un Kowal_Sentry bien configure apporte une valeur tres concrete :

• detection plus rapide des incidents apres deploiement,
• temps de diagnostic plus court pour les erreurs de checkout,
• meilleure visibilite sur les problemes d integrations HTTP,
• supervision des processus cron et CLI,
• contexte coherent entre backend et frontend,
• plus grand controle sur la qualite des donnees envoyees a un outil externe.

Dans les projets Magento, cela signifie generalement moins de temps passe a reproduire manuellement une erreur et un passage plus rapide du symptome a la cause.

Limitations a connaitre

Aucune integration d observabilite n est totalement sans conditions. Dans le cas de notre module, il faut garder en tete quelques points :

• les metriques backend du SDK PHP Sentry actuel ne doivent pas etre considerees comme un pipeline complet de metriques,
• User Feedback est parfois marque dans Sentry comme beta ou experimental,
• Replay doit etre mis en place avec prudence et toujours avec un masquage fort,
• un sampling trop large en production augmente rapidement le volume de donnees et les couts.

Ces limitations ne disqualifient pas la solution. Elles exigent simplement une configuration consciente.

Resume

Sentry dans Magento 2 a du sens lorsqu il est implemente comme une couche complete d observabilite, et non uniquement comme un simple mecanisme d envoi d exceptions. C est exactement le role de Kowal_Sentry. Il relie backend PHP, frontend JavaScript, tracing, checkout, supervision cron, strategie de release et sanitisation des donnees dans un module Magento coherent.

Grace a cela, l equipe technique dispose d un veritable outil pour maintenir et faire evoluer la boutique : avec une meilleure visibilite sur les erreurs, un diagnostic plus rapide des regressions et un plus grand controle sur la stabilite du processus de vente.

Sources

• Sentry for PHP: https://docs.sentry.io/platforms/php/
• Sentry for JavaScript Browser: https://docs.sentry.io/platforms/javascript/guides/browser/
• Sentry Session Replay: https://docs.sentry.io/platforms/javascript/session-replay/
• Sentry User Feedback: https://docs.sentry.io/platforms/javascript/user-feedback/
• Sentry Crons for PHP: https://docs.sentry.io/platforms/php/crons/
• Sentry Environments and configuration: https://docs.sentry.io/platforms/javascript/configuration/environments/