Kowal_Sentry : guide d’installation et de configuration

Objectif du module

Kowal_Sentry intègre Magento 2 avec Sentry et permet de surveiller :

• les erreurs backend PHP,
• les erreurs JavaScript sur le storefront et, en option, dans le panneau d’administration,
• les transactions HTTP, CLI et cron,
• les breadcrumbs du checkout,
• Session Replay,
• User Feedback,
• release tracking et préparation aux source maps.

Le module a été préparé comme un package Composer et doit fonctionner depuis l’emplacement vendor/kowal/module-sentry.

Exigences

• Magento Open Source / Adobe Commerce 2.4.x
• PHP 8.1+
• accès à Sentry et à au moins un projet
• token GitHub si le dépôt est installé via un vcs privé

Installation

Les commandes ci-dessous ont été copiées depuis README.md.

composer config repositories.sentry vcs https://github.com/kowalco/sentrycomposer config --global --auth github-oauth.github.com composer require kowal/module-sentrybin/magento module:enable Kowal_Sentrybin/magento setup:upgradebin/magento cache:flush

Important

• Le package Composer doit fonctionner uniquement depuis vendor/kowal/module-sentry.
• Il ne faut pas conserver simultanément le même module dans app/code/Kowal/Sentry.
• Après l’installation, vous trouverez la configuration dans :

Stores -> Configuration -> Kowal -> Sentry

Démarrage rapide

Configuration minimale nécessaire pour lancer le module :

1. Définissez Enable Module = Yes.
2. Définissez Environment, par exemple production ou staging.
3. Activez Enable Backend Monitoring et collez le Backend DSN.
4. Si vous souhaitez surveiller le frontend, activez Enable Frontend Monitoring et collez le Frontend DSN.
5. Enregistrez la configuration et videz le cache si cela est nécessaire dans l’environnement concerné.

Où trouver les données dans Sentry

DSN

Vous trouverez généralement le DSN ici :

Settings -> Projects -> [projekt] -> Client Keys (DSN)

Dans les champs Backend DSN et Frontend DSN, collez uniquement l’URL DSN elle-même, par exemple :

https://examplePublicKey@o0000000000000000.ingest.de.sentry.io/0000000000000000

Ne collez pas tout le snippet :

Sentryinit([ 'dsn' => 'https://examplePublicKey@o0000000000000000.ingest.de.sentry.io/0000000000000000',]);

Organization

Le slug de l’organisation se lit le plus facilement depuis l’URL du panneau Sentry, par exemple :

https://sentry.io/settings/acme/projects/shop-frontend/

Dans cet exemple :

• acme correspond à Organization
• shop-frontend correspond à Project Slug

Project Slug

Vous pouvez le lire :

• depuis l’URL du projet dans le panneau Sentry,
• ou depuis Settings -> Projects -> [projekt] -> Details

Auth token pour les source maps

Si vous utilisez sentry-cli, il est préférable de conserver le token en dehors de Magento, par exemple dans une variable d’environnement :

SENTRY_AUTH_TOKEN

Création du token :

• Settings -> Custom Integrations
• ou User Settings -> Personal Tokens

Vérification après installation

Après la configuration de base, vous pouvez vérifier si le module est actif et si le SDK fonctionne. Les commandes smoke-test ci-dessous ont été copiées depuis README.md.

Après avoir activé Enable Test Commands :

bin/magento kowal:sentry:test:errorbin/magento kowal:sentry:test:transactionbin/magento kowal:sentry:test:checkinbin/magento kowal:sentry:test:log

Configuration dans le panneau Magento

Chemin :

Stores -> Configuration -> Kowal -> Sentry

Vous trouverez ci-dessous la description des différentes sections, possibilités et variantes de paramètres.

Section General

Cette section contrôle l’activation du module, l’environnement et la méthode de calcul de release.

Enable Module

