Sentry w Magento 2: techniczna observability sklepu z modułem Kowal_Sentry

Czym jest Sentry i do czego realnie służy

Sentry najczęściej kojarzy się z error trackingiem, ale w praktyce jest platformą observability, która łączy kilka warstw diagnostyki aplikacji:

• raportowanie wyjątków i błędów runtime,
• tracing wydajności i zależności między operacjami,
• breadcrumbs pokazujące sekwencję działań przed awarią,
• Session Replay po stronie przeglądarki,
• User Feedback od użytkownika końcowego,
• monitoring procesów okresowych, takich jak cron,
• release tracking i powiązanie błędów z konkretnym wdrożeniem.

W dobrze wdrożonym projekcie Sentry nie jest tylko miejscem, do którego wpada stack trace. To narzędzie, które pozwala odpowiedzieć na pytania:

• co dokładnie się zepsuło,
• gdzie problem wystąpił: backend, frontend, checkout, cron, integracja,
• od kiedy problem występuje i z jakim release jest powiązany,
• czy błąd dotyczy wszystkich użytkowników, konkretnego sklepu, metody płatności lub procesu,
• jak wyglądał kontekst requestu i co wydarzyło się tuż przed błędem.

To jest szczególnie ważne w Magento, gdzie awaria rzadko jest izolowanym wyjątkiem w jednym kontrolerze. Często dotyczy całego przepływu: storefront, AJAX, checkout, payment provider, cron synchronizujący dane i późniejsza obróbka zamówienia.

Dlaczego Sentry jest szczególnie przydatne w projektach Magento

Magento 2 jest platformą rozbudowaną, warstwową i intensywnie integrowaną. Typowy sklep działa jednocześnie jako:

• aplikacja backendowa PHP,
• aplikacja frontendowa z dużą ilością JavaScript,
• system integracyjny łączący ERP, PIM, WMS, OMS, bramki płatnicze i kurierów,
• środowisko wielosklepowe z różnymi scope i konfiguracją per website lub store view,
• platforma operująca na krytycznych procesach sprzedażowych, gdzie problem w checkout albo cronie ma bezpośredni wpływ na przychód.

W praktyce oznacza to, że zwykły log plikowy nie wystarcza. Sam stack trace PHP też nie wystarcza. Do diagnozy potrzebny jest szerszy model obserwacji:

• wyjątki backendowe z kontekstem biznesowym,
• błędy JavaScript z rzeczywistej sesji użytkownika,
• tracing requestów i zależności HTTP,
• monitoring cronów i CLI,
• korelacja z release po wdrożeniu,
• sanitizacja danych, żeby observability nie kolidowała z bezpieczeństwem.

To właśnie obszar, w którym Sentry dobrze pasuje do Magento, pod warunkiem że integracja jest zrobiona świadomie, a nie jako prosty wrapper na captureException().

Jak można zastosować Sentry w Magento 2

1. Monitoring błędów backendu PHP

Najbardziej oczywisty scenariusz to raportowanie wyjątków PHP z requestów storefrontu, admina, API, cronów i CLI. W Magento daje to szybki dostęp do:

• stack trace,
• środowiska i release,
• route name i full action name,
• kontekstu store view,
• powiązanych danych o kliencie, quote, zamówieniu lub produkcie, jeśli integracja je dołącza.

To pozwala nie tylko zobaczyć, że pojawił się błąd, ale także odróżnić problem checkoutu od problemu integracji lub błędu panelu administracyjnego.

2. Monitoring frontendu JavaScript

Wiele krytycznych awarii w Magento nie pojawia się w PHP, tylko w przeglądarce:

• błąd RequireJS,
• problem z komponentem Knockout,
• nieudane XHR w checkout,
• nieobsłużone Promise rejection,
• błąd customowego widgetu na PDP albo w koszyku.

Sentry Browser SDK pozwala to rejestrować wraz z breadcrumbs, requestami sieciowymi, adresem strony, środowiskiem i release. W praktyce daje to dużo lepszy obraz tego, co rzeczywiście widzi użytkownik.

3. Performance Monitoring i tracing

Sentry potrafi zbierać transakcje i spany, dzięki czemu można analizować:

• czas trwania requestów HTTP,
• wolne komendy CLI,
• długie lub niestabilne crony,
• zewnętrzne wywołania HTTP z backendu,
• AJAX i fetch po stronie przeglądarki.

To nie zastępuje pełnego APM na poziomie infrastruktury, ale w projektach Magento jest bardzo wartościowe diagnostycznie, bo łączy wydajność z kontekstem aplikacyjnym i release.

4. Monitoring checkoutu

Checkout jest najważniejszym technicznie obszarem sklepu. To właśnie tutaj błędy kosztują najwięcej. Sentry można wykorzystać do:

• rejestrowania błędów w krokach checkoutu,
• tagowania metody płatności i wysyłki,
• breadcrumbs dla AJAX wywoływanych przez checkout,
• analizy problemów z placeOrder,
• Session Replay dla sesji kończących się błędem.

To przekłada się bezpośrednio na krótszy czas diagnozy problemów wpływających na konwersję.

5. Cron Monitoring i check-iny

Magento intensywnie opiera się na cronach. To one realizują wiele procesów, których użytkownik nie widzi bezpośrednio:

• eksporty i importy,
• synchronizacje z systemami zewnętrznymi,
• generowanie alertów,
• czyszczenie danych,
• zadania indeksacyjne i utrzymaniowe.

Sentry pozwala monitorować check-iny cronów, ich czas wykonania oraz status. Dzięki temu można szybko zauważyć, że zadanie przestało się wykonywać, działa zbyt długo albo kończy się błędem.

6. Release tracking i source maps

Jedną z największych wartości Sentry jest powiązanie błędów z konkretnym wdrożeniem. Jeśli release jest ustawiony spójnie dla backendu, frontendu i source maps, zespół może:

• odróżnić stary błąd od regresji po ostatnim deployu,
• szybciej zawęzić zakres zmian,
• poprawnie zsymbolizować stack trace z assetów frontendowych,
• ocenić wpływ konkretnego release na stabilność sklepu.

W projektach Magento ma to szczególne znaczenie, bo deployment często obejmuje jednocześnie backend, static content i integracje.

Czym jest moduł Kowal_Sentry

Kowal_Sentry to produkcyjny moduł Magento 2 integrujący sklep z Sentry po stronie backendu i frontendu. Został zaprojektowany jako warstwa integracyjna zgodna z architekturą Magento:

Moduł jest dostępny tutaj: Kowal_Sentry dla Magento 2.

• bez modyfikacji core,
• z użyciem dependency injection,
• z pluginami wokół kluczowych punktów wejścia aplikacji,
• z konfiguracją przez Stores -> Configuration,
• z rozdzieleniem backendu i frontendu,
• z naciskiem na bezpieczeństwo danych.

Nie jest to pojedynczy helper wysyłający wyjątek. To zbiór mechanizmów spinających PHP SDK, Browser SDK, release strategy, context providers, sanitizację i monitoring procesów Magento.

Jak dokładnie działa integracja w naszym module

Bootstrap backendu PHP

Moduł inicjalizuje PHP SDK raz na request lub proces. Podczas bootstrapu ustawia między innymi:

• dsn,
• environment,
• release,
• sample_rate,
• traces_sample_rate,
• profiles_sample_rate,
• enable_logs,
• send_default_pii,
• hooki before_send,
• hooki sanitizujące breadcrumbs, transakcje, check-iny, logi i metryki.

To ważne, bo już na wejściu definiowana jest polityka tego, co wolno wysłać do Sentry, a co powinno zostać odfiltrowane albo zredagowane.

Transakcje dla requestów HTTP

Plugin wokół Magento\Framework\App\Http otacza request transakcją typu http.server. Transakcja jest nazywana na podstawie requestu Magento i otrzymuje tagi oraz dane takie jak:

• route_name,
• full_action_name,
• ścieżka requestu,
• metoda HTTP,
• area_code.

Jeśli request zakończy się wyjątkiem, moduł raportuje go do Sentry i domyka transakcję ze statusem błędu.

Monitoring CLI

Plugin wokół Magento\Framework\Console\Cli uruchamia transakcje typu cli.command dla komend bin/magento. To daje obserwowalność dla:

• reindeksacji,
• importów,
• zadań uruchamianych ręcznie,
• własnych komend integracyjnych.

W praktyce jest to bardzo użyteczne na stagingu i produkcji, gdzie problemy z CLI nie zawsze są widoczne w standardowym monitoringu aplikacyjnym.

Monitoring cronów i check-iny

Plugin wokół Magento\Cron\Model\Observer uruchamia transakcję cron.job, raportuje czas wykonania zadania i wysyła check-iny do Sentry. Dzięki temu można:

• monitorować wszystkie crony albo tylko wybrane job_code,
• ustawić timeout per job,
• ustawić maksymalny oczekiwany runtime,
• budować spójne nazwy monitorów przez slug prefix,
• opcjonalnie auto-rejestrować monitora przy pierwszym check-inie.

To jedna z mocniejszych części integracji, bo łączy techniczny monitoring Sentry z rzeczywistym modelem pracy Magento.

Checkout instrumentation

Plugin wokół Magento\Quote\Model\QuoteManagement::placeOrder() dodaje breadcrumbs i raportuje wyjątki związane z finalizacją zamówienia. Dzięki temu event może zawierać dodatkowy kontekst, na przykład:

• cart_id,
• payment_method,
• informacje potrzebne do szybszej diagnozy awarii w checkout.

Po stronie frontendu moduł może dodatkowo śledzić checkoutowe breadcrumbs i błędy AJAX, więc razem daje to spójniejszy obraz przepływu zamówienia.

Spany i breadcrumbs dla wywołań HTTP klientem Curl

Plugin wokół Magento\Framework\HTTP\Client\Curl dodaje span http.client dla wywołań GET, POST, PUT i DELETE. Rejestrowane są między innymi:

• URL,
• metoda,
• host,
• status odpowiedzi,
• breadcrumb odpowiadający wywołaniu.

To przydatne przy diagnozowaniu integracji z zewnętrznymi API, gdzie błąd nie wynika z samego Magento, tylko z czasu odpowiedzi, problemu autoryzacji albo niepoprawnego payloadu po stronie partnera.

Browser SDK dla storefrontu i admina

Po stronie przeglądarki moduł ładuje Browser SDK dynamicznie przez Magento i RequireJS. Inicjalizacja obejmuje:

• dsn,
• environment,
• release,
• tracesSampleRate,
• Replay,
• User Feedback,
• tracePropagationTargets,
• beforeSend z sanitizacją eventu.

Dodatkowo moduł:

• podpina się pod błędy RequireJS,
• dodaje AJAX breadcrumbs,
• ustawia tagi i konteksty Magento,
• inicjalizuje checkout instrumentation tylko na checkout_index_index,
• może działać na storefrontcie i opcjonalnie w adminie.

Release strategy

Nasz moduł wspiera cztery strategie release:

• manual,
• env,
• file,
• generated.

W praktyce oznacza to, że integrację można dopasować zarówno do prostego wdrożenia ręcznego, jak i do dojrzałego CI/CD. Dodatkowo moduł obsługuje takie zmienne środowiskowe jak:

• KOWAL_SENTRY_RELEASE,
• SENTRY_RELEASE,
• RELEASE_NAME,
• GIT_COMMIT.

Jeśli release nie zostanie dostarczony z zewnątrz, moduł potrafi wygenerować go na podstawie wersji Magento, wersji modułu i skrótu commita.

Sanitizacja i prywatność

Jednym z najważniejszych elementów integracji jest sanitizer eventów. W naszym module sanitizacja obejmuje:

• request headers,
• cookies,
• POST body,
• query params,
• konteksty i extra,
• tagi,
• user,
• breadcrumbs,
• logi,
• metryki.

W zależności od konfiguracji moduł potrafi:

• blokować Authorization,
• blokować cookies,
• usuwać body requestów,
• maskować dane klienta,
• anonimizować IP,
• redagować dodatkowe klucze wrażliwe, np. token, api_key, customer_email.

W e-commerce nie jest to dodatek. To warunek poprawnej integracji.

Zakres konfiguracji modułu

Konfiguracja jest dostępna w panelu Magento:

Stores -> Configuration -> Kowal -> Sentry

