Sentry in Magento 2

technische store observability met de Kowal_Sentry-module

12 minuten, 6 seconden

Sentry in Magento 2

Sentry in Magento 2: technische store observability met de Kowal_Sentry-module

Wat Sentry is en waar het in de praktijk voor dient

Sentry wordt meestal geassocieerd met error tracking, maar in de praktijk is het een observability-platform dat meerdere lagen van applicatiediagnostiek combineert:

  • rapportage van exceptions en runtimefouten,
  • performance tracing en afhankelijkheden tussen operaties,
  • breadcrumbs die de volgorde van acties voor een storing tonen,
  • Session Replay aan browserzijde,
  • User Feedback van de eindgebruiker,
  • monitoring van periodieke processen zoals cron,
  • release tracking en koppeling van fouten aan een specifieke deployment.

In een goed geimplementeerd project is Sentry niet alleen de plek waar een stack trace terechtkomt. Het is een tool waarmee je vragen kunt beantwoorden als:

  • wat er precies kapot ging,
  • waar het probleem optrad: backend, frontend, checkout, cron, integratie,
  • sinds wanneer het probleem bestaat en aan welke release het gekoppeld is,
  • of de fout alle gebruikers raakt, een specifieke store, betaalmethode of proces,
  • hoe de requestcontext eruitzag en wat er vlak voor de fout gebeurde.

Dit is vooral belangrijk in Magento, waar een storing zelden een geisoleerde exception in een enkele controller is. Vaak raakt het de volledige flow: storefront, AJAX, checkout, payment provider, cron die data synchroniseert en latere orderverwerking.

Waarom Sentry vooral nuttig is in Magento-projecten

Magento 2 is een uitgebreid, gelaagd en sterk geintegreerd platform. Een typische shop werkt tegelijk als:

  • PHP-backendapplicatie,
  • frontendapplicatie met veel JavaScript,
  • integratiesysteem dat ERP, PIM, WMS, OMS, betaalgateways en vervoerders verbindt,
  • multistore-omgeving met verschillende scopes en configuratie per website of store view,
  • platform dat kritieke verkoopprocessen ondersteunt, waar een probleem in checkout of cron direct invloed heeft op omzet.

In de praktijk betekent dit dat een gewoon bestandslog niet voldoende is. Een PHP-stack trace alleen is ook niet voldoende. Voor diagnose is een breder observatiemodel nodig:

  • backendexceptions met businesscontext,
  • JavaScript-fouten uit echte gebruikerssessies,
  • tracing van requests en HTTP-afhankelijkheden,
  • cron- en CLI-monitoring,
  • correlatie met de release na deployment,
  • datasanitisatie zodat observability niet botst met security.

Dat is precies het gebied waarin Sentry goed bij Magento past, mits de integratie bewust wordt uitgevoerd en niet als een simpele wrapper rond captureException().

Hoe Sentry in Magento 2 kan worden gebruikt

1. Monitoring van PHP-backendfouten

Het meest voor de hand liggende scenario is het rapporteren van PHP-exceptions uit storefront-, admin-, API-, cron- en CLI-requests. In Magento geeft dat snel toegang tot:

  • de stack trace,
  • environment en release,
  • route name en full action name,
  • store-viewcontext,
  • gekoppelde klant-, quote-, order- of productdata als de integratie die toevoegt.

Hiermee kun je niet alleen zien dat er een fout is opgetreden, maar ook onderscheiden of het om een checkoutprobleem, een integratieprobleem of een fout in het adminpanel gaat.

2. Monitoring van het JavaScript-frontend

Veel kritieke storingen in Magento verschijnen niet in PHP, maar in de browser:

  • een RequireJS-fout,
  • een probleem met een Knockout-component,
  • mislukte XHR in checkout,
  • een onbehandelde Promise rejection,
  • een fout in een custom widget op de PDP of in de winkelwagen.

Sentry Browser SDK kan dit registreren samen met breadcrumbs, netwerkaanvragen, paginURL, environment en release. In de praktijk geeft dit een veel beter beeld van wat de gebruiker echt ziet.

3. Performance Monitoring en tracing

Sentry kan transacties en spans verzamelen, zodat je kunt analyseren:

  • duur van HTTP-requests,
  • trage CLI-commando's,
  • lange of instabiele cronjobs,
  • externe HTTP-calls vanuit de backend,
  • AJAX- en fetch-calls in de browser.

Dit vervangt geen volledige APM op infrastructuurniveau, maar is in Magento-projecten diagnostisch erg waardevol omdat het performance koppelt aan applicatiecontext en release.

4. Monitoring van checkout