• Yes : active le module globalement.
• No : le backend et le frontend ne seront pas initialisés, même si d’autres options sont activées.

Recommandation :

• Yes dans l’environnement depuis lequel vous souhaitez envoyer des données à Sentry.

Environment

Exemples :

• production
• staging
• development

Variantes :

• un nom commun pour toute l’instance,
• des valeurs différentes par website/store view si vous avez besoin de séparer les events.

Recommandation :

• sans espaces ni barres obliques,
• conservez une nomenclature constante entre backend, frontend et CI/CD.

Release Strategy

Variantes disponibles :

• manual : la release provient du champ Release Name Override
• env : la release est récupérée depuis les variables d’environnement
• file : la release est lue depuis un fichier
• generated : la release est construite automatiquement par le module

Quand l’utiliser :

• manual : lorsque vous souhaitez saisir la release manuellement, plutôt en dépannage ou pour des déploiements simples
• env : idéal en CI/CD lorsque la release est transmise par le deployment
• file : adapté lorsque le deployment enregistre l’identifiant de version dans un fichier partagé
• generated : adapté pour démarrer si vous n’avez pas encore de pipeline release mature

Variables d’environnement prises en charge :

• KOWAL_SENTRY_RELEASE
• SENTRY_RELEASE
• RELEASE_NAME
• GIT_COMMIT

Release Name Override

Utilisé uniquement avec la stratégie manual.

Exemple :

magento-store@2.4.7-p1+20260410.1

Recommandation :

• exactement la même valeur doit être utilisée lors de l’upload des source maps.

Project Name

Nom de projet auxiliaire dans les contextes du module. Ce n’est pas le Project Slug de Sentry.

Variantes :

• nom de l’instance de la boutique,
• nom du groupe de boutiques,
• nom du projet interne.

Debug Mode

• Yes : journalisation diagnostique plus détaillée
• No : mode production

Recommandation :

• No en production,
• Yes temporairement lorsque vous diagnostiquez la configuration.

Enable Test Commands

• Yes : rend disponibles les commandes de test bin/magento
• No : les masque en fonctionnement normal

Recommandation :

• Yes sur staging ou pendant les tests,
• No dans une configuration de production permanente.

Section Backend SDK

Concerne le PHP SDK utilisé par storefront HTTP, admin, API, cron et CLI.

Enable Backend Monitoring

• Yes : active le monitoring du backend
• No : le backend n’envoie pas d’erreurs ni de traces à Sentry

Backend DSN

C’est le DSN principal pour le PHP SDK.

Variantes :

• projet Sentry séparé uniquement pour le backend
• même projet pour le backend et le frontend

Recommandation :

• sur les déploiements plus matures, conservez des projets backend et frontend séparés,
• dans les installations plus petites, vous pouvez commencer avec un seul projet commun.

Error Sample Rate

Plage : 0-1

Exemples :

• 1 : envoyer toutes les erreurs
• 0.5 : envoyer environ la moitié
• 0.25 : envoyer environ 25%

Recommandation :

• généralement 1.0 pour les erreurs, au moins au départ.

Trace Sample Rate

Plage : 0-1

Exemples :

• 0.05 : sampling faible, adapté à la production avec un trafic important
• 0.1 : point de départ raisonnable
• 0.2 : plus de données au prix d’un volume plus élevé

Recommandation :

• en production, généralement 0.05-0.2, selon le trafic et le plan Sentry.

Profile Sample Rate

Plage : 0-1

Variantes :

• 0 : profiling désactivé
• valeur basse, par exemple 0.01 : diagnostic périodique des performances

Recommandation :

• 0 ou valeur très faible en production.

Enable Logs

• Yes : envoie les structured logs
• No : pas de logs dans Sentry

Quand l’activer :

• lorsque vous souhaitez corréler les logs avec les traces et les erreurs.

Enable Metrics API

• Yes : active la façade du module pour les métriques
• No : les métriques côté module ne seront pas actives

