Kowal_Sentry: instrukcja instalacji i konfiguracji

Cel modułu

Kowal_Sentry integruje Magento 2 z Sentry i pozwala monitorować:

• bledy backendu PHP,
• bledy JavaScript na storefront i opcjonalnie w panelu administracyjnym,
• transakcje HTTP, CLI i cron,
• checkout breadcrumbs,
• Session Replay,
• User Feedback,
• release tracking i przygotowanie pod source maps.

Modul zostal przygotowany jako pakiet Composer i powinien dzialac z lokalizacji vendor/kowal/module-sentry.

Wymagania

• Magento Open Source / Adobe Commerce 2.4.x
• PHP 8.1+
• dostep do Sentry i przynajmniej jednego projektu
• token GitHub, jesli repozytorium jest instalowane przez prywatny vcs

Instalacja

Ponizsze polecenia zostaly skopiowane z README.md.

composer config repositories.sentry vcs https://github.com/kowalco/sentry
composer config --global --auth github-oauth.github.com <YOUR_TOKEN>
composer require kowal/module-sentry
bin/magento module:enable Kowal_Sentry
bin/magento setup:upgrade
bin/magento cache:flush

Wazne

• Pakiet Composer ma dzialac tylko z vendor/kowal/module-sentry.
• Nie nalezy jednoczesnie trzymac tego samego modulu w app/code/Kowal/Sentry.
• Po instalacji konfiguracje znajdziesz w:

Stores -> Configuration -> Kowal -> Sentry

Szybki start

Minimalna konfiguracja potrzebna do uruchomienia modulu:

1. Ustaw Enable Module = Yes.
2. Ustaw Environment, np. production albo staging.
3. Wlacz Enable Backend Monitoring i wklej Backend DSN.
4. Jesli chcesz monitorowac frontend, wlacz Enable Frontend Monitoring i wklej Frontend DSN.
5. Zapisz konfiguracje i wyczysc cache, jesli jest to potrzebne w danym srodowisku.

Skad wziac dane z Sentry

DSN

DSN znajdziesz zwykle tutaj:

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

Do pol Backend DSN i Frontend DSN wklejasz tylko sam URL DSN, np.:

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

Nie wklejaj calego snippetu:

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

Organization

Slug organizacji najlatwiej odczytac z adresu URL panelu Sentry, np.:

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

W tym przykladzie:

• acme to Organization
• shop-frontend to Project Slug

Project Slug

Mozesz go odczytac:

• z URL projektu w panelu Sentry,
• albo z Settings -> Projects -> [projekt] -> Details

Auth token do source maps

Jesli uzywasz sentry-cli, token najlepiej trzymac poza Magento, np. w zmiennej srodowiskowej:

SENTRY_AUTH_TOKEN

Tworzenie tokenu:

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

Weryfikacja po instalacji

Po podstawowej konfiguracji mozesz sprawdzic, czy modul jest aktywny i czy SDK dziala. Komendy smoke-test ponizej zostaly skopiowane z README.md.

Po wlaczeniu Enable Test Commands:

bin/magento kowal:sentry:test:error
bin/magento kowal:sentry:test:transaction
bin/magento kowal:sentry:test:checkin
bin/magento kowal:sentry:test:log

Konfiguracja w panelu Magento

Sciezka:

Stores -> Configuration -> Kowal -> Sentry

Ponizej opis poszczegolnych sekcji, mozliwosci i wariantow ustawien.

Sekcja General

Ta sekcja steruje aktywacja modulu, srodowiskiem i sposobem wyliczania release.

Enable Module

• Yes: uruchamia modul globalnie.
• No: backend i frontend nie beda inicjalizowane, nawet jesli inne opcje sa wlaczone.

Rekomendacja:

• Yes na srodowisku, na ktorym chcesz wysylac dane do Sentry.

Environment

Przyklady:

• production
• staging
• development

Warianty:

• jedna wspolna nazwa dla calej instancji,
• rozne wartosci per website/store view, jesli potrzebujesz rozdzielic eventy.

Rekomendacja:

• bez spacji i bez ukosnikow,
• trzymaj stale nazewnictwo miedzy backendem, frontendem i CI/CD.

Release Strategy

Dostepne warianty:

• manual: release bierze sie z pola Release Name Override
• env: release pobierany jest ze zmiennych srodowiskowych
• file: release odczytywany jest z pliku
• generated: release skladany automatycznie przez modul

Kiedy uzyc:

• manual: gdy chcesz wpisywac release recznie, raczej awaryjnie lub na prostych wdrozeniach
• env: najlepsze w CI/CD, gdy release jest przekazywany przez deployment
• file: dobre, gdy deployment zapisuje identyfikator wersji do wspoldzielonego pliku
• generated: dobre na start, jesli nie masz jeszcze dojrzalego pipeline release

Obslugiwane zmienne srodowiskowe:

• KOWAL_SENTRY_RELEASE
• SENTRY_RELEASE
• RELEASE_NAME
• GIT_COMMIT

Release Name Override

Uzywane tylko przy strategii manual.

Przyklad:

magento-store@2.4.7-p1+20260410.1

Rekomendacja:

• dokladnie ta sama wartosc powinna byc uzyta przy uploadzie source maps.

Project Name

Pomocnicza nazwa projektu w kontekstach modulu. To nie jest Project Slug z Sentry.

Warianty:

• nazwa instancji sklepu,
• nazwa grupy sklepow,
• nazwa projektu wewnetrznego.

Debug Mode

• Yes: bardziej gadatliwe logowanie diagnostyczne
• No: tryb produkcyjny

Rekomendacja:

• No na produkcji,
• Yes tymczasowo, gdy diagnozujesz konfiguracje.

Enable Test Commands

• Yes: udostepnia komendy testowe bin/magento
• No: ukrywa je w normalnej pracy

Rekomendacja:

• Yes na stagingu lub na czas testow,
• No w stalej konfiguracji produkcyjnej.

Sekcja Backend SDK

Dotyczy PHP SDK uzywanego przez storefront HTTP, admin, API, cron i CLI.

Enable Backend Monitoring

• Yes: wlacza monitoring backendu
• No: backend nie wysyla bledow i trace do Sentry

Backend DSN

To podstawowy DSN dla PHP SDK.

Warianty:

• osobny projekt Sentry tylko dla backendu
• ten sam projekt dla backendu i frontendu

Rekomendacja:

• na bardziej dojrzalych wdrozeniach trzymaj osobne projekty backend i frontend,
• w mniejszych instalacjach mozna zaczac od jednego wspolnego projektu.

Error Sample Rate

Zakres: 0-1

Przyklady:

• 1: wysylaj wszystkie bledy
• 0.5: wysylaj okolo polowy
• 0.25: wysylaj okolo 25%

Rekomendacja:

• zwykle 1.0 dla bledow, przynajmniej na starcie.

Trace Sample Rate

Zakres: 0-1

Przyklady:

• 0.05: niski sampling, dobre na produkcji z duzym ruchem
• 0.1: sensowny punkt startowy
• 0.2: wiecej danych kosztem wolumenu

Rekomendacja:

• na produkcji zwykle 0.05-0.2, zalezne od ruchu i planu Sentry.

Profile Sample Rate

Zakres: 0-1

Warianty:

• 0: profilowanie wylaczone
• niska wartosc, np. 0.01: okresowa diagnostyka wydajnosci

Rekomendacja:

• 0 lub bardzo niska wartosc na produkcji.

Enable Logs

• Yes: wysyla structured logs
• No: brak logow w Sentry

Kiedy wlaczyc:

• gdy chcesz korelowac logi z trace i errorami.

Enable Metrics API

• Yes: wlacza fasade modulu dla metryk
• No: metryki po stronie modulu nie beda aktywne

Uwaga:

• aktualne sentry/sentry 4.24.x traktuje backend metrics jako API wygaszane / no-op.

Enable Cron Monitoring

• Yes: wysyla check-iny i transakcje cron
• No: crony nie beda monitorowane przez Sentry

Dane znajdziesz w Sentry w sekcji:

• Crons
• Monitors

Enable CLI Monitoring

• Yes: monitoruje komendy bin/magento
• No: brak monitoringu procesow CLI

Przydatne dla:

• importow,
• reindeksacji,
• customowych komend integracyjnych.

Enable Adminhtml Monitoring

• Yes: monitoruje requesty panelu administracyjnego
• No: ogranicza backend do storefrontu, API, cron i CLI

Enable API Monitoring

• Yes: monitoruje REST, GraphQL i inne endpointy
• No: odcina czesc integracyjna od monitoringu

Sekcja Frontend SDK

Dotyczy Browser SDK ladowanego na storefront i opcjonalnie w panelu admina.

Enable Frontend Monitoring

• Yes: laduje Browser SDK
• No: frontend nie wysyla danych do Sentry

Frontend DSN

Warianty:

• osobny projekt frontendowy
• to samo DSN co backend
• puste pole, aby modul sprobowal fallbacku do Backend DSN

Rekomendacja:

• docelowo osobny projekt frontendowy, jesli chcesz miec czytelne Issues, Replay i Performance.

Enable Storefront JS

• Yes: Browser SDK dziala na storefront
• No: brak SDK na publicznej czesci sklepu

Enable Admin JS

• Yes: Browser SDK dziala tez w panelu admina
• No: monitoring JS ograniczony do storefrontu

Rekomendacja:

• wlaczaj tylko wtedy, gdy realnie diagnozujesz problemy JS w adminie.

JS Trace Sample Rate

Zakres: 0-1

Przyklady:

• 0.01: bardzo ostroznie
• 0.05: dobry start dla produkcji
• 0.1: wiecej danych, wiekszy wolumen

JS Replay Session Sample Rate

Zakres: 0-1

Przyklady:

• 0: brak pelnych replay
• 0.01: bezpieczny start
• 0.05: wiecej danych do analizy UX i bledow

JS Replay On Error Sample Rate

Zakres: 0-1

Przyklady:

• 1: replay po kazdym bledzie w sesji
• 0.5: replay po czesci bledow

Rekomendacja:

• czesto lepszy start niz wysoki sampling wszystkich sesji.

Enable Session Replay

• Yes: wlacza Replay
• No: brak nagrywania sesji

Rekomendacja:

• wlaczaj razem z mocnym maskowaniem checkoutu i platnosci.

Enable User Feedback Widget

• Yes: widget Feedback jest dostepny
• No: widget nie jest ladowany

Uwaga:

• w zaleznosci od planu i konta Sentry funkcja moze byc oznaczona jako beta / experimental.

Enable Checkout Instrumentation

• Yes: dodaje breadcrumbs i tagi checkoutowe
• No: brak dodatkowego kontekstu checkoutu

Rekomendacja:

• zwykle warto zostawic wlaczone.

Enable Ajax Instrumentation

• Yes: breadcrumbs dla AJAX / fetch / XHR
• No: mniej kontekstu dla problemow frontendowych

Browser SDK CDN URL

Domyslnie wskazuje oficjalny bundle Sentry.

Warianty:

• domyslny URL modulu
• wlasny mirror CDN
• przypiety konkretny bundle / konkretna wersja

Zmieniaj tylko wtedy, gdy:

• pinujesz wersje SDK,
• masz wlasne reguly CSP,
• korzystasz z mirrorowania assetow.

Sekcja Privacy / Security

To sekcja odpowiedzialna za minimalizowanie ryzyka wysylki danych wrazliwych.

Send Default PII

• Yes: SDK moze wysylac domyslny zestaw danych uzytkownika i requestu
• No: bardziej zachowawcza polityka prywatnosci

Rekomendacja:

• zazwyczaj No.

Anonymize IP

• Yes: nie przekazuj pelnego IP
• No: pozostaw standardowe zachowanie

Rekomendacja:

• zwykle Yes.

Mask Customer Data

• Yes: maskuje dane klienta
• No: mniej ochrony danych

Rekomendacja:

• praktycznie zawsze Yes na produkcji.

Mask Checkout Fields

• Yes: maskuje pola checkoutu
• No: ryzyko wycieku danych z checkoutu

Rekomendacja:

• zawsze Yes.

Mask Payment Fields

• Yes: maskuje pola zwiazane z platnoscia
• No: bardzo ryzykowne

Rekomendacja:

• zawsze Yes.

Block Authorization Headers

• Yes: usuwa lub maskuje Authorization i tokeny
• No: ryzyko wysylki danych uwierzytelniajacych

Rekomendacja:

• zawsze Yes.

Block Cookies

• Yes: usuwa cookies z danych eventu
• No: wieksze ryzyko wycieku danych sesyjnych

Rekomendacja:

• zwykle Yes.

Block POST Bodies

• Yes: usuwa ciala POST
• No: wysyla wiecej danych requestu

Rekomendacja:

• zwykle Yes, szczegolnie dla checkoutu, logowania i formularzy.

Redact Query Params

• Yes: maskuje parametry query string
• No: query string pozostaje bardziej czytelny, ale mniej bezpieczny

Additional Redacted Keys

Pole tekstowe na dodatkowe klucze do redakcji.

Przyklady:

• token
• api_key
• customer_email
• external_customer_id

Mozesz rozdzielac:

• przecinkami,
• spacjami,
• nowymi liniami.

Replay Mask Selectors

Selektory CSS, ktorych tresc ma byc maskowana w Replay.

Przyklady:

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

Replay Block Selectors

Selektory CSS, ktore maja byc calkowicie blokowane w Replay.

Przyklady:

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

