Kowal_Sentry: instrucțiuni de instalare și configurare

Scopul modulului

Kowal_Sentry integrează Magento 2 cu Sentry și permite monitorizarea:

• erorilor de backend PHP,
• erorilor JavaScript pe storefront și opțional în panoul de administrare,
• tranzacțiilor HTTP, CLI și cron,
• checkout breadcrumbs,
• Session Replay,
• User Feedback,
• release tracking și pregătire pentru source maps.

Modulul a fost pregătit ca pachet Composer și ar trebui să funcționeze din locația vendor/kowal/module-sentry.

Cerințe

• Magento Open Source / Adobe Commerce 2.4.x
• PHP 8.1+
• acces la Sentry și cel puțin un proiect
• token GitHub, dacă repository-ul este instalat printr-un vcs privat

Instalare

Comenzile de mai jos au fost copiate din 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

• Pachetul Composer trebuie să funcționeze doar din vendor/kowal/module-sentry.
• Nu trebuie păstrat simultan același modul în app/code/Kowal/Sentry.
• După instalare, configurația se găsește în:

Stores -> Configuration -> Kowal -> Sentry

Pornire rapidă

Configurația minimă necesară pentru pornirea modulului:

1. Setați Enable Module = Yes.
2. Setați Environment, de ex. production sau staging.
3. Activați Enable Backend Monitoring și inserați Backend DSN.
4. Dacă doriți să monitorizați frontendul, activați Enable Frontend Monitoring și inserați Frontend DSN.
5. Salvați configurația și curățați cache-ul, dacă este necesar în mediul respectiv.

De unde se obțin datele din Sentry

DSN

DSN se găsește de obicei aici:

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

În câmpurile Backend DSN și Frontend DSN inserați doar URL-ul DSN, de ex.:

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

Nu inserați întregul snippet:

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

Organization

Slugul organizației se poate citi cel mai ușor din URL-ul panoului Sentry, de ex.:

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

În acest exemplu:

• acme este Organization
• shop-frontend este Project Slug

Project Slug

Îl puteți citi:

• din URL-ul proiectului în panoul Sentry,
• sau din Settings -> Projects -> [projekt] -> Details

Auth token pentru source maps

Dacă utilizați sentry-cli, tokenul este cel mai bine păstrat în afara Magento, de ex. într-o variabilă de mediu:

SENTRY_AUTH_TOKEN

Crearea tokenului:

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

Verificare după instalare

După configurarea de bază, puteți verifica dacă modulul este activ și dacă SDK-ul funcționează. Comenzile smoke-test de mai jos au fost copiate din README.md.

După activarea Enable Test Commands:

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

Configurare în panoul Magento

Cale:

Stores -> Configuration -> Kowal -> Sentry

Mai jos este descrierea secțiunilor, posibilităților și variantelor de setări.

Secțiunea General

Această secțiune controlează activarea modulului, mediul și modul de calculare a release.

Enable Module

• Yes: pornește modulul global.
• No: backendul și frontendul nu vor fi inițializate, chiar dacă alte opțiuni sunt activate.

Recomandare:

• Yes pe mediul din care doriți să trimiteți date către Sentry.

Environment

Exemple:

• production
• staging
• development

Variante:

• o singură denumire comună pentru întreaga instanță,
• valori diferite per website/store view, dacă aveți nevoie să separați eventurile.

Recomandare:

• fără spații și fără slash-uri,
• păstrați o denumire constantă între backend, frontend și CI/CD.

Release Strategy

Variante disponibile:

• manual: release este preluat din câmpul Release Name Override
• env: release este preluat din variabilele de mediu
• file: release este citit dintr-un fișier
• generated: release este compus automat de modul

Când se utilizează:

• manual: când doriți să introduceți release manual, mai degrabă în situații de urgență sau pentru implementări simple
• env: cea mai bună opțiune în CI/CD, când release este transmis prin deployment
• file: potrivit când deploymentul scrie identificatorul versiunii într-un fișier partajat
• generated: potrivit la început, dacă nu aveți încă un pipeline release matur

Variabile de mediu acceptate:

• KOWAL_SENTRY_RELEASE
• SENTRY_RELEASE
• RELEASE_NAME
• GIT_COMMIT