Zakres ustawień został celowo rozbity na sekcje odpowiadające różnym aspektom observability.

1. General

Sekcja bazowa steruje aktywacją modułu oraz parametrami wspólnymi:

• globalne włączenie lub wyłączenie modułu,
• Environment,
• Release Strategy,
• Release Name Override,
• Project Name,
• Debug Mode,
• testowe komendy CLI.

To sekcja, która ustawia fundament diagnostyki. Bez poprawnego environment i release dane w Sentry będą mniej wartościowe, bo trudniej będzie odróżnić środowiska i wdrożenia.

2. Backend SDK

Tutaj konfigurowany jest monitoring po stronie PHP:

• Backend DSN,
• Error Sample Rate,
• Trace Sample Rate,
• Profile Sample Rate,
• Enable Logs,
• Enable Metrics API,
• Enable Cron Monitoring,
• Enable CLI Monitoring,
• Enable Adminhtml Monitoring,
• Enable API Monitoring.

To właśnie ta sekcja decyduje, czy sklep raportuje wyjątki i tracing dla backendu oraz jak szeroki jest zakres obserwacji procesów uruchamianych poza storefrontem.

Warto pamiętać, że backend metrics w aktualnym sentry/sentry 4.24.x są traktowane jako wygaszane lub no-op, więc pole Enable Metrics API należy traktować jako kompatybilną fasadę modułu, a nie pełny backend metrics pipeline.

3. Frontend SDK

Sekcja frontendowa odpowiada za Browser SDK:

• Frontend DSN,
• Enable Storefront JS,
• Enable Admin JS,
• JS Trace Sample Rate,
• JS Replay Session Sample Rate,
• JS Replay On Error Sample Rate,
• Enable Session Replay,
• Enable User Feedback Widget,
• Enable Checkout Instrumentation,
• Enable Ajax Instrumentation,
• Browser SDK CDN URL.

To bardzo ważne rozdzielenie. W wielu projektach Magento potrzeby obserwacji storefrontu i admina są inne, dlatego moduł pozwala zarządzać nimi osobno.

4. Privacy / Security

Ta sekcja definiuje politykę bezpieczeństwa danych:

• Send Default PII,
• Anonymize IP,
• Mask Customer Data,
• Mask Checkout Fields,
• Mask Payment Fields,
• Block Authorization Headers,
• Block Cookies,
• Block POST Bodies,
• Redact Query Params,
• Additional Redacted Keys,
• Replay Mask Selectors,
• Replay Block Selectors,
• Allowed Domains for Replay Network Details.

To sekcja krytyczna w każdym wdrożeniu produkcyjnym. Zbyt liberalne ustawienia observability mogą doprowadzić do wysyłania do Sentry danych, które nie powinny tam trafić.

5. Filtering

Sekcja filtrów pozwala ograniczać szum:

• regexy ignorujące wyjątki,
• regexy ignorujące URL,
• ignorowane transakcje,
• ignorowanie botów,
• ignorowanie health checków,
• ignorowanie części ruchu admina,
• ignorowanie części błędów zasobów statycznych.

W dobrze utrzymanym projekcie filtrowanie nie jest opcjonalne. Bez niego zespół bardzo szybko traci jakość sygnału w Sentry.

6. Context

Tutaj definiujemy, ile kontekstu biznesowego Magento dołączamy do eventów:

• store context,
• website context,
• customer context,
• quote context,
• cart totals,
• order context,
• product context,
• category context,
• payment i shipping method,
• wersja modułu,
• wersja Magento,
• deployment metadata.

Ta sekcja jest szczególnie cenna w projektach z rozbudowanym checkoutem i wieloma integracjami, bo pozwala dużo szybciej odpowiedzieć na pytanie, kogo i czego dotyczy problem.

7. Source Maps / Release

Sekcja release i source maps porządkuje dane potrzebne do pracy z frontendowym release workflow:

• flaga używania source maps,
• tryb uploadu source maps,
• Assets Base URL,
• Release Dist,
• Organization,
• Project Slug,
• Release File Path.

Sam moduł nie uploaduje source maps podczas runtime Magento. I dobrze. To powinien robić pipeline CI/CD, na przykład przez sentry-cli.

8. User Feedback