Remarque :

• la version actuelle sentry/sentry 4.24.x traite les backend metrics comme une API en voie d’abandon / no-op.

Enable Cron Monitoring

• Yes : envoie les check-ins et transactions cron
• No : les crons ne seront pas surveillés par Sentry

Vous trouverez les données dans Sentry, dans la section :

• Crons
• Monitors

Enable CLI Monitoring

• Yes : surveille les commandes bin/magento
• No : pas de monitoring des processus CLI

Utile pour :

• les imports,
• les réindexations,
• les commandes d’intégration personnalisées.

Enable Adminhtml Monitoring

• Yes : surveille les requêtes du panneau d’administration
• No : limite le backend au storefront, à l’API, à cron et au CLI

Enable API Monitoring

• Yes : surveille REST, GraphQL et les autres endpoints
• No : exclut la partie intégration du monitoring

Section Frontend SDK

Concerne le Browser SDK chargé sur le storefront et, en option, dans le panneau admin.

Enable Frontend Monitoring

• Yes : charge le Browser SDK
• No : le frontend n’envoie pas de données à Sentry

Frontend DSN

Variantes :

• projet frontend séparé
• même DSN que le backend
• champ vide pour que le module tente un fallback vers Backend DSN

Recommandation :

• à terme, utilisez un projet frontend séparé si vous souhaitez des Issues, Replay et Performance lisibles.

Enable Storefront JS

• Yes : le Browser SDK fonctionne sur le storefront
• No : pas de SDK sur la partie publique de la boutique

Enable Admin JS

• Yes : le Browser SDK fonctionne également dans le panneau admin
• No : monitoring JS limité au storefront

Recommandation :

• activez uniquement lorsque vous diagnostiquez réellement des problèmes JS dans l’admin.

JS Trace Sample Rate

Plage : 0-1

Exemples :

• 0.01 : très prudent
• 0.05 : bon départ pour la production
• 0.1 : plus de données, volume plus élevé

JS Replay Session Sample Rate

Plage : 0-1

Exemples :

• 0 : pas de replay complet
• 0.01 : démarrage sécurisé
• 0.05 : plus de données pour analyser l’UX et les erreurs

JS Replay On Error Sample Rate

Plage : 0-1

Exemples :

• 1 : replay après chaque erreur dans la session
• 0.5 : replay après une partie des erreurs

Recommandation :

• souvent un meilleur point de départ qu’un sampling élevé de toutes les sessions.

Enable Session Replay

• Yes : active Replay
• No : pas d’enregistrement des sessions

Recommandation :

• activez avec un masquage fort du checkout et des paiements.

Enable User Feedback Widget

• Yes : le widget Feedback est disponible
• No : le widget n’est pas chargé

Remarque :

• selon le plan et le compte Sentry, la fonctionnalité peut être marquée comme beta / experimental.

Enable Checkout Instrumentation

• Yes : ajoute des breadcrumbs et des tags de checkout
• No : pas de contexte de checkout supplémentaire

Recommandation :

• il est généralement conseillé de laisser cette option activée.

Enable Ajax Instrumentation

• Yes : breadcrumbs pour AJAX / fetch / XHR
• No : moins de contexte pour les problèmes frontend

Browser SDK CDN URL

Par défaut, pointe vers le bundle officiel Sentry.

Variantes :

• URL par défaut du module
• miroir CDN personnalisé
• bundle spécifique / version spécifique épinglée

À modifier uniquement lorsque :

• vous épinglez une version du SDK,
• vous avez vos propres règles CSP,
• vous utilisez le mirroring des assets.

Section Privacy / Security

Cette section est responsable de la réduction du risque d’envoi de données sensibles.

Send Default PII

• Yes : le SDK peut envoyer l’ensemble par défaut de données utilisateur et de requête
• No : politique de confidentialité plus prudente

Recommandation :

• généralement No.

