Kowal_Sentry: istruzioni di installazione e configurazione

Obiettivo del modulo

Kowal_Sentry integra Magento 2 con Sentry e consente di monitorare:

• errori del backend PHP,
• errori JavaScript sullo storefront e, opzionalmente, nel pannello di amministrazione,
• transazioni HTTP, CLI e cron,
• checkout breadcrumbs,
• Session Replay,
• User Feedback,
• release tracking e preparazione per source maps.

Il modulo è stato preparato come pacchetto Composer e dovrebbe funzionare dalla posizione vendor/kowal/module-sentry.

Requisiti

• Magento Open Source / Adobe Commerce 2.4.x
• PHP 8.1+
• accesso a Sentry e ad almeno un progetto
• token GitHub, se il repository viene installato tramite vcs privato

Installazione

I comandi seguenti sono stati copiati da 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

Importante

• Il pacchetto Composer deve funzionare solo da vendor/kowal/module-sentry.
• Non bisogna mantenere contemporaneamente lo stesso modulo in app/code/Kowal/Sentry.
• Dopo l’installazione trovi la configurazione in:

Stores -> Configuration -> Kowal -> Sentry

Avvio rapido

Configurazione minima necessaria per avviare il modulo:

1. Imposta Enable Module = Yes.
2. Imposta Environment, per esempio production oppure staging.
3. Attiva Enable Backend Monitoring e incolla Backend DSN.
4. Se vuoi monitorare il frontend, attiva Enable Frontend Monitoring e incolla Frontend DSN.
5. Salva la configurazione e pulisci la cache, se necessario nell’ambiente specifico.

Dove trovare i dati in Sentry

DSN

Di solito trovi il DSN qui:

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

Nei campi Backend DSN e Frontend DSN incolla solo l’URL DSN, per esempio:

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

Non incollare l’intero snippet:

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

Organization

Lo slug dell’organizzazione si legge più facilmente dall’URL del pannello Sentry, per esempio:

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

In questo esempio:

• acme è Organization
• shop-frontend è Project Slug

Project Slug

Puoi ricavarlo:

• dall’URL del progetto nel pannello Sentry,
• oppure da Settings -> Projects -> [projekt] -> Details

Auth token per source maps

Se usi sentry-cli, è preferibile conservare il token fuori da Magento, per esempio in una variabile d’ambiente:

SENTRY_AUTH_TOKEN

Creazione del token:

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

Verifica dopo l’installazione

Dopo la configurazione di base puoi verificare se il modulo è attivo e se l’SDK funziona. I comandi smoke-test seguenti sono stati copiati da README.md.

Dopo aver attivato Enable Test Commands:

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

Configurazione nel pannello Magento

Percorso:

Stores -> Configuration -> Kowal -> Sentry

Di seguito la descrizione delle singole sezioni, funzionalità e varianti di impostazione.

Sezione General

Questa sezione gestisce l’attivazione del modulo, l’ambiente e il modo di calcolare release.

Enable Module

• Yes: avvia il modulo globalmente.
• No: backend e frontend non saranno inizializzati, anche se altre opzioni sono attive.

Raccomandazione:

• Yes nell’ambiente da cui vuoi inviare dati a Sentry.

Environment

Esempi:

• production
• staging
• development

Varianti:

• un unico nome comune per tutta l’istanza,
• valori diversi per website/store view, se hai bisogno di separare gli eventi.

Raccomandazione:

• senza spazi e senza slash,
• mantieni una nomenclatura costante tra backend, frontend e CI/CD.

Release Strategy

Varianti disponibili:

• manual: la release viene presa dal campo Release Name Override
• env: la release viene recuperata dalle variabili d’ambiente
• file: la release viene letta da un file
• generated: la release viene composta automaticamente dal modulo

Quando usarle:

• manual: quando vuoi inserire la release manualmente, piuttosto come soluzione di emergenza o in implementazioni semplici
• env: la scelta migliore in CI/CD, quando la release viene passata dal deployment
• file: utile quando il deployment salva l’identificatore di versione in un file condiviso
• generated: utile all’inizio, se non hai ancora una pipeline di release matura

Variabili d’ambiente supportate:

• KOWAL_SENTRY_RELEASE
• SENTRY_RELEASE
• RELEASE_NAME
• GIT_COMMIT