Sekcja feedbacku umożliwia kontrolowanie widgetu po stronie przeglądarki:

• motyw widgetu,
• język,
• auto-open po wybranych błędach,
• obecność na success page,
• obecność na contact page,
• trigger w footerze,
• własny selektor triggera.

To funkcja przydatna tam, gdzie zespół chce szybciej zbierać sygnały od użytkowników końcowych bez budowania osobnego mechanizmu zgłoszeń technicznych.

9. Cron Monitoring

Sekcja cronowa porządkuje monitorowanie zadań Magento:

• auto-rejestracja monitorów,
• lista monitorowanych job_code,
• timeout threshold per job,
• max runtime per job,
• prefiks slugów monitorów.

To ważne, bo w praktyce nie wszystkie crony są równie krytyczne. Moduł pozwala skupić monitoring na procesach, które mają realny wpływ na sprzedaż, integracje i ciągłość działania sklepu.

Jak wygląda sensowny scenariusz wdrożenia

W praktyce rekomendowany proces wygląda tak:

1. Uruchomić backend monitoring z restrykcyjną polityką prywatności.
2. Dodać frontend monitoring dla storefrontu.
3. Włączyć tracing na umiarkowanym sample rate.
4. Włączyć cron monitoring dla najważniejszych zadań.
5. Skonfigurować release strategy spójną z deploymentem.
6. Dodać source maps w CI/CD.
7. Dopiero potem rozszerzać zakres Replay i feedbacku.

Taka kolejność ma sens, bo pozwala najpierw zbudować stabilny i bezpieczny sygnał diagnostyczny, a dopiero później zwiększać szczegółowość danych.

Co daje ta integracja zespołowi technicznemu

Z perspektywy zespołu utrzymaniowego dobrze skonfigurowany Kowal_Sentry daje bardzo konkretną wartość:

• szybsze wykrywanie awarii po deployu,
• krótszy czas diagnozy błędów checkoutu,
• lepszą widoczność problemów z integracjami HTTP,
• monitoring procesów cron i CLI,
• spójny kontekst backendu i frontendu,
• większą kontrolę nad jakością danych wysyłanych do narzędzia zewnętrznego.

W projektach Magento to zwykle oznacza mniej czasu spędzonego na ręcznym odtwarzaniu błędu i szybsze przejście od objawu do przyczyny.

Ograniczenia, o których warto wiedzieć

Żadna integracja observability nie jest całkowicie bezwarunkowa. W przypadku naszego modułu warto pamiętać o kilku rzeczach:

• backend metrics w aktualnym PHP SDK Sentry nie powinny być traktowane jako pełnoprawny pipeline metryk,
• User Feedback bywa w Sentry oznaczony jako beta lub experimental,
• Replay należy wdrażać ostrożnie i zawsze z silnym maskowaniem,
• zbyt szeroki sampling na produkcji szybko zwiększa wolumen danych i koszty.

Te ograniczenia nie dyskwalifikują rozwiązania. Po prostu wymagają świadomej konfiguracji.

Podsumowanie

Sentry w Magento 2 ma sens wtedy, gdy jest wdrożone jako pełna warstwa observability, a nie tylko prosty mechanizm wysyłania wyjątków. Kowal_Sentry właśnie do tego służy. Łączy backend PHP, frontend JavaScript, tracing, checkout, cron monitoring, release strategy i sanitizację danych w jednym spójnym module Magento.

Dzięki temu zespół techniczny dostaje realne narzędzie do utrzymania i rozwoju sklepu: z lepszą widocznością błędów, szybszą diagnozą regresji i większą kontrolą nad stabilnością procesu sprzedażowego.

Źródła

• Sentry for PHP: https://docs.sentry.io/platforms/php/
• Sentry for JavaScript Browser: https://docs.sentry.io/platforms/javascript/guides/browser/
• Sentry Session Replay: https://docs.sentry.io/platforms/javascript/session-replay/
• Sentry User Feedback: https://docs.sentry.io/platforms/javascript/user-feedback/
• Sentry Crons for PHP: https://docs.sentry.io/platforms/php/crons/
• Sentry Environments and configuration: https://docs.sentry.io/platforms/javascript/configuration/environments/