Anonymize IP

• Yes : ne transmet pas l’IP complète
• No : conserve le comportement standard

Recommandation :

• généralement Yes.

Mask Customer Data

• Yes : masque les données client
• No : moins de protection des données

Recommandation :

• pratiquement toujours Yes en production.

Mask Checkout Fields

• Yes : masque les champs du checkout
• No : risque de fuite de données du checkout

Recommandation :

• toujours Yes.

Mask Payment Fields

• Yes : masque les champs liés au paiement
• No : très risqué

Recommandation :

• toujours Yes.

Block Authorization Headers

• Yes : supprime ou masque Authorization et les tokens
• No : risque d’envoi de données d’authentification

Recommandation :

• toujours Yes.

Block Cookies

• Yes : supprime les cookies des données de l’event
• No : risque plus élevé de fuite de données de session

Recommandation :

• généralement Yes.

Block POST Bodies

• Yes : supprime les corps POST
• No : envoie davantage de données de requête

Recommandation :

• généralement Yes, en particulier pour le checkout, la connexion et les formulaires.

Redact Query Params

• Yes : masque les paramètres de query string
• No : la query string reste plus lisible, mais moins sécurisée

Additional Redacted Keys

Champ texte pour les clés supplémentaires à rédiger.

Exemples :

• token
• api_key
• customer_email
• external_customer_id

Vous pouvez les séparer par :

• des virgules,
• des espaces,
• des nouvelles lignes.

Replay Mask Selectors

Sélecteurs CSS dont le contenu doit être masqué dans Replay.

Exemples :

• .customer-email
• .field[name*='password']
• .payment-method

Replay Block Selectors

Sélecteurs CSS qui doivent être entièrement bloqués dans Replay.

Exemples :

• .checkout-container
• .payment-method iframe
• .opc-wrapper

Allowed Domains for Replay Network Details

Liste des domaines pour lesquels Replay peut joindre les détails des requêtes réseau.

Exemples :

• store.example.com
• api.example.com
• trusted-partner.example

Recommandation :

• indiquez uniquement vos propres domaines et des domaines de confiance.

Section Filtering

Cette section limite le bruit et le volume des événements.

Ignore Exceptions Regex

Une règle regex par ligne.

Exemples d’utilisation :

• erreurs techniques connues et non critiques,
• exceptions provenant d’intégrations externes déjà gérées autrement.

Ignore URLs Regex

Une règle regex par ligne.

Exemples :

• endpoints health-check,
• webhooks de test,
• ressources techniques.

Ignore Transactions

Un nom de transaction par ligne.

Recommandation :

• collectez d’abord les données,
• puis filtrez les transactions de faible valeur et répétitives.

Ignore Bots

• Yes : exclut le trafic des bots et crawlers
• No : vous surveillez également le trafic automatisé

Recommandation :

• Yes en cas de trafic SEO important.

Ignore Health Checks

• Yes : ignore /health, /status, /ping et similaires
• No : ces requêtes sont envoyées à Sentry

Ignore Admin Routes

• Yes : limite les événements provenant de l’admin
• No : l’admin reste surveillé

Ignore Static Resource Errors

• Yes : filtre une partie des erreurs d’assets .js et .css
• No : toutes les erreurs de ce type restent visibles

Recommandation :

• généralement Yes si vous ne souhaitez pas remplir le projet de bruit après les deploys.

Section Context

Contrôle la quantité de contexte métier ajoutée aux events.

Attach Store Context

• Yes : ajoute store_id, store_code, le nom de la boutique et la devise
• No : absence de ce contexte

Recommandation :

• Yes, en particulier en multistore.

Attach Website Context

• Yes : ajoute les données website
• No : absence de ce niveau d’identification

Attach Customer Context

• Yes : ajoute le contexte client anonymisé
• No : absence de données sur le statut du client

Attach Quote Context