Release Name Override

Utilizat doar pentru strategia manual.

Exemplu:

magento-store@2.4.7-p1+20260410.1

Recomandare:

• exact aceeași valoare ar trebui folosită la uploadul source maps.

Project Name

Denumire auxiliară a proiectului în contextele modulului. Aceasta nu este Project Slug din Sentry.

Variante:

• numele instanței magazinului,
• numele grupului de magazine,
• numele proiectului intern.

Debug Mode

• Yes: logging de diagnosticare mai detaliat
• No: mod de producție

Recomandare:

• No pe producție,
• Yes temporar, când diagnosticați configurația.

Enable Test Commands

• Yes: pune la dispoziție comenzi de test bin/magento
• No: le ascunde în funcționarea normală

Recomandare:

• Yes pe staging sau pe durata testelor,
• No în configurația permanentă de producție.

Secțiunea Backend SDK

Se referă la PHP SDK utilizat de storefront HTTP, admin, API, cron și CLI.

Enable Backend Monitoring

• Yes: activează monitorizarea backendului
• No: backendul nu trimite erori și trace-uri către Sentry

Backend DSN

Acesta este DSN-ul de bază pentru PHP SDK.

Variante:

• proiect Sentry separat doar pentru backend
• același proiect pentru backend și frontend

Recomandare:

• în implementări mai mature, păstrați proiecte separate backend și frontend,
• în instalări mai mici, se poate începe cu un singur proiect comun.

Error Sample Rate

Interval: 0-1

Exemple:

• 1: trimite toate erorile
• 0.5: trimite aproximativ jumătate
• 0.25: trimite aproximativ 25%

Recomandare:

• de obicei 1.0 pentru erori, cel puțin la început.

Trace Sample Rate

Interval: 0-1

Exemple:

• 0.05: sampling redus, bun pentru producție cu trafic mare
• 0.1: punct de pornire rezonabil
• 0.2: mai multe date cu prețul unui volum mai mare

Recomandare:

• pe producție, de obicei 0.05-0.2, în funcție de trafic și de planul Sentry.

Profile Sample Rate

Interval: 0-1

Variante:

• 0: profilare dezactivată
• valoare redusă, de ex. 0.01: diagnosticare periodică a performanței

Recomandare:

• 0 sau o valoare foarte redusă pe producție.

Enable Logs

• Yes: trimite structured logs
• No: fără loguri în Sentry

Când se activează:

• când doriți să corelați logurile cu trace-uri și erori.

Enable Metrics API

• Yes: activează fațada modulului pentru metrici
• No: metricile pe partea modulului nu vor fi active

Observație:

• versiunea actuală sentry/sentry 4.24.x tratează backend metrics ca API în curs de retragere / no-op.

Enable Cron Monitoring

• Yes: trimite check-in-uri și tranzacții cron
• No: cronurile nu vor fi monitorizate de Sentry

Datele se găsesc în Sentry în secțiunea:

• Crons
• Monitors

Enable CLI Monitoring

• Yes: monitorizează comenzile bin/magento
• No: fără monitorizarea proceselor CLI

Util pentru:

• importuri,
• reindexare,
• comenzi custom de integrare.

Enable Adminhtml Monitoring

• Yes: monitorizează requesturile panoului de administrare
• No: limitează backendul la storefront, API, cron și CLI

Enable API Monitoring

• Yes: monitorizează REST, GraphQL și alte endpointuri
• No: exclude partea de integrare din monitorizare

Secțiunea Frontend SDK

Se referă la Browser SDK încărcat pe storefront și opțional în panoul admin.

Enable Frontend Monitoring

• Yes: încarcă Browser SDK
• No: frontendul nu trimite date către Sentry

Frontend DSN

Variante:

• proiect frontend separat
• același DSN ca backend
• câmp gol, pentru ca modulul să încerce fallback la Backend DSN

Recomandare:

• în final, un proiect frontend separat, dacă doriți Issues, Replay și Performance clare.

Enable Storefront JS

• Yes: Browser SDK funcționează pe storefront
• No: fără SDK pe partea publică a magazinului

Enable Admin JS