Allowed Domains for Replay Network Details

Lista domen, dla ktorych Replay moze dolaczac szczegoly requestow sieciowych.

Przyklady:

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

Rekomendacja:

• wpisuj tylko wlasne i zaufane domeny.

Sekcja Filtering

Ta sekcja ogranicza szum i wolumen zdarzen.

Ignore Exceptions Regex

Jedna regula regex na linie.

Przyklady zastosowania:

• znane, niegrozne bledy techniczne,
• wyjatki z zewnetrznych integracji, ktore sa juz obslugiwane inaczej.

Ignore URLs Regex

Jedna regula regex na linie.

Przyklady:

• endpointy health-check,
• webhooki testowe,
• zasoby techniczne.

Ignore Transactions

Jedna nazwa transakcji na linie.

Rekomendacja:

• najpierw zbierz dane,
• potem odfiltruj transakcje malo wartosciowe i powtarzalne.

Ignore Bots

• Yes: odcina ruch botow i crawlerow
• No: monitorujesz takze ruch automatyczny

Rekomendacja:

• Yes przy duzym ruchu SEO.

Ignore Health Checks

• Yes: pomija /health, /status, /ping i podobne
• No: takie requesty trafia do Sentry

Ignore Admin Routes

• Yes: ogranicza zdarzenia z admina
• No: admin pozostaje monitorowany

Ignore Static Resource Errors

• Yes: filtruje czesc bledow assetow .js i .css
• No: wszystkie tego typu bledy pozostaja widoczne

Rekomendacja:

• zwykle Yes, jesli nie chcesz zapelniac projektu szumem po deployach.

Sekcja Context

Steruje iloscia kontekstu biznesowego dokladanego do eventow.

Attach Store Context

• Yes: dolacza store_id, store_code, nazwe sklepu i walute
• No: brak tego kontekstu

Rekomendacja:

• Yes, szczegolnie przy multistore.

Attach Website Context

• Yes: dolacza dane website
• No: brak tego poziomu identyfikacji

Attach Customer Context

• Yes: dolacza zanonimizowany kontekst klienta
• No: brak danych o statusie klienta

Attach Quote Context

• Yes: dolacza kontekst koszyka / quote
• No: mniej danych dla diagnozy checkoutu

Attach Cart Totals

• Yes: dolacza totale koszyka
• No: lzejszy event

Rekomendacja:

• wlacz tylko wtedy, gdy te dane realnie pomagaja w analizie.

Attach Order Context

• Yes: dolacza kontekst zamowienia
• No: brak danych o order flow

Szczegolnie przydatne dla:

• invoice,
• shipment,
• transakcyjnych emaili,
• integracji ERP / OMS.

Attach Product Context

• Yes: dolacza podstawowy kontekst produktowy
• No: brak tego kontekstu

Attach Category Context

• Yes: dolacza podstawowy kontekst kategorii
• No: brak tego kontekstu

Attach Payment / Shipping Method

• Yes: dolacza payment_method i shipping_method
• No: mniej danych dla checkoutu

Rekomendacja:

• to jedno z cenniejszych ustawien diagnostycznych.

Attach Module Version

• Yes: dolacza wersje Kowal_Sentry
• No: bez tej informacji w eventach

Attach Magento Version

• Yes: dolacza wersje Magento
• No: bez kontekstu platformy

Attach Deployment Metadata

• Yes: dolacza dodatkowe dane o deployu, jesli sa dostepne
• No: brak tych metadanych

Przydatne, gdy chcesz szybko powiazac problem z rolloutem lub konkretnym buildem.

Sekcja Source Maps / Release

Ta sekcja porzadkuje parametry potrzebne dla release i source maps. Sam upload powinien odbywac sie w CI/CD, a nie podczas runtime Magento.

Enable Source Map Upload

• Yes: potwierdza, ze organizacyjnie korzystasz z source maps
• No: modul nie zaklada source maps w konfiguracji

Uwaga:

• to flaga konfiguracyjna, nie mechanizm uploadu.

Source Map Upload Mode

Warianty:

• manual: reczne polecenia sentry-cli
• ci: upload w pipeline CI/CD
• deploy_hook: upload w hooku deploymentu

Rekomendacja:

• na produkcji najczesciej ci.

Assets Base URL

Przyklad:

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

Ta wartosc musi odpowiadac temu, co Browser SDK widzi w stack trace. Inaczej source maps nie beda dopasowane.

Release Dist

Opcjonalne dist dla release.

Przyklady:

• storefront
• admin
• pl-store

Uzywaj, gdy jeden release ma kilka wariantow assetow.