Checkout is technisch het belangrijkste gebied van een shop. Hier kosten fouten het meest. Sentry kan worden gebruikt voor:

  • registreren van fouten in checkoutstappen,
  • taggen van betaal- en verzendmethode,
  • breadcrumbs voor AJAX-calls die door checkout worden gestart,
  • analyse van problemen met placeOrder,
  • Session Replay voor sessies die met een fout eindigen.

Dit vertaalt zich direct in kortere diagnosetijd voor problemen die de conversie raken.

5. Cron Monitoring en check-ins

Magento leunt zwaar op cron. Daarmee worden veel processen uitgevoerd die de gebruiker niet direct ziet:

  • exports en imports,
  • synchronisaties met externe systemen,
  • genereren van alerts,
  • opschonen van data,
  • indexatie- en onderhoudstaken.

Sentry maakt het mogelijk cron-check-ins, uitvoeringstijd en status te monitoren. Zo zie je snel dat een taak niet meer draait, te lang duurt of met een fout eindigt.

6. Release tracking en source maps

Een van de grootste waarden van Sentry is het koppelen van fouten aan een specifieke deployment. Als de release consistent is ingesteld voor backend, frontend en source maps, kan het team:

  • een oude fout onderscheiden van een regressie na de laatste deploy,
  • de scope van wijzigingen sneller verkleinen,
  • stack traces van frontendassets correct symboliseren,
  • de impact van een specifieke release op de stabiliteit van de shop beoordelen.

In Magento-projecten is dit extra belangrijk omdat deployment vaak tegelijk backend, static content en integraties omvat.

Wat de module Kowal_Sentry is

Kowal_Sentry is een productieklare Magento 2-module die de shop met Sentry integreert aan backend- en frontendzijde. De module is ontworpen als integratielaag die aansluit op de Magento-architectuur:

De module is hier beschikbaar: Kowal_Sentry for Magento 2.

  • zonder core-aanpassingen,
  • met dependency injection,
  • met plugins rond belangrijke applicatie-entrypoints,
  • met configuratie via Stores -> Configuration,
  • met scheiding tussen backend en frontend,
  • met sterke nadruk op dataveiligheid.

Het is geen losse helper die een exception verstuurt. Het is een set mechanismen die PHP SDK, Browser SDK, releasestrategie, contextproviders, sanitisatie en monitoring van Magento-processen samenbrengt.

Hoe de integratie in onze module precies werkt

Bootstrap van de PHP-backend

De module initialiseert de PHP SDK een keer per request of proces. Tijdens bootstrap stelt de module onder meer in:

  • dsn,
  • environment,
  • release,
  • sample_rate,
  • traces_sample_rate,
  • profiles_sample_rate,
  • enable_logs,
  • send_default_pii,
  • before_send-hooks,
  • hooks die breadcrumbs, transacties, check-ins, logs en metrics sanitiseren.

Dat is belangrijk, omdat direct bij de ingang wordt vastgelegd wat naar Sentry mag worden gestuurd en wat moet worden uitgefilterd of geredigeerd.

Transacties voor HTTP-requests

De plugin rond Magento\Framework\App\Http verpakt de request in een transactie van het type http.server. De transactie krijgt een naam op basis van de Magento-request en ontvangt tags en data zoals:

  • route_name,
  • full_action_name,
  • requestpad,
  • HTTP-methode,
  • area_code.

Als de request met een exception eindigt, rapporteert de module die aan Sentry en sluit de transactie af met een foutstatus.

CLI-monitoring

De plugin rond Magento\Framework\Console\Cli start transacties van het type cli.command voor bin/magento-commando's. Dat levert observability op voor:

  • herindexatie,
  • imports,
  • handmatig gestartte taken,
  • custom integratiecommando's.

In de praktijk is dit erg nuttig op staging en productie, waar CLI-problemen niet altijd zichtbaar zijn in standaard applicatiemonitoring.

Cron-monitoring en check-ins

De plugin rond Magento\Cron\Model\Observer start een cron.job-transactie, rapporteert de uitvoeringstijd van de job en stuurt check-ins naar Sentry. Daardoor kun je:

  • alle crons of alleen geselecteerde job_code-waarden monitoren,
  • een timeout per job instellen,
  • een maximaal verwachte runtime instellen,
  • consistente monitornamen opbouwen via een slug prefix,
  • de monitor optioneel automatisch registreren bij de eerste check-in.

Dit is een van de sterkere onderdelen van de integratie, omdat het technische Sentry-monitoring verbindt met het echte werkmodel van Magento.

Checkout-instrumentatie

De plugin rond Magento\Quote\Model\QuoteManagement::placeOrder() voegt breadcrumbs toe en rapporteert exceptions rond het afronden van de bestelling. Daardoor kan het event extra context bevatten, bijvoorbeeld:

  • cart_id,
  • payment_method,
  • informatie die nodig is om checkoutstoringen sneller te diagnosticeren.