• Yes: Browser SDK funcționează și în panoul admin
• No: monitorizarea JS este limitată la storefront

Recomandare:

• activați doar atunci când diagnosticați efectiv probleme JS în admin.

JS Trace Sample Rate

Interval: 0-1

Exemple:

• 0.01: foarte prudent
• 0.05: început bun pentru producție
• 0.1: mai multe date, volum mai mare

JS Replay Session Sample Rate

Interval: 0-1

Exemple:

• 0: fără replay complet
• 0.01: început sigur
• 0.05: mai multe date pentru analiza UX și a erorilor

JS Replay On Error Sample Rate

Interval: 0-1

Exemple:

• 1: replay după fiecare eroare din sesiune
• 0.5: replay după o parte dintre erori

Recomandare:

• adesea este un început mai bun decât un sampling ridicat al tuturor sesiunilor.

Enable Session Replay

• Yes: activează Replay
• No: fără înregistrarea sesiunilor

Recomandare:

• activați împreună cu mascarea puternică a checkoutului și plăților.

Enable User Feedback Widget

• Yes: widgetul Feedback este disponibil
• No: widgetul nu este încărcat

Observație:

• în funcție de planul și contul Sentry, funcția poate fi marcată ca beta / experimental.

Enable Checkout Instrumentation

• Yes: adaugă breadcrumbs și taguri de checkout
• No: fără context suplimentar de checkout

Recomandare:

• de obicei merită lăsat activat.

Enable Ajax Instrumentation

• Yes: breadcrumbs pentru AJAX / fetch / XHR
• No: mai puțin context pentru problemele frontend

Browser SDK CDN URL

Implicit indică bundle-ul oficial Sentry.

Variante:

• URL-ul implicit al modulului
• mirror CDN propriu
• bundle concret / versiune concretă fixată

Modificați doar atunci când:

• fixați versiunea SDK,
• aveți reguli CSP proprii,
• utilizați mirrorarea asseturilor.

Secțiunea Privacy / Security

Aceasta este secțiunea responsabilă pentru minimizarea riscului de trimitere a datelor sensibile.

Send Default PII

• Yes: SDK-ul poate trimite setul implicit de date ale utilizatorului și requestului
• No: politică de confidențialitate mai conservatoare

Recomandare:

• de regulă No.

Anonymize IP

• Yes: nu transmite IP-ul complet
• No: păstrează comportamentul standard

Recomandare:

• de obicei Yes.

Mask Customer Data

• Yes: maschează datele clientului
• No: protecție mai redusă a datelor

Recomandare:

• practic întotdeauna Yes pe producție.

Mask Checkout Fields

• Yes: maschează câmpurile de checkout
• No: risc de scurgere a datelor din checkout

Recomandare:

• întotdeauna Yes.

Mask Payment Fields

• Yes: maschează câmpurile asociate plății
• No: foarte riscant

Recomandare:

• întotdeauna Yes.

Block Authorization Headers

• Yes: elimină sau maschează Authorization și tokenurile
• No: risc de trimitere a datelor de autentificare

Recomandare:

• întotdeauna Yes.

Block Cookies

• Yes: elimină cookies din datele eventului
• No: risc mai mare de scurgere a datelor de sesiune

Recomandare:

• de obicei Yes.

Block POST Bodies

• Yes: elimină body-urile POST
• No: trimite mai multe date ale requestului

Recomandare:

• de obicei Yes, în special pentru checkout, autentificare și formulare.

Redact Query Params

• Yes: maschează parametrii query string
• No: query string rămâne mai lizibil, dar mai puțin sigur

Additional Redacted Keys

Câmp text pentru chei suplimentare de redactat.

Exemple:

• token
• api_key
• customer_email
• external_customer_id

Le puteți separa prin:

• virgule,
• spații,
• linii noi.

Replay Mask Selectors

Selectori CSS al căror conținut trebuie mascat în Replay.

Exemple:

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

Replay Block Selectors

Selectori CSS care trebuie blocați complet în Replay.

Exemple:

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

Allowed Domains for Replay Network Details

Lista domeniilor pentru care Replay poate atașa detalii ale requesturilor de rețea.

Exemple:

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

Recomandare:

• introduceți doar domeniile proprii și de încredere.