Organization

Slug organizacji uzywany przez sentry-cli i API.

Jak znalezc:

• z URL panelu Sentry,
• np. https://sentry.io/settings/acme/projects/shop-frontend/ -> acme

Project Slug

Slug projektu uzywany przez workflow release i source maps.

Jak znalezc:

• z URL projektu,
• lub Settings -> Projects -> [projekt] -> Details

Release File Path

Sciezka do pliku z nazwa release przy strategii file.

Przyklady:

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

Sekcja User Feedback

Konfiguracja widgetu zgloszen problemow po stronie przegladarki.

Widget Theme

Warianty:

• light
• dark
• system

Rekomendacja:

• zwykle system.

Widget Language

Przyklady:

• pl-PL
• en-US

Rekomendacja:

• w multistore dopasuj do locale store view.

Auto-open after selected errors

• Yes: po wybranych bledach frontendowych moze pojawic sie propozycja feedbacku
• No: widget nie otwiera sie automatycznie

Rekomendacja:

• stosuj ostroznie, zeby nie byc zbyt agresywnym dla uzytkownika.

Show on checkout success

• Yes: trigger Feedback moze pojawic sie na stronie sukcesu zamowienia
• No: brak triggera w tym miejscu

Show on contact page

• Yes: trigger lub widget na stronie kontaktowej
• No: brak ekspozycji na contact page

Show in footer

• Yes: stale widoczny trigger w stopce lub jako staly element strony
• No: brak stalego triggera

To najprostsza opcja, jesli chcesz miec przycisk Zglos problem.

Custom Trigger Selector

Selektor CSS istniejacego elementu otwierajacego Feedback.

Przyklady:

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

Uzyj tego pola, jesli chcesz podpiac widget pod wlasny przycisk w layoucie lub CMS blocku.

Sekcja Cron Monitoring

Ta sekcja steruje check-inami i monitorami dla cronow Magento.

Enable auto-registration of configured cron jobs

• Yes: pierwszy check-in moze utworzyc lub zaktualizowac monitor w Sentry
• No: modul wysyla check-iny bez auto-konfiguracji monitora

Rekomendacja:

• Yes, jesli masz kontrolowany deployment i swiadomie zdefiniowane joby.

Monitored job codes

Lista job_code Magento.

Mozesz rozdzielac:

• przecinkami,
• spacjami,
• nowymi liniami.

Warianty:

• puste pole: monitoruj wszystkie crony
• lista wybranych job_code: monitoruj tylko krytyczne zadania

Przyklady:

• sales_clean_quotes
• catalog_product_alert
• indexer_reindex_all_invalid

Timeout threshold per job

Jedna regula na linie:

job_code:minutes

Przyklad:

catalog_product_alert:10

Uzywaj, gdy cron bywa wykonywany nieregularnie i chcesz ograniczyc falszywe alarmy.

Max runtime per job

Jedna regula na linie:

job_code:minutes

Przyklad:

indexer_reindex_all_invalid:30

Po przekroczeniu limitu Sentry moze oznaczyc monitor jako problematyczny.

Check-in slug prefix

Przyklad:

magento-

Przydatne, gdy jedna organizacja Sentry monitoruje kilka instancji Magento i chcesz uniknac kolizji nazw.

Rekomendowane profile konfiguracji

Bezpieczny start produkcyjny

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

• wyzsze Trace Sample Rate, np. 0.2
• wyzsze JS Trace Sample Rate, np. 0.1
• tymczasowo Debug Mode = Yes
• Enable Test Commands = Yes
• ostroznie z Replay: nadal utrzymuj maskowanie i blokady

Wariant minimalny tylko backend

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

To dobry pierwszy krok, jesli chcesz najpierw uruchomic monitoring wyjatkow i cronow po stronie PHP.

Najczestsze bledy konfiguracyjne

• Wklejenie calego snippetu \Sentry\init(...) zamiast samego DSN.
• Jednoczesna obecnosc modulu w vendor/ i app/code/.
• Rozne wartosci release miedzy eventami a source maps.
• Zbyt agresywny sampling Replay na produkcji.
• Wylaczenie maskowania checkoutu i platnosci.
• Zostawienie przykladowego DSN w aktywnej konfiguracji.

Podsumowanie

Najbezpieczniej zaczac od monitoringu backendu, ostroznego monitoringu frontendu i restrykcyjnych ustawien prywatnosci. Gdy dane w Sentry stana sie stabilne i czytelne, mozna stopniowo zwiekszac trace sampling, Replay i zakres kontekstu biznesowego.