Release Name Override

Usato solo con la strategia manual.

Esempio:

magento-store@2.4.7-p1+20260410.1

Raccomandazione:

• lo stesso identico valore dovrebbe essere usato durante l’upload delle source maps.

Project Name

Nome ausiliario del progetto nei contesti del modulo. Non è il Project Slug di Sentry.

Varianti:

• nome dell’istanza dello store,
• nome del gruppo di store,
• nome del progetto interno.

Debug Mode

• Yes: logging diagnostico più dettagliato
• No: modalità produzione

Raccomandazione:

• No in produzione,
• Yes temporaneamente, quando diagnostichi la configurazione.

Enable Test Commands

• Yes: rende disponibili i comandi di test bin/magento
• No: li nasconde durante il normale funzionamento

Raccomandazione:

• Yes su staging o durante i test,
• No nella configurazione di produzione permanente.

Sezione Backend SDK

Riguarda il PHP SDK usato da storefront HTTP, admin, API, cron e CLI.

Enable Backend Monitoring

• Yes: attiva il monitoraggio del backend
• No: il backend non invia errori e trace a Sentry

Backend DSN

È il DSN principale per PHP SDK.

Varianti:

• progetto Sentry separato solo per il backend
• lo stesso progetto per backend e frontend

Raccomandazione:

• nelle implementazioni più mature, mantieni progetti separati per backend e frontend,
• nelle installazioni più piccole si può iniziare con un unico progetto condiviso.

Error Sample Rate

Intervallo: 0-1

Esempi:

• 1: invia tutti gli errori
• 0.5: invia circa la metà
• 0.25: invia circa il 25%

Raccomandazione:

• di solito 1.0 per gli errori, almeno all’inizio.

Trace Sample Rate

Intervallo: 0-1

Esempi:

• 0.05: sampling basso, adatto alla produzione con traffico elevato
• 0.1: punto di partenza ragionevole
• 0.2: più dati a costo di un volume maggiore

Raccomandazione:

• in produzione di solito 0.05-0.2, in base al traffico e al piano Sentry.

Profile Sample Rate

Intervallo: 0-1

Varianti:

• 0: profiling disattivato
• valore basso, per esempio 0.01: diagnostica periodica delle prestazioni

Raccomandazione:

• 0 o un valore molto basso in produzione.

Enable Logs

• Yes: invia structured logs
• No: nessun log in Sentry

Quando attivarlo:

• quando vuoi correlare i log con trace ed errori.

Enable Metrics API

• Yes: attiva la facciata del modulo per le metriche
• No: le metriche lato modulo non saranno attive

Nota:

• l’attuale sentry/sentry 4.24.x tratta le backend metrics come API in dismissione / no-op.

Enable Cron Monitoring

• Yes: invia check-in e transazioni cron
• No: i cron non saranno monitorati da Sentry

Troverai i dati in Sentry nella sezione:

• Crons
• Monitors

Enable CLI Monitoring

• Yes: monitora i comandi bin/magento
• No: nessun monitoraggio dei processi CLI

Utile per:

• import,
• reindicizzazioni,
• comandi di integrazione custom.

Enable Adminhtml Monitoring

• Yes: monitora le request del pannello di amministrazione
• No: limita il backend a storefront, API, cron e CLI

Enable API Monitoring

• Yes: monitora REST, GraphQL e altri endpoint
• No: esclude la parte di integrazione dal monitoraggio

Sezione Frontend SDK

Riguarda il Browser SDK caricato sullo storefront e, opzionalmente, nel pannello admin.

Enable Frontend Monitoring

• Yes: carica il Browser SDK
• No: il frontend non invia dati a Sentry

Frontend DSN

Varianti:

• progetto frontend separato
• lo stesso DSN del backend
• campo vuoto, per consentire al modulo di provare il fallback a Backend DSN

Raccomandazione:

• come obiettivo, un progetto frontend separato, se vuoi Issues, Replay e Performance più leggibili.

Enable Storefront JS

• Yes: il Browser SDK funziona sullo storefront
• No: nessun SDK nella parte pubblica dello store

Enable Admin JS

• Yes: il Browser SDK funziona anche nel pannello admin
• No: monitoraggio JS limitato allo storefront

Raccomandazione:

• attivalo solo quando diagnostichi realmente problemi JS nell’admin.

JS Trace Sample Rate

Intervallo: 0-1

Esempi:

• 0.01: approccio molto prudente
• 0.05: buon punto di partenza per la produzione
• 0.1: più dati, volume maggiore

JS Replay Session Sample Rate

Intervallo: 0-1

Esempi:

• 0: nessun replay completo
• 0.01: avvio sicuro
• 0.05: più dati per l’analisi di UX ed errori

JS Replay On Error Sample Rate

Intervallo: 0-1

Esempi:

• 1: replay dopo ogni errore nella sessione
• 0.5: replay dopo una parte degli errori

Raccomandazione:

• spesso è un punto di partenza migliore rispetto a un sampling elevato di tutte le sessioni.

Enable Session Replay

• Yes: attiva Replay
• No: nessuna registrazione delle sessioni

Raccomandazione:

• attivalo insieme a un forte mascheramento di checkout e pagamenti.

Enable User Feedback Widget

• Yes: il widget Feedback è disponibile
• No: il widget non viene caricato

Nota:

• a seconda del piano e dell’account Sentry, la funzionalità può essere indicata come beta / experimental.

Enable Checkout Instrumentation

• Yes: aggiunge breadcrumbs e tag di checkout
• No: nessun contesto di checkout aggiuntivo

Raccomandazione:

• di solito conviene lasciarlo attivo.

Enable Ajax Instrumentation

• Yes: breadcrumbs per AJAX / fetch / XHR
• No: meno contesto per i problemi frontend

Browser SDK CDN URL

Di default punta al bundle ufficiale Sentry.

Varianti:

• URL predefinito del modulo
• mirror CDN personalizzato
• bundle specifico / versione specifica fissata

Modificalo solo quando:

• fissi la versione del SDK,
• hai regole CSP personalizzate,
• usi il mirroring degli asset.

Sezione Privacy / Security

Questa sezione è responsabile della riduzione del rischio di invio di dati sensibili.

Send Default PII

• Yes: SDK può inviare il set predefinito di dati utente e request
• No: policy privacy più conservativa

Raccomandazione:

• di norma No.

Anonymize IP

• Yes: non trasmettere l’IP completo
• No: mantieni il comportamento standard

Raccomandazione:

• di solito Yes.

Mask Customer Data

• Yes: maschera i dati del cliente
• No: minore protezione dei dati

Raccomandazione:

• praticamente sempre Yes in produzione.

Mask Checkout Fields

• Yes: maschera i campi del checkout
• No: rischio di perdita di dati dal checkout

Raccomandazione:

• sempre Yes.

Mask Payment Fields

• Yes: maschera i campi legati al pagamento
• No: molto rischioso

Raccomandazione:

• sempre Yes.

Block Authorization Headers

• Yes: rimuove o maschera Authorization e token
• No: rischio di invio di dati di autenticazione

Raccomandazione:

• sempre Yes.

Block Cookies

• Yes: rimuove i cookie dai dati dell’evento
• No: rischio maggiore di perdita di dati di sessione

Raccomandazione:

• di solito Yes.

Block POST Bodies

• Yes: rimuove i body POST
• No: invia più dati della request

Raccomandazione:

• di solito Yes, soprattutto per checkout, login e form.

Redact Query Params

• Yes: maschera i parametri query string
• No: la query string resta più leggibile, ma meno sicura

Additional Redacted Keys

Campo di testo per chiavi aggiuntive da redigere.

Esempi:

• token
• api_key
• customer_email
• external_customer_id

Puoi separarle con:

• virgole,
• spazi,
• nuove righe.

Replay Mask Selectors

Selettori CSS il cui contenuto deve essere mascherato in Replay.

Esempi:

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

Replay Block Selectors

Selettori CSS che devono essere completamente bloccati in Replay.

Esempi:

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

Allowed Domains for Replay Network Details

Elenco di domini per i quali Replay può includere i dettagli delle request di rete.

Esempi:

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

Raccomandazione:

• inserisci solo domini propri e affidabili.

Sezione Filtering

Questa sezione limita il rumore e il volume degli eventi.

Ignore Exceptions Regex

Una regola regex per riga.

Esempi di utilizzo:

• errori tecnici noti e non pericolosi,
• eccezioni da integrazioni esterne che sono già gestite in altro modo.

Ignore URLs Regex

Una regola regex per riga.

Esempi:

• endpoint health-check,
• webhook di test,
• risorse tecniche.

Ignore Transactions

Un nome transazione per riga.

Raccomandazione:

• prima raccogli i dati,
• poi filtra le transazioni di scarso valore e ripetitive.

Ignore Bots

• Yes: esclude il traffico di bot e crawler
• No: monitori anche il traffico automatico

Raccomandazione:

• Yes con traffico SEO elevato.

Ignore Health Checks

• Yes: ignora /health, /status, /ping e simili
• No: tali request arrivano a Sentry

Ignore Admin Routes

• Yes: limita gli eventi dall’admin
• No: l’admin resta monitorato

Ignore Static Resource Errors

• Yes: filtra una parte degli errori degli asset .js e .css
• No: tutti gli errori di questo tipo restano visibili

Raccomandazione:

• di solito Yes, se non vuoi riempire il progetto di rumore dopo i deploy.

Sezione Context

Gestisce la quantità di contesto business aggiunto agli eventi.

Attach Store Context

• Yes: aggiunge store_id, store_code, nome dello store e valuta
• No: nessun contesto di questo tipo

Raccomandazione:

• Yes, soprattutto con multistore.

Attach Website Context

• Yes: aggiunge i dati website
• No: nessun livello di identificazione di questo tipo

Attach Customer Context

• Yes: aggiunge il contesto cliente anonimizzato
• No: nessun dato sullo stato del cliente

Attach Quote Context

• Yes: aggiunge il contesto carrello / quote
• No: meno dati per la diagnosi del checkout

Attach Cart Totals

• Yes: aggiunge i totali del carrello
• No: evento più leggero

Raccomandazione:

• attivalo solo quando questi dati aiutano realmente nell’analisi.

Attach Order Context

• Yes: aggiunge il contesto dell’ordine
• No: nessun dato sull’order flow

Particolarmente utile per:

• invoice,
• shipment,
• email transazionali,
• integrazioni ERP / OMS.

Attach Product Context

• Yes: aggiunge il contesto prodotto di base
• No: nessun contesto di questo tipo

Attach Category Context

• Yes: aggiunge il contesto categoria di base
• No: nessun contesto di questo tipo

Attach Payment / Shipping Method

• Yes: aggiunge payment_method e shipping_method
• No: meno dati per il checkout

Raccomandazione:

• è una delle impostazioni diagnostiche più preziose.

Attach Module Version

• Yes: aggiunge la versione di Kowal_Sentry
• No: senza questa informazione negli eventi

Attach Magento Version

• Yes: aggiunge la versione di Magento
• No: senza contesto della piattaforma

Attach Deployment Metadata

• Yes: aggiunge dati aggiuntivi sul deploy, se disponibili
• No: nessun metadato di questo tipo

Utile quando vuoi collegare rapidamente un problema a un rollout o a una build specifica.

Sezione Source Maps / Release

Questa sezione organizza i parametri necessari per release e source maps. L’upload stesso dovrebbe avvenire in CI/CD, non durante il runtime di Magento.

Enable Source Map Upload

• Yes: conferma che a livello organizzativo usi source maps
• No: il modulo non presuppone source maps nella configurazione

Nota:

• è una flag di configurazione, non un meccanismo di upload.

Source Map Upload Mode

Varianti:

• manual: comandi manuali sentry-cli
• ci: upload nella pipeline CI/CD
• deploy_hook: upload nell’hook di deployment

Raccomandazione:

• in produzione più spesso ci.

Assets Base URL

Esempio:

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

Questo valore deve corrispondere a ciò che il Browser SDK vede nello stack trace. Altrimenti le source maps non verranno abbinate.

Release Dist

dist opzionale per la release.

Esempi:

• storefront
• admin
• pl-store

Usalo quando una release ha più varianti di asset.

Organization

Slug dell’organizzazione usato da sentry-cli e API.

Come trovarlo:

• dall’URL del pannello Sentry,
• per esempio https://sentry.io/settings/acme/projects/shop-frontend/ -> acme

Project Slug

Slug del progetto usato dal workflow release e dalle source maps.

Come trovarlo:

• dall’URL del progetto,
• oppure Settings -> Projects -> [projekt] -> Details

Release File Path

Percorso del file con il nome della release per la strategia file.

Esempi:

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

Sezione User Feedback

Configurazione del widget per la segnalazione dei problemi lato browser.

Widget Theme

Varianti:

• light
• dark
• system

Raccomandazione:

• di solito system.

Widget Language

Esempi:

• pl-PL
• en-US

Raccomandazione:

• in multistore adattalo al locale dello store view.

Auto-open after selected errors

• Yes: dopo errori frontend selezionati può comparire una proposta di feedback
• No: il widget non si apre automaticamente

Raccomandazione:

• usalo con cautela per non essere troppo invasivo per l’utente.

Show on checkout success

• Yes: il trigger Feedback può comparire nella pagina di successo dell’ordine
• No: nessun trigger in questo punto

Show on contact page

• Yes: trigger o widget nella pagina di contatto
• No: nessuna esposizione sulla contact page

Show in footer

• Yes: trigger sempre visibile nel footer o come elemento fisso della pagina
• No: nessun trigger permanente

È l’opzione più semplice se vuoi avere un pulsante Zglos problem.

Custom Trigger Selector

Selettore CSS di un elemento esistente che apre Feedback.

Esempi:

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

Usa questo campo se vuoi collegare il widget a un pulsante personalizzato nel layout o in un blocco CMS.

Sezione Cron Monitoring

Questa sezione gestisce check-in e monitor per i cron Magento.

Enable auto-registration of configured cron jobs

• Yes: il primo check-in può creare o aggiornare un monitor in Sentry
• No: il modulo invia check-in senza autoconfigurazione del monitor

Raccomandazione:

• Yes, se hai un deployment controllato e job definiti consapevolmente.

Monitored job codes

Elenco dei job_code Magento.

Puoi separarli con:

• virgole,
• spazi,
• nuove righe.

Varianti:

• campo vuoto: monitora tutti i cron
• elenco di job_code selezionati: monitora solo i job critici

Esempi:

• sales_clean_quotes
• catalog_product_alert
• indexer_reindex_all_invalid

Timeout threshold per job

Una regola per riga:

job_code:minutes

Esempio:

catalog_product_alert:10

Usalo quando un cron può essere eseguito in modo irregolare e vuoi limitare i falsi allarmi.

Max runtime per job

Una regola per riga:

job_code:minutes

Esempio:

indexer_reindex_all_invalid:30

Dopo il superamento del limite, Sentry può contrassegnare il monitor come problematico.

Check-in slug prefix

Esempio:

magento-

Utile quando una sola organizzazione Sentry monitora più istanze Magento e vuoi evitare collisioni di nomi.

Profili di configurazione consigliati

Avvio sicuro in produzione

• Enable Module = Yes
• Enable Backend Monitoring = Yes
• Enable Frontend Monitoring = Yes
• Error Sample Rate = 1
• Trace Sample Rate = 0.05 oppure 0.1
• JS Trace Sample Rate = 0.01 oppure 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

Profilo diagnostico su staging

• Trace Sample Rate più alto, per esempio 0.2
• JS Trace Sample Rate più alto, per esempio 0.1
• temporaneamente Debug Mode = Yes
• Enable Test Commands = Yes
• attenzione con Replay: mantieni comunque mascheramento e blocchi

Variante minima solo backend

• Enable Backend Monitoring = Yes
• Backend DSN compilato
• Enable Frontend Monitoring = No

È un buon primo passo se vuoi avviare prima il monitoraggio delle eccezioni e dei cron lato PHP.

Errori di configurazione più frequenti

• Incollare l’intero snippet Sentryinit(...) invece del solo DSN.
• Presenza contemporanea del modulo in vendor/ e app/code/.
• Valori diversi di release tra eventi e source maps.
• Sampling Replay troppo aggressivo in produzione.
• Disattivazione del mascheramento di checkout e pagamenti.
• Lasciare un DSN di esempio nella configurazione attiva.

Riepilogo

È più sicuro iniziare dal monitoraggio del backend, da un monitoraggio prudente del frontend e da impostazioni privacy restrittive. Quando i dati in Sentry diventano stabili e leggibili, si possono aumentare gradualmente trace sampling, Replay e l’ambito del contesto business.