• Yes : ajoute le contexte panier / quote
• No : moins de données pour diagnostiquer le checkout

Attach Cart Totals

• Yes : ajoute les totaux du panier
• No : event plus léger

Recommandation :

• activez uniquement si ces données aident réellement à l’analyse.

Attach Order Context

• Yes : ajoute le contexte de la commande
• No : absence de données sur l’order flow

Particulièrement utile pour :

• invoice,
• shipment,
• e-mails transactionnels,
• intégrations ERP / OMS.

Attach Product Context

• Yes : ajoute le contexte produit de base
• No : absence de ce contexte

Attach Category Context

• Yes : ajoute le contexte catégorie de base
• No : absence de ce contexte

Attach Payment / Shipping Method

• Yes : ajoute payment_method et shipping_method
• No : moins de données pour le checkout

Recommandation :

• c’est l’un des paramètres de diagnostic les plus précieux.

Attach Module Version

• Yes : ajoute la version de Kowal_Sentry
• No : sans cette information dans les events

Attach Magento Version

• Yes : ajoute la version de Magento
• No : sans contexte de plateforme

Attach Deployment Metadata

• Yes : ajoute des données supplémentaires sur le deploy si elles sont disponibles
• No : absence de ces métadonnées

Utile lorsque vous souhaitez relier rapidement un problème à un rollout ou à un build précis.

Section Source Maps / Release

Cette section organise les paramètres nécessaires aux release et source maps. L’upload lui-même doit être effectué dans CI/CD, et non pendant le runtime Magento.

Enable Source Map Upload

• Yes : confirme que vous utilisez organisationnellement les source maps
• No : le module ne suppose pas de source maps dans la configuration

Remarque :

• il s’agit d’un flag de configuration, pas d’un mécanisme d’upload.

Source Map Upload Mode

Variantes :

• manual : commandes sentry-cli manuelles
• ci : upload dans le pipeline CI/CD
• deploy_hook : upload dans un hook de deployment

Recommandation :

• en production, le plus souvent ci.

Assets Base URL

Exemple :

https://store.example.com/static/frontend

Cette valeur doit correspondre à ce que le Browser SDK voit dans la stack trace. Sinon, les source maps ne seront pas associées.

Release Dist

dist optionnel pour la release.

Exemples :

• storefront
• admin
• pl-store

À utiliser lorsqu’une même release comporte plusieurs variantes d’assets.

Organization

Slug de l’organisation utilisé par sentry-cli et l’API.

Comment le trouver :

• depuis l’URL du panneau Sentry,
• par exemple https://sentry.io/settings/acme/projects/shop-frontend/ -> acme

Project Slug

Slug du projet utilisé par le workflow release et source maps.

Comment le trouver :

• depuis l’URL du projet,
• ou Settings -> Projects -> [projekt] -> Details

Release File Path

Chemin vers le fichier contenant le nom de release avec la stratégie file.

Exemples :

• /var/www/shared/release.txt
• pub/media/deploy/release-id.txt

Section User Feedback

Configuration du widget de signalement de problèmes côté navigateur.

Widget Theme

Variantes :

• light
• dark
• system

Recommandation :

• généralement system.

Widget Language

Exemples :

• pl-PL
• en-US

Recommandation :

• en multistore, adaptez au locale du store view.

Auto-open after selected errors

• Yes : après certaines erreurs frontend, une proposition de feedback peut apparaître
• No : le widget ne s’ouvre pas automatiquement

Recommandation :

• à utiliser avec prudence afin de ne pas être trop intrusif pour l’utilisateur.

Show on checkout success

• Yes : le trigger Feedback peut apparaître sur la page de succès de commande
• No : pas de trigger à cet endroit

Show on contact page

• Yes : trigger ou widget sur la page de contact
• No : pas d’exposition sur la contact page

Show in footer

• Yes : trigger visible en permanence dans le pied de page ou comme élément fixe de la page
• No : pas de trigger permanent