Aan frontendzijde kan de module daarnaast checkout-breadcrumbs en AJAX-fouten volgen, wat samen een samenhangender beeld van de orderflow geeft.

Spans en breadcrumbs voor HTTP-calls via de Curl-client

De plugin rond Magento\Framework\HTTP\Client\Curl voegt een http.client-span toe voor GET, POST, PUT en DELETE-calls. Daarbij worden onder meer vastgelegd:

  • URL,
  • methode,
  • host,
  • responsstatus,
  • de breadcrumb die bij de call hoort.

Dit is nuttig bij het diagnosticeren van integraties met externe API's, waar de fout niet uit Magento zelf komt maar uit responstijd, autorisatieproblemen of een onjuiste payload aan partnerzijde.

Browser SDK voor storefront en admin

Aan browserzijde laadt de module Browser SDK dynamisch via Magento en RequireJS. De initialisatie omvat:

  • dsn,
  • environment,
  • release,
  • tracesSampleRate,
  • Replay,
  • User Feedback,
  • tracePropagationTargets,
  • beforeSend met eventsanitisatie.

Daarnaast:

  • haakt de module in op RequireJS-fouten,
  • voegt AJAX-breadcrumbs toe,
  • stelt Magento-tags en -contexten in,
  • initialiseert checkoutinstrumentatie alleen op checkout_index_index,
  • kan de module draaien op storefront en optioneel in admin.

Releasestrategie

Onze module ondersteunt vier releasestrategieen:

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

In de praktijk betekent dit dat de integratie past bij zowel een eenvoudige handmatige deployment als bij volwassen CI/CD. Daarnaast ondersteunt de module omgevingsvariabelen zoals:

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

Als de release niet extern wordt aangeleverd, kan de module die genereren op basis van Magento-versie, moduleversie en korte commithash.

Sanitisatie en privacy

Een van de belangrijkste onderdelen van de integratie is de eventsanitizer. In onze module omvat sanitisatie:

  • requestheaders,
  • cookies,
  • POST-body,
  • queryparams,
  • contexten en extra,
  • tags,
  • user,
  • breadcrumbs,
  • logs,
  • metrics.

Afhankelijk van de configuratie kan de module:

  • Authorization blokkeren,
  • cookies blokkeren,
  • requestbodies verwijderen,
  • klantdata maskeren,
  • IP anonimiseren,
  • extra gevoelige sleutels redigeren zoals token, api_key, customer_email.

In e-commerce is dit geen extra. Het is een voorwaarde voor een correcte integratie.

Reikwijdte van de moduleconfiguratie

De configuratie is beschikbaar in het Magento-paneel:

Stores -> Configuration -> Kowal -> Sentry

De instellingen zijn bewust verdeeld in secties die overeenkomen met verschillende aspecten van observability.

1. General

De basissectie stuurt de activatie van de module en gedeelde parameters:

  • globaal in- of uitschakelen van de module,
  • Environment,
  • Release Strategy,
  • Release Name Override,
  • Project Name,
  • Debug Mode,
  • test-CLI-commando's.

Deze sectie legt de basis van diagnostiek. Zonder correcte environment en release zijn data in Sentry minder waardevol, omdat omgevingen en deployments lastiger te onderscheiden zijn.

2. Backend SDK

Hier wordt monitoring aan PHP-zijde geconfigureerd:

  • 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.

Deze sectie bepaalt of de shop backendexceptions en tracing rapporteert en hoe breed de observatiescope is voor processen buiten de storefront.

Het is goed om te onthouden dat backendmetrics in huidige sentry/sentry 4.24.x als deprecated of no-op worden behandeld. Het veld Enable Metrics API moet daarom worden gezien als compatibiliteitsfacade van de module en niet als een volledige backend-metricspipeline.

3. Frontend SDK

De frontendsectie is bedoeld voor 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.

Deze scheiding is erg belangrijk. In veel Magento-projecten verschillen de observabilitybehoeften van storefront en admin, daarom laat de module je die apart beheren.

4. Privacy / Security

Deze sectie definieert het databeveiligingsbeleid:

  • 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.

Dit is een kritieke sectie in elke productie-implementatie. Te soepele observability-instellingen kunnen ertoe leiden dat data naar Sentry wordt gestuurd die daar niet hoort te belanden.

5. Filtering

De filtersectie helpt ruis te beperken:

  • regexen die exceptions negeren,
  • regexen die URL's negeren,
  • genegeerde transacties,
  • bots negeren,
  • health checks negeren,
  • een deel van adminverkeer negeren,
  • een deel van fouten in statische assets negeren.

In een goed onderhouden project is filtering niet optioneel. Zonder filtering verliest het team snel signaalkwaliteit in Sentry.