Secțiunea Filtering

Această secțiune limitează zgomotul și volumul evenimentelor.

Ignore Exceptions Regex

O regulă regex pe linie.

Exemple de utilizare:

• erori tehnice cunoscute, nepericuloase,
• excepții din integrări externe care sunt deja gestionate altfel.

Ignore URLs Regex

O regulă regex pe linie.

Exemple:

• endpointuri health-check,
• webhookuri de test,
• resurse tehnice.

Ignore Transactions

Un nume de tranzacție pe linie.

Recomandare:

• mai întâi colectați datele,
• apoi filtrați tranzacțiile cu valoare redusă și repetitive.

Ignore Bots

• Yes: exclude traficul boturilor și crawlerelor
• No: monitorizați și traficul automat

Recomandare:

• Yes în cazul unui trafic SEO mare.

Ignore Health Checks

• Yes: omite /health, /status, /ping și similare
• No: astfel de requesturi ajung în Sentry

Ignore Admin Routes

• Yes: limitează evenimentele din admin
• No: adminul rămâne monitorizat

Ignore Static Resource Errors

• Yes: filtrează o parte dintre erorile asseturilor .js și .css
• No: toate erorile de acest tip rămân vizibile

Recomandare:

• de obicei Yes, dacă nu doriți să umpleți proiectul cu zgomot după deploy-uri.

Secțiunea Context

Controlează cantitatea de context business atașată eventurilor.

Attach Store Context

• Yes: atașează store_id, store_code, numele magazinului și moneda
• No: fără acest context

Recomandare:

• Yes, în special pentru multistore.

Attach Website Context

• Yes: atașează date website
• No: fără acest nivel de identificare

Attach Customer Context

• Yes: atașează context anonimizat al clientului
• No: fără date despre statusul clientului

Attach Quote Context

• Yes: atașează contextul coșului / quote
• No: mai puține date pentru diagnosticarea checkoutului

Attach Cart Totals

• Yes: atașează totalurile coșului
• No: event mai ușor

Recomandare:

• activați doar atunci când aceste date ajută efectiv la analiză.

Attach Order Context

• Yes: atașează contextul comenzii
• No: fără date despre order flow

Deosebit de util pentru:

• invoice,
• shipment,
• emailuri tranzacționale,
• integrări ERP / OMS.

Attach Product Context

• Yes: atașează contextul de bază al produsului
• No: fără acest context

Attach Category Context

• Yes: atașează contextul de bază al categoriei
• No: fără acest context

Attach Payment / Shipping Method

• Yes: atașează payment_method și shipping_method
• No: mai puține date pentru checkout

Recomandare:

• este una dintre cele mai valoroase setări de diagnosticare.

Attach Module Version

• Yes: atașează versiunea Kowal_Sentry
• No: fără această informație în eventuri

Attach Magento Version

• Yes: atașează versiunea Magento
• No: fără contextul platformei

Attach Deployment Metadata

• Yes: atașează date suplimentare despre deploy, dacă sunt disponibile
• No: fără aceste metadate

Util atunci când doriți să asociați rapid problema cu un rollout sau cu un build concret.

Secțiunea Source Maps / Release

Această secțiune organizează parametrii necesari pentru release și source maps. Uploadul propriu-zis ar trebui să aibă loc în CI/CD, nu în timpul runtime-ului Magento.

Enable Source Map Upload

• Yes: confirmă că organizațional utilizați source maps
• No: modulul nu presupune source maps în configurație

Observație:

• este un flag de configurare, nu un mecanism de upload.

Source Map Upload Mode

Variante:

• manual: comenzi manuale sentry-cli
• ci: upload în pipeline CI/CD
• deploy_hook: upload în hookul de deployment

Recomandare:

• pe producție, cel mai frecvent ci.

Assets Base URL

Exemplu:

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

Această valoare trebuie să corespundă cu ceea ce Browser SDK vede în stack trace. Altfel, source maps nu vor fi potrivite.

Release Dist

dist opțional pentru release.

Exemple:

• storefront
• admin
• pl-store

Utilizați când un release are mai multe variante de asseturi.

Organization

Slugul organizației utilizat de sentry-cli și API.

