Kowal_Sentry : guide d’installation et de configuration

Objectif du module

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

• les erreurs du 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 pour les source maps.

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

Prérequis

• Magento Open Source / Adobe Commerce 2.4.x
• PHP 8.1+
• accès à Sentry et au moins un projet
• adresse e-mail du client et token de licence pour le dépôt Composer Kowal

Installation

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

Les données d’accès au dépôt Composer, c’est-à-dire l’adresse e-mail du client et le token de licence, vous seront envoyées par e-mail après l’achat. Elles sont également disponibles dans l’espace client après connexion sur kowal.store. Remplacez TWOJ_EMAIL_KLIENTA par l’adresse e-mail de votre compte et TWOJ_TOKEN par le token reçu. Exécutez les commandes dans le répertoire racine de Magento.

composer config repositories.kowal composer https://repo.kowal.storecomposer config http-basic.repo.kowal.store 'TWOJ_EMAIL_KLIENTA' 'TWOJ_TOKEN'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 ex. production ou staging.
3. Activez Enable Backend Monitoring et collez Backend DSN.
4. Si vous souhaitez surveiller le frontend, activez Enable Frontend Monitoring et collez 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 le snippet complet :

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

Organization

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

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

Dans cet exemple :

• acme est Organization
• shop-frontend est 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 activation de 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 réglages.

Section General

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

Enable Module

• Yes : lance 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 sur 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 devez séparer les événements.

Recommandation :

• sans espaces ni barres obliques,
• gardez 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 de 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 :

• la même valeur exacte 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 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 la 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

Il s’agit du 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émarrage.

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 ex. 0.01 : diagnostic périodique des performances

Recommandation :

• 0 ou une valeur très basse en production.

Enable Logs

• Yes : envoie des 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 :

• actuellement, sentry/sentry 4.24.x traite les backend metrics comme une API en voie de suppression / 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 :

• imports,
• réindexations,
• 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, aux crons et à la CLI

Enable API Monitoring

• Yes : surveille REST, GraphQL et les autres endpoints
• No : coupe 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, 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 aussi 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 replays complets
• 0.01 : démarrage sûr
• 0.05 : plus de données pour l’analyse UX et des 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 de session

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 fonction peut être marquée comme beta / experimental.

Enable Checkout Instrumentation

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

Recommandation :

• il est généralement utile 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
• votre propre miroir CDN
• bundle concret / version concrète épinglé(e)

Ne modifiez que lorsque :

• vous épinglez la version du SDK,
• vous avez vos propres règles CSP,
• vous utilisez un 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 des données utilisateur et de requête
• No : politique de confidentialité plus prudente

Recommandation :

• généralement No.

Anonymize IP

• Yes : ne pas transmettre l’IP complète
• No : conserver 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’événement
• 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, notamment pour le checkout, la connexion et les formulaires.

Redact Query Params

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

Additional Redacted Keys

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

Exemples :

• token
• api_key
• customer_email
• external_customer_id

Vous pouvez les séparer par :

• virgules,
• espaces,
• 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 de 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 :

• n’indiquez que 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 dangereuses,
• exceptions provenant d’intégrations externes qui sont déjà traité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 : coupe le trafic des bots et crawlers
• No : vous surveillez aussi 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 voulez pas remplir le projet de bruit après les deploys.

Section Context

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

Attach Store Context

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

Recommandation :

• Yes, surtout en multistore.

Attach Website Context

• Yes : joint les données website
• No : pas de ce niveau d’identification

Attach Customer Context

• Yes : joint un contexte client anonymisé
• No : pas de données sur le statut du client

Attach Quote Context

• Yes : joint le contexte panier / quote
• No : moins de données pour le diagnostic du checkout

Attach Cart Totals

• Yes : joint les totaux du panier
• No : événement plus léger

Recommandation :

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

Attach Order Context

• Yes : joint le contexte de commande
• No : pas de données sur l’order flow

Particulièrement utile pour :

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

Attach Product Context

• Yes : joint un contexte produit de base
• No : pas de ce contexte

Attach Category Context

• Yes : joint un contexte catégorie de base
• No : pas de ce contexte

Attach Payment / Shipping Method

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

Recommandation :

• c’est l’un des réglages diagnostiques les plus utiles.

Attach Module Version

• Yes : joint la version Kowal_Sentry
• No : sans cette information dans les événements

Attach Magento Version

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

Attach Deployment Metadata

• Yes : joint des données supplémentaires sur le deploy, si disponibles
• No : pas de ces métadonnées

Utile lorsque vous souhaitez associer rapidement un problème à un rollout ou à un build spécifique.

Section Source Maps / Release

Cette section organise les paramètres nécessaires pour la release et les source maps. L’upload lui-même doit se faire dans le 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 :

• c’est un flag de configuration, pas 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 le 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 release possède 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 ex. 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 à la 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 footer 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 rattacher le widget à votre propre bouton dans le layout ou un CMS block.

Section Cron Monitoring

Cette section contrôle les check-ins et les 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 des 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 de job_code Magento.

Vous pouvez les séparer par :

• virgules,
• espaces,
• 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 façon 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 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 ex. 0.2
• JS Trace Sample Rate plus élevé, par ex. 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 commencer par activer le monitoring des exceptions et des crons côté PHP.

Erreurs de configuration les plus fréquentes

• Coller le snippet complet \Sentry\init(...) au lieu du DSN seul.
• Présence simultanée du module dans vendor/ et app/code/.
• Valeurs release différentes entre les événements 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é

Il est plus sûr de commencer par le monitoring du backend, un monitoring prudent du frontend et des réglages de confidentialité stricts. Lorsque les données dans Sentry deviennent stables et lisibles, vous pouvez augmenter progressivement le trace sampling, Replay et le périmètre du contexte métier.