6. Context

Hier definiieren we hoeveel Magento-businesscontext aan events wordt gekoppeld:

  • storecontext,
  • websitecontext,
  • klantcontext,
  • quotecontext,
  • winkelwagentotalen,
  • ordercontext,
  • productcontext,
  • categoriecontext,
  • betaal- en verzendmethode,
  • moduleversie,
  • Magento-versie,
  • deploymentmetadata.

Deze sectie is vooral waardevol in projecten met complexe checkout en veel integraties, omdat je er veel sneller mee kunt beantwoorden wie en wat door het probleem wordt geraakt.

7. Source Maps / Release

De release- en source-mapssectie ordent data die nodig zijn voor de frontend-releaseworkflow:

  • vlag voor het gebruik van source maps,
  • uploadmodus voor source maps,
  • Assets Base URL,
  • Release Dist,
  • Organization,
  • Project Slug,
  • Release File Path.

De module uploadt zelf geen source maps tijdens Magento-runtime. En dat is goed. Dat hoort door de CI/CD-pipeline te worden gedaan, bijvoorbeeld via sentry-cli.

8. User Feedback

De feedbacksectie maakt controle van de browserwidget mogelijk:

  • widgetthema,
  • taal,
  • automatisch openen bij geselecteerde fouten,
  • aanwezigheid op de success page,
  • aanwezigheid op de contact page,
  • trigger in de footer,
  • aangepaste triggerselector.

Deze functie is nuttig waar het team sneller signalen van eindgebruikers wil verzamelen zonder een apart technisch meldmechanisme te bouwen.

9. Cron Monitoring

De cronsectie ordent monitoring van Magento-taken:

  • automatische monitorregistratie,
  • lijst met gemonitorde job_code-waarden,
  • timeoutdrempel per job,
  • maximale runtime per job,
  • monitor-slugprefix.

Dit is belangrijk omdat in de praktijk niet alle crons even kritisch zijn. De module laat je monitoring richten op processen die echte impact hebben op omzet, integraties en operationele continuiteit van de shop.

Hoe een zinvol implementatiescenario eruitziet

In de praktijk ziet het aanbevolen proces er zo uit:

  1. Start backendmonitoring met een restrictief privacybeleid.
  2. Voeg frontendmonitoring toe voor de storefront.
  3. Schakel tracing in met een gematigde sample rate.
  4. Schakel cronmonitoring in voor de belangrijkste jobs.
  5. Configureer een releasestrategie die past bij deployment.
  6. Voeg source maps toe in CI/CD.
  7. Breid pas daarna Replay en feedback uit.

Deze volgorde is logisch, omdat je eerst een stabiel en veilig diagnostisch signaal opbouwt en pas daarna de datadetail vergroot.

Wat deze integratie het technische team oplevert

Vanuit het perspectief van het onderhoudsteam levert een goed geconfigureerde Kowal_Sentry heel concrete waarde:

  • snellere detectie van storingen na deployments,
  • kortere diagnosetijd voor checkoutfouten,
  • betere zichtbaarheid van problemen met HTTP-integraties,
  • monitoring van cron- en CLI-processen,
  • consistente backend- en frontendcontext,
  • meer controle over de kwaliteit van data die naar een externe tool wordt gestuurd.

In Magento-projecten betekent dit meestal minder tijd kwijt aan het handmatig reproduceren van een fout en sneller van symptoom naar oorzaak gaan.

Beperkingen die je moet kennen

Geen enkele observability-integratie is volledig zonder voorwaarden. In het geval van onze module is het goed om een paar dingen te onthouden:

  • backendmetrics in de huidige Sentry PHP SDK moeten niet als volwaardige metricspipeline worden gezien,
  • User Feedback wordt in Sentry soms als beta of experimenteel gemarkeerd,
  • Replay moet voorzichtig worden ingevoerd en altijd met sterke masking,
  • te brede sampling in productie verhoogt datavolume en kosten snel.

Deze beperkingen diskwalificeren de oplossing niet. Ze vragen alleen om bewuste configuratie.

Samenvatting

Sentry in Magento 2 is zinvol wanneer het als volledige observabilitylaag wordt geimplementeerd en niet alleen als eenvoudig mechanisme om exceptions te versturen. Precies daarvoor dient Kowal_Sentry. Het combineert PHP-backend, JavaScript-frontend, tracing, checkout, cronmonitoring, releasestrategie en datasanitisatie in een coherente Magento-module.

Daardoor krijgt het technische team een echt hulpmiddel voor onderhoud en doorontwikkeling van de shop: met beter inzicht in fouten, snellere diagnose van regressies en meer controle over de stabiliteit van het verkoopproces.

Bronnen

  • 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/

Previous Next