Cum se găsește:

• din URL-ul panoului Sentry,
• de ex. https://sentry.io/settings/acme/projects/shop-frontend/ -> acme

Project Slug

Slugul proiectului utilizat de workflow-ul release și source maps.

Cum se găsește:

• din URL-ul proiectului,
• sau Settings -> Projects -> [projekt] -> Details

Release File Path

Calea către fișierul cu numele release pentru strategia file.

Exemple:

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

Secțiunea User Feedback

Configurarea widgetului de raportare a problemelor pe partea browserului.

Widget Theme

Variante:

• light
• dark
• system

Recomandare:

• de obicei system.

Widget Language

Exemple:

• pl-PL
• en-US

Recomandare:

• în multistore, adaptați la locale-ul store view.

Auto-open after selected errors

• Yes: după anumite erori frontend poate apărea o propunere de feedback
• No: widgetul nu se deschide automat

Recomandare:

• utilizați cu prudență, pentru a nu fi prea agresiv pentru utilizator.

Show on checkout success

• Yes: triggerul Feedback poate apărea pe pagina de succes a comenzii
• No: fără trigger în acest loc

Show on contact page

• Yes: trigger sau widget pe pagina de contact
• No: fără expunere pe contact page

Show in footer

• Yes: trigger vizibil permanent în footer sau ca element fix al paginii
• No: fără trigger permanent

Aceasta este cea mai simplă opțiune dacă doriți să aveți un buton Zglos problem.

Custom Trigger Selector

Selector CSS al unui element existent care deschide Feedback.

Exemple:

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

Utilizați acest câmp dacă doriți să conectați widgetul la propriul buton din layout sau dintr-un CMS block.

Secțiunea Cron Monitoring

Această secțiune controlează check-in-urile și monitoarele pentru cronurile Magento.

Enable auto-registration of configured cron jobs

• Yes: primul check-in poate crea sau actualiza monitorul în Sentry
• No: modulul trimite check-in-uri fără auto-configurarea monitorului

Recomandare:

• Yes, dacă aveți un deployment controlat și joburi definite conștient.

Monitored job codes

Lista job_code Magento.

Le puteți separa prin:

• virgule,
• spații,
• linii noi.

Variante:

• câmp gol: monitorizează toate cronurile
• lista job_code selectate: monitorizează doar taskurile critice

Exemple:

• sales_clean_quotes
• catalog_product_alert
• indexer_reindex_all_invalid

Timeout threshold per job

O regulă pe linie:

job_code:minutes

Exemplu:

catalog_product_alert:10

Utilizați când cronul este executat uneori neregulat și doriți să limitați alarmele false.

Max runtime per job

O regulă pe linie:

job_code:minutes

Exemplu:

indexer_reindex_all_invalid:30

După depășirea limitei, Sentry poate marca monitorul ca problematic.

Check-in slug prefix

Exemplu:

magento-

Util când o organizație Sentry monitorizează mai multe instanțe Magento și doriți să evitați coliziunile de nume.

Profiluri de configurare recomandate

Pornire sigură în producție

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

• Trace Sample Rate mai ridicat, de ex. 0.2
• JS Trace Sample Rate mai ridicat, de ex. 0.1
• temporar Debug Mode = Yes
• Enable Test Commands = Yes
• prudență cu Replay: păstrați în continuare mascarea și blocările

Variantă minimă doar backend

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

Este un prim pas bun dacă doriți să porniți mai întâi monitorizarea excepțiilor și cronurilor pe partea PHP.

Cele mai frecvente erori de configurare

• Inserarea întregului snippet Sentryinit(...) în locul DSN-ului propriu-zis.
• Prezența simultană a modulului în vendor/ și app/code/.
• Valori diferite release între eventuri și source maps.
• Sampling Replay prea agresiv pe producție.
• Dezactivarea mascării checkoutului și plăților.
• Lăsarea unui DSN exemplu în configurația activă.

Rezumat

Cel mai sigur este să începeți cu monitorizarea backendului, monitorizarea prudentă a frontendului și setări restrictive de confidențialitate. Când datele din Sentry devin stabile și lizibile, puteți crește treptat trace sampling, Replay și intervalul contextului business.