C’est l’option la plus simple si vous souhaitez disposer d’un bouton Zglos problem.

Custom Trigger Selector

Sélecteur CSS d’un élément existant ouvrant Feedback.

Exemples :

• #report-issue
• .js-sentry-feedback

Utilisez ce champ si vous souhaitez connecter le widget à votre propre bouton dans le layout ou dans un bloc CMS.

Section Cron Monitoring

Cette section contrôle les check-ins et monitors pour les crons Magento.

Enable auto-registration of configured cron jobs

• Yes : le premier check-in peut créer ou mettre à jour un monitor dans Sentry
• No : le module envoie les check-ins sans auto-configuration du monitor

Recommandation :

• Yes si vous disposez d’un deployment contrôlé et de jobs définis consciemment.

Monitored job codes

Liste des job_code Magento.

Vous pouvez les séparer par :

• des virgules,
• des espaces,
• des nouvelles lignes.

Variantes :

• champ vide : surveiller tous les crons
• liste de job_code sélectionnés : surveiller uniquement les tâches critiques

Exemples :

• sales_clean_quotes
• catalog_product_alert
• indexer_reindex_all_invalid

Timeout threshold per job

Une règle par ligne :

job_code:minutes

Exemple :

catalog_product_alert:10

À utiliser lorsqu’un cron s’exécute de manière irrégulière et que vous souhaitez limiter les fausses alertes.

Max runtime per job

Une règle par ligne :

job_code:minutes

Exemple :

indexer_reindex_all_invalid:30

Après dépassement de la limite, Sentry peut marquer le monitor comme problématique.

Check-in slug prefix

Exemple :

magento-

Utile lorsqu’une organisation Sentry surveille plusieurs instances Magento et que vous souhaitez éviter les collisions de noms.

Profils de configuration recommandés

Démarrage de production sécurisé

• Enable Module = Yes
• Enable Backend Monitoring = Yes
• Enable Frontend Monitoring = Yes
• Error Sample Rate = 1
• Trace Sample Rate = 0.05 ou 0.1
• JS Trace Sample Rate = 0.01 ou 0.05
• Enable Session Replay = Yes
• JS Replay Session Sample Rate = 0.01
• JS Replay On Error Sample Rate = 1
• Send Default PII = No
• Anonymize IP = Yes
• Mask Customer Data = Yes
• Mask Checkout Fields = Yes
• Mask Payment Fields = Yes
• Block Authorization Headers = Yes
• Block Cookies = Yes
• Block POST Bodies = Yes
• Redact Query Params = Yes
• Ignore Bots = Yes
• Ignore Health Checks = Yes

Profil de diagnostic sur staging

• Trace Sample Rate plus élevé, par exemple 0.2
• JS Trace Sample Rate plus élevé, par exemple 0.1
• temporairement Debug Mode = Yes
• Enable Test Commands = Yes
• prudence avec Replay : conservez toujours le masquage et les blocages

Variante minimale backend uniquement

• Enable Backend Monitoring = Yes
• Backend DSN renseigné
• Enable Frontend Monitoring = No

C’est une bonne première étape si vous souhaitez d’abord lancer le monitoring des exceptions et des crons côté PHP.

Erreurs de configuration les plus fréquentes

• Coller tout le snippet Sentryinit(...) au lieu du seul DSN.
• Présence simultanée du module dans vendor/ et app/code/.
• Valeurs différentes de release entre les events et les source maps.
• Sampling Replay trop agressif en production.
• Désactivation du masquage du checkout et des paiements.
• Conservation du DSN d’exemple dans une configuration active.

Résumé

Le plus sûr est de commencer par le monitoring du backend, un monitoring prudent du frontend et des paramètres de confidentialité restrictifs. Lorsque les données dans Sentry deviennent stables et lisibles, vous pouvez augmenter progressivement le trace sampling, Replay et l’étendue du contexte métier.