Kowal_Sentry: instrucțiuni de instalare și configurare

Scopul modulului

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

• erorilor backend PHP,
• erorilor JavaScript pe storefront și opțional în panoul administrativ,
• tranzacțiilor HTTP, CLI și cron,
• checkout breadcrumbs,
• Session Replay,
• User Feedback,
• release tracking și pregătirea 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 la cel puțin un proiect
• adresa de e-mail a clientului și token de licență pentru repository-ul Composer Kowal

Instalare

Comenzile de mai jos au fost copiate din README.md.

Datele de acces la repository-ul Composer, adresa de e-mail a clientului și tokenul de licență, le veți primi prin e-mail după achiziție. Sunt disponibile și în panoul clientului după autentificarea pe kowal.store. Înlocuiți TWOJ_EMAIL_KLIENTA cu adresa de e-mail a contului dumneavoastră, iar TWOJ_TOKEN cu tokenul primit. Executați comenzile în directorul principal 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

• 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

Start rapid

Configurația minimă necesară pentru pornirea modulului:

1. Setați Enable Module = Yes.
2. Setați Environment, de exemplu production sau staging.
3. Activați Enable Backend Monitoring și lipiți Backend DSN.
4. Dacă doriți să monitorizați frontendul, activați Enable Frontend Monitoring și lipiț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 lipiți doar URL-ul DSN, de exemplu:

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

Nu lipiți întregul snippet:

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

Organization

Slugul organizației este cel mai ușor de citit din URL-ul panoului Sentry, de exemplu:

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ă folosiți sentry-cli, cel mai bine este să păstrați tokenul în afara Magento, de exemplu într-o variabilă de mediu:

SENTRY_AUTH_TOKEN

Crearea tokenului:

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

Verificare după instalare

După configurația de bază, puteți verifica dacă modulul este activ și dacă SDK 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 calcul al 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 în mediul din care doriți să trimiteți date către Sentry.

Environment

Exemple:

• production
• staging
• development

Variante:

• o denumire comună pentru întreaga instanță,
• valori diferite per website/store view, dacă trebuie să separați evenimentele.

Recomandare:

• fără spații și fără slashuri,
• păstrați o nomenclatură constantă între backend, frontend și CI/CD.

Release Strategy

Variante disponibile:

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

Când se folosește:

• manual: când doriți să introduceți release-ul manual, mai degrabă în regim de rezervă sau pentru implementări simple
• env: cel mai bun în CI/CD, când release-ul este transmis prin deployment
• file: bun când deploymentul salvează identificatorul versiunii într-un fișier partajat
• generated: bun pentru î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

Folosit doar cu strategia manual.

Exemplu:

magento-store@2.4.7-p1+20260410.1

Recomandare:

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

Project Name

Nume auxiliar al proiectului în contextele modulului. Acesta nu este Project Slug din Sentry.

Variante:

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

Debug Mode

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

Recomandare:

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

Enable Test Commands

• Yes: pune la dispoziție comenzile 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 folosit de storefront HTTP, admin, API, cron și CLI.

Enable Backend Monitoring

• Yes: activează monitorizarea backendului
• No: backendul nu trimite erori și trace 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 backend și frontend separate,
• î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:

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

Profile Sample Rate

Interval: 0-1

Variante:

• 0: profilarea dezactivată
• valoare mică, de exemplu 0.01: diagnostic periodic al performanței

Recomandare:

• 0 sau o valoare foarte mică în 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 din partea modulului nu vor fi active

Atenție:

• sentry/sentry 4.24.x actual tratează backend metrics ca API în curs de eliminare / 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,
• reindexări,
• comenzi customizate de integrare.

Enable Adminhtml Monitoring

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

Enable API Monitoring

• Yes: monitorizează REST, GraphQL și alte endpointuri
• No: separă partea de integrare de 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 backendul
• 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 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-uri complete
• 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 samplingul 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 a plăților.

Enable User Feedback Widget

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

Atenț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 pentru 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,
• folosiți mirror pentru asseturi.

Secțiunea Privacy / Security

Această secțiune este responsabilă pentru minimizarea riscului de trimitere a datelor sensibile.

Send Default PII

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

Recomandare:

• de obicei 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 în producție.

Mask Checkout Fields

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

Recomandare:

• întotdeauna Yes.

Mask Payment Fields

• Yes: maschează câmpurile legate de plată
• 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 evenimentului
• No: risc mai mare de scurgere a datelor de sesiune

Recomandare:

• de obicei Yes.

Block POST Bodies

• Yes: elimină corpurile 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 domenii 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 date,
• apoi filtrați tranzacțiile cu valoare redusă și repetitive.

Ignore Bots

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

Recomandare:

• Yes la 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 de business adăugată la evenimente.

Attach Store Context

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

Recomandare:

• Yes, mai ales pentru multistore.

Attach Website Context

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

Attach Customer Context

• Yes: atașează contextul 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: eveniment mai ușor

Recomandare:

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

Attach Order Context

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

Deosebit de util pentru:

• invoice,
• shipment,
• e-mailuri 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:

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

Attach Module Version

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

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 o problemă cu rolloutul 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 Magento.

Enable Source Map Upload

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

Atenț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:

• în producție, cel mai adesea 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. În caz contrar, source maps nu vor fi potrivite.

Release Dist

dist opțional pentru release.

Exemple:

• storefront
• admin
• pl-store

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

Organization

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

Cum se găsește:

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

Project Slug

Slugul proiectului folosit 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-ului 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 în browser.

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 propunerea de feedback
• No: widgetul nu se deschide automat

Recomandare:

• folosiț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

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

Custom Trigger Selector

Selector CSS al elementului existent care deschide Feedback.

Exemple:

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

Folosiți acest câmp dacă doriți să legați widgetul de un buton propriu din layout sau 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 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: monitorizați toate cronurile
• lista job_code selectate: monitorizați 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

Folosiți când cronul este executat 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 atunci când o organizație Sentry monitorizează mai multe instanțe Magento și doriți să evitați coliziunile de nume.

Profile de configurare recomandate

Start de producție sigur

• 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 diagnostic pe staging

• Trace Sample Rate mai mare, de exemplu 0.2
• JS Trace Sample Rate mai mare, de exemplu 0.1
• temporar Debug Mode = Yes
• Enable Test Commands = Yes
• atenție la Replay: mențineți în continuare mascarea și blocările

Variantă minimă doar backend

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

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

Cele mai frecvente erori de configurare

• Lipirea întregului snippet \Sentry\init(...) în locul DSN-ului simplu.
• Prezența simultană a modulului în vendor/ și app/code/.
• Valori diferite release între evenimente și source maps.
• Sampling Replay prea agresiv în producție.
• Dezactivarea mascării checkoutului și a 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 stricte de confidențialitate. Când datele din Sentry devin stabile și lizibile, puteți crește treptat trace sampling, Replay și domeniul contextului de business.