Kowal_Sentry: installatie- en configuratiehandleiding

Doel van de module

Kowal_Sentry integreert Magento 2 met Sentry en maakt het mogelijk om te monitoren:

• PHP-backendfouten,
• JavaScript-fouten op de storefront en optioneel in het beheerpaneel,
• HTTP-, CLI- en cron-transacties,
• checkout breadcrumbs,
• Session Replay,
• User Feedback,
• release tracking en voorbereiding voor source maps.

De module is voorbereid als Composer-pakket en moet werken vanuit de locatie vendor/kowal/module-sentry.

Vereisten

• Magento Open Source / Adobe Commerce 2.4.x
• PHP 8.1+
• toegang tot Sentry en minimaal één project
• GitHub-token, als de repository via private vcs wordt geïnstalleerd

Installatie

De onderstaande commando's zijn gekopieerd uit 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

Belangrijk

• Het Composer-pakket moet alleen werken vanuit vendor/kowal/module-sentry.
• Bewaar dezelfde module niet tegelijkertijd in app/code/Kowal/Sentry.
• Na installatie vindt u de configuratie in:

Stores -> Configuration -> Kowal -> Sentry

Snelle start

Minimale configuratie die nodig is om de module te starten:

1. Stel Enable Module = Yes in.
2. Stel Environment in, bijvoorbeeld production of staging.
3. Schakel Enable Backend Monitoring in en plak Backend DSN.
4. Als u de frontend wilt monitoren, schakelt u Enable Frontend Monitoring in en plakt u Frontend DSN.
5. Sla de configuratie op en leeg de cache, als dit in de betreffende omgeving nodig is.

Waar haalt u gegevens uit Sentry vandaan

DSN

DSN vindt u meestal hier:

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

In de velden Backend DSN en Frontend DSN plakt u alleen de DSN-URL zelf, bijvoorbeeld:

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

Plak niet de volledige snippet:

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

Organization

De slug van de organisatie is het eenvoudigst af te lezen uit de URL van het Sentry-paneel, bijvoorbeeld:

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

In dit voorbeeld:

• acme is Organization
• shop-frontend is Project Slug

Project Slug

U kunt deze aflezen:

• uit de project-URL in het Sentry-paneel,
• of via Settings -> Projects -> [projekt] -> Details

Auth token voor source maps

Als u sentry-cli gebruikt, kunt u het token het beste buiten Magento bewaren, bijvoorbeeld in een omgevingsvariabele:

SENTRY_AUTH_TOKEN

Token aanmaken:

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

Verificatie na installatie

Na de basisconfiguratie kunt u controleren of de module actief is en of de SDK werkt. De onderstaande smoke-test-commando's zijn gekopieerd uit README.md.

Na het inschakelen van Enable Test Commands:

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

Configuratie in het Magento-paneel

Pad:

Stores -> Configuration -> Kowal -> Sentry

Hieronder vindt u een beschrijving van de afzonderlijke secties, mogelijkheden en instelvarianten.

Sectie General

Deze sectie beheert de activatie van de module, de omgeving en de manier waarop release wordt bepaald.

Enable Module

• Yes: start de module globaal.
• No: backend en frontend worden niet geïnitialiseerd, zelfs als andere opties zijn ingeschakeld.

Aanbeveling:

• Yes op de omgeving van waaruit u gegevens naar Sentry wilt verzenden.

Environment

Voorbeelden:

• production
• staging
• development

Varianten:

• één gezamenlijke naam voor de hele instantie,
• verschillende waarden per website/store view, als u events wilt scheiden.

Aanbeveling:

• zonder spaties en zonder schuine strepen,
• houd consistente naamgeving aan tussen backend, frontend en CI/CD.

Release Strategy

Beschikbare varianten:

• manual: release komt uit het veld Release Name Override
• env: release wordt opgehaald uit omgevingsvariabelen
• file: release wordt uit een bestand gelezen
• generated: release wordt automatisch door de module opgebouwd

Wanneer gebruiken:

• manual: wanneer u release handmatig wilt invoeren, eerder als noodoplossing of bij eenvoudige implementaties
• env: het beste in CI/CD, wanneer release via deployment wordt doorgegeven
• file: goed wanneer deployment de versie-identificatie naar een gedeeld bestand schrijft
• generated: goed als startpunt, als u nog geen volwassen release pipeline heeft

Ondersteunde omgevingsvariabelen:

• KOWAL_SENTRY_RELEASE
• SENTRY_RELEASE
• RELEASE_NAME
• GIT_COMMIT

Release Name Override

Alleen gebruikt bij de strategie manual.

Voorbeeld:

magento-store@2.4.7-p1+20260410.1

Aanbeveling:

• exact dezelfde waarde moet worden gebruikt bij de upload van source maps.

Project Name

Hulpnaam van het project in de contexten van de module. Dit is niet Project Slug uit Sentry.

Varianten:

• naam van de webshopinstantie,
• naam van de webshopgroep,
• naam van het interne project.

Debug Mode

• Yes: meer uitgebreide diagnostische logging
• No: productiemodus

Aanbeveling:

• No op productie,
• Yes tijdelijk wanneer u de configuratie diagnosticeert.

Enable Test Commands

• Yes: maakt testcommando's bin/magento beschikbaar
• No: verbergt ze tijdens normaal gebruik

Aanbeveling:

• Yes op staging of tijdens tests,
• No in een permanente productieconfiguratie.

Sectie Backend SDK

Heeft betrekking op de PHP SDK die wordt gebruikt door storefront HTTP, admin, API, cron en CLI.

Enable Backend Monitoring

• Yes: schakelt backendmonitoring in
• No: backend verzendt geen fouten en traces naar Sentry

Backend DSN

Dit is de basis-DSN voor PHP SDK.

Varianten:

• apart Sentry-project alleen voor backend
• hetzelfde project voor backend en frontend

Aanbeveling:

• houd bij meer volwassen implementaties aparte backend- en frontendprojecten aan,
• bij kleinere installaties kunt u beginnen met één gezamenlijk project.

Error Sample Rate

Bereik: 0-1

Voorbeelden:

• 1: verzend alle fouten
• 0.5: verzend ongeveer de helft
• 0.25: verzend ongeveer 25%

Aanbeveling:

• meestal 1.0 voor fouten, ten minste aan het begin.

Trace Sample Rate

Bereik: 0-1

Voorbeelden:

• 0.05: lage sampling, goed voor productie met veel verkeer
• 0.1: redelijk startpunt
• 0.2: meer gegevens ten koste van volume

Aanbeveling:

• op productie meestal 0.05-0.2, afhankelijk van verkeer en Sentry-plan.

Profile Sample Rate

Bereik: 0-1

Varianten:

• 0: profiling uitgeschakeld
• lage waarde, bijvoorbeeld 0.01: periodieke prestatiediagnose

Aanbeveling:

• 0 of een zeer lage waarde op productie.

Enable Logs

• Yes: verzendt structured logs
• No: geen logs in Sentry

Wanneer inschakelen:

• wanneer u logs wilt correleren met traces en errors.

Enable Metrics API

• Yes: schakelt de modulefaçade voor metrics in
• No: metrics aan modulezijde zijn niet actief

Let op:

• de huidige sentry/sentry 4.24.x behandelt backend metrics als een uitgefaseerde API / no-op.

Enable Cron Monitoring

• Yes: verzendt check-ins en cron-transacties
• No: cronjobs worden niet door Sentry gemonitord

U vindt de gegevens in Sentry in de sectie:

• Crons
• Monitors

Enable CLI Monitoring

• Yes: monitort bin/magento-commando's
• No: geen monitoring van CLI-processen

Nuttig voor:

• imports,
• herindexering,
• custom integratiecommando's.

Enable Adminhtml Monitoring

• Yes: monitort requests van het beheerpaneel
• No: beperkt backend tot storefront, API, cron en CLI

Enable API Monitoring

• Yes: monitort REST, GraphQL en andere endpoints
• No: sluit het integratiegedeelte uit van monitoring

Sectie Frontend SDK

Heeft betrekking op de Browser SDK die op de storefront en optioneel in het adminpaneel wordt geladen.

Enable Frontend Monitoring

• Yes: laadt de Browser SDK
• No: frontend verzendt geen gegevens naar Sentry

Frontend DSN

Varianten:

• apart frontendproject
• dezelfde DSN als backend
• leeg veld, zodat de module een fallback naar Backend DSN probeert

Aanbeveling:

• uiteindelijk een apart frontendproject, als u duidelijke Issues, Replay en Performance wilt hebben.

Enable Storefront JS

• Yes: Browser SDK werkt op de storefront
• No: geen SDK op het publieke deel van de webshop

Enable Admin JS

• Yes: Browser SDK werkt ook in het adminpaneel
• No: JS-monitoring beperkt tot de storefront

Aanbeveling:

• schakel alleen in wanneer u daadwerkelijk JS-problemen in admin diagnosticeert.

JS Trace Sample Rate

Bereik: 0-1

Voorbeelden:

• 0.01: zeer voorzichtig
• 0.05: goede start voor productie
• 0.1: meer gegevens, groter volume

JS Replay Session Sample Rate

Bereik: 0-1

Voorbeelden:

• 0: geen volledige replays
• 0.01: veilige start
• 0.05: meer gegevens voor analyse van UX en fouten

JS Replay On Error Sample Rate

Bereik: 0-1

Voorbeelden:

• 1: replay na elke fout in de sessie
• 0.5: replay na een deel van de fouten

Aanbeveling:

• vaak een beter startpunt dan hoge sampling van alle sessies.

Enable Session Replay

• Yes: schakelt Replay in
• No: geen sessie-opname

Aanbeveling:

• schakel in samen met sterke maskering van checkout en betalingen.

Enable User Feedback Widget

• Yes: Feedback-widget is beschikbaar
• No: widget wordt niet geladen

Let op:

• afhankelijk van het Sentry-plan en account kan de functie als beta / experimental zijn gemarkeerd.

Enable Checkout Instrumentation

• Yes: voegt checkout-breadcrumbs en tags toe
• No: geen aanvullende checkoutcontext

Aanbeveling:

• meestal is het de moeite waard om ingeschakeld te laten.

Enable Ajax Instrumentation

• Yes: breadcrumbs voor AJAX / fetch / XHR
• No: minder context voor frontendproblemen

Browser SDK CDN URL

Standaard verwijst dit naar de officiële Sentry-bundle.

Varianten:

• standaard-URL van de module
• eigen CDN-mirror
• vastgezette specifieke bundle / specifieke versie

Wijzig dit alleen wanneer:

• u een SDK-versie pint,
• u eigen CSP-regels heeft,
• u asset-mirroring gebruikt.

Sectie Privacy / Security

Deze sectie is verantwoordelijk voor het minimaliseren van het risico op verzending van gevoelige gegevens.

Send Default PII

• Yes: SDK kan de standaardset gebruikers- en requestgegevens verzenden
• No: conservatiever privacybeleid

Aanbeveling:

• meestal No.

Anonymize IP

• Yes: verstuur niet het volledige IP
• No: behoud standaardgedrag

Aanbeveling:

• meestal Yes.

Mask Customer Data

• Yes: maskeert klantgegevens
• No: minder gegevensbescherming

Aanbeveling:

• vrijwel altijd Yes op productie.

Mask Checkout Fields

• Yes: maskeert checkoutvelden
• No: risico op datalek uit checkout

Aanbeveling:

• altijd Yes.

Mask Payment Fields

• Yes: maskeert velden met betrekking tot betaling
• No: zeer risicovol

Aanbeveling:

• altijd Yes.

Block Authorization Headers

• Yes: verwijdert of maskeert Authorization en tokens
• No: risico op verzending van authenticatiegegevens

Aanbeveling:

• altijd Yes.

Block Cookies

• Yes: verwijdert cookies uit eventgegevens
• No: groter risico op lekkage van sessiegegevens

Aanbeveling:

• meestal Yes.

Block POST Bodies

• Yes: verwijdert POST-bodies
• No: verzendt meer requestgegevens

Aanbeveling:

• meestal Yes, vooral voor checkout, login en formulieren.

Redact Query Params

• Yes: maskeert query string-parameters
• No: query string blijft beter leesbaar, maar minder veilig

Additional Redacted Keys

Tekstveld voor extra sleutels die moeten worden geredigeerd.

Voorbeelden:

• token
• api_key
• customer_email
• external_customer_id

U kunt scheiden met:

• komma's,
• spaties,
• nieuwe regels.

Replay Mask Selectors

CSS-selectors waarvan de inhoud in Replay moet worden gemaskeerd.

Voorbeelden:

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

Replay Block Selectors

CSS-selectors die volledig moeten worden geblokkeerd in Replay.

Voorbeelden:

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

Allowed Domains for Replay Network Details

Lijst met domeinen waarvoor Replay details van netwerkrequests mag toevoegen.

Voorbeelden:

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

Aanbeveling:

• voer alleen eigen en vertrouwde domeinen in.

Sectie Filtering

Deze sectie beperkt ruis en eventvolume.

Ignore Exceptions Regex

Eén regex-regel per regel.

Voorbeelden van toepassing:

• bekende, ongevaarlijke technische fouten,
• exceptions uit externe integraties die al op een andere manier worden afgehandeld.

Ignore URLs Regex

Eén regex-regel per regel.

Voorbeelden:

• health-check-endpoints,
• testwebhooks,
• technische resources.

Ignore Transactions

Eén transactienaam per regel.

Aanbeveling:

• verzamel eerst gegevens,
• filter daarna transacties die weinig waarde hebben en repetitief zijn.

Ignore Bots

• Yes: sluit bot- en crawlerverkeer uit
• No: u monitort ook automatisch verkeer

Aanbeveling:

• Yes bij veel SEO-verkeer.

Ignore Health Checks

• Yes: slaat /health, /status, /ping en vergelijkbare requests over
• No: dergelijke requests gaan naar Sentry

Ignore Admin Routes

• Yes: beperkt events uit admin
• No: admin blijft gemonitord

Ignore Static Resource Errors

• Yes: filtert een deel van assetfouten .js en .css
• No: alle fouten van dit type blijven zichtbaar

Aanbeveling:

• meestal Yes, als u het project niet met ruis na deploys wilt vullen.

Sectie Context

Beheert de hoeveelheid bedrijfscontext die aan events wordt toegevoegd.

Attach Store Context

• Yes: voegt store_id, store_code, winkelnaam en valuta toe
• No: geen deze context

Aanbeveling:

• Yes, vooral bij multistore.

Attach Website Context

• Yes: voegt websitegegevens toe
• No: geen dit identificatieniveau

Attach Customer Context

• Yes: voegt geanonimiseerde klantcontext toe
• No: geen gegevens over klantstatus

Attach Quote Context

• Yes: voegt winkelwagen-/quote-context toe
• No: minder gegevens voor checkoutdiagnose

Attach Cart Totals

• Yes: voegt winkelwagentotalen toe
• No: lichter event

Aanbeveling:

• schakel alleen in wanneer deze gegevens daadwerkelijk helpen bij de analyse.

Attach Order Context

• Yes: voegt bestelcontext toe
• No: geen gegevens over order flow

Vooral nuttig voor:

• invoice,
• shipment,
• transactionele e-mails,
• ERP-/OMS-integraties.

Attach Product Context

• Yes: voegt basisproductcontext toe
• No: geen deze context

Attach Category Context

• Yes: voegt basiscategoriecontext toe
• No: geen deze context

Attach Payment / Shipping Method

• Yes: voegt payment_method en shipping_method toe
• No: minder gegevens voor checkout

Aanbeveling:

• dit is een van de waardevollere diagnostische instellingen.

Attach Module Version

• Yes: voegt de versie van Kowal_Sentry toe
• No: zonder deze informatie in events

Attach Magento Version

• Yes: voegt Magento-versie toe
• No: zonder platformcontext

Attach Deployment Metadata

• Yes: voegt aanvullende gegevens over deployment toe, als deze beschikbaar zijn
• No: geen deze metadata

Nuttig wanneer u een probleem snel wilt koppelen aan een rollout of specifieke build.

Sectie Source Maps / Release

Deze sectie ordent de parameters die nodig zijn voor release en source maps. De upload zelf moet plaatsvinden in CI/CD, niet tijdens Magento-runtime.

Enable Source Map Upload

• Yes: bevestigt dat u organisatorisch source maps gebruikt
• No: de module gaat niet uit van source maps in de configuratie

Let op:

• dit is een configuratievlag, geen uploadmechanisme.

Source Map Upload Mode

Varianten:

• manual: handmatige sentry-cli-commando's
• ci: upload in CI/CD-pipeline
• deploy_hook: upload in deployment hook

Aanbeveling:

• op productie meestal ci.

Assets Base URL

Voorbeeld:

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

Deze waarde moet overeenkomen met wat de Browser SDK in de stack trace ziet. Anders worden source maps niet gematcht.

Release Dist

Optionele dist voor release.

Voorbeelden:

• storefront
• admin
• pl-store

Gebruik wanneer één release meerdere assetvarianten heeft.

Organization

Organisatieslug gebruikt door sentry-cli en API.

Hoe vinden:

• uit de URL van het Sentry-paneel,
• bijvoorbeeld https://sentry.io/settings/acme/projects/shop-frontend/ -> acme

Project Slug

Projectslug gebruikt door release workflow en source maps.

Hoe vinden:

• uit de project-URL,
• of Settings -> Projects -> [projekt] -> Details

Release File Path

Pad naar het bestand met de releasenaam bij de strategie file.

Voorbeelden:

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

Sectie User Feedback

Configuratie van de widget voor problemmeldingen aan browserzijde.

Widget Theme

Varianten:

• light
• dark
• system

Aanbeveling:

• meestal system.

Widget Language

Voorbeelden:

• pl-PL
• en-US

Aanbeveling:

• stem in multistore af op de locale van de store view.

Auto-open after selected errors

• Yes: na geselecteerde frontendfouten kan een feedbackvoorstel verschijnen
• No: de widget opent niet automatisch

Aanbeveling:

• gebruik voorzichtig, zodat u niet te agressief bent voor de gebruiker.

Show on checkout success

• Yes: Feedback-trigger kan op de bestelbevestigingspagina verschijnen
• No: geen trigger op deze plek

Show on contact page

• Yes: trigger of widget op de contactpagina
• No: geen weergave op de contact page

Show in footer

• Yes: permanent zichtbare trigger in de footer of als vast element op de pagina
• No: geen permanente trigger

Dit is de eenvoudigste optie als u een knop Zglos problem wilt hebben.

Custom Trigger Selector

CSS-selector van een bestaand element dat Feedback opent.

Voorbeelden:

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

Gebruik dit veld als u de widget aan een eigen knop in layout of CMS block wilt koppelen.

Sectie Cron Monitoring

Deze sectie beheert check-ins en monitors voor Magento-cronjobs.

Enable auto-registration of configured cron jobs

• Yes: de eerste check-in kan een monitor in Sentry aanmaken of bijwerken
• No: de module verzendt check-ins zonder automatische monitorconfiguratie

Aanbeveling:

• Yes, als u een gecontroleerde deployment heeft en bewust gedefinieerde jobs.

Monitored job codes

Lijst met Magento job_code.

U kunt scheiden met:

• komma's,
• spaties,
• nieuwe regels.

Varianten:

• leeg veld: monitor alle cronjobs
• lijst met geselecteerde job_code: monitor alleen kritieke taken

Voorbeelden:

• sales_clean_quotes
• catalog_product_alert
• indexer_reindex_all_invalid

Timeout threshold per job

Eén regel per regel:

job_code:minutes

Voorbeeld:

catalog_product_alert:10

Gebruik wanneer cron soms onregelmatig wordt uitgevoerd en u valse alarmen wilt beperken.

Max runtime per job

Eén regel per regel:

job_code:minutes

Voorbeeld:

indexer_reindex_all_invalid:30

Na overschrijding van de limiet kan Sentry de monitor als problematisch markeren.

Check-in slug prefix

Voorbeeld:

magento-

Nuttig wanneer één Sentry-organisatie meerdere Magento-instanties monitort en u naamconflicten wilt vermijden.

Aanbevolen configuratieprofielen

Veilige productiestart

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

Diagnostisch profiel op staging

• hogere Trace Sample Rate, bijvoorbeeld 0.2
• hogere JS Trace Sample Rate, bijvoorbeeld 0.1
• tijdelijk Debug Mode = Yes
• Enable Test Commands = Yes
• voorzichtig met Replay: behoud nog steeds maskering en blokkades

Minimale variant alleen backend

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

Dit is een goede eerste stap als u eerst monitoring van exceptions en cronjobs aan PHP-zijde wilt starten.

Meest voorkomende configuratiefouten

• De volledige snippet Sentryinit(...) plakken in plaats van alleen de DSN.
• Gelijktijdige aanwezigheid van de module in vendor/ en app/code/.
• Verschillende waarden van release tussen events en source maps.
• Te agressieve Replay-sampling op productie.
• Uitschakelen van maskering van checkout en betalingen.
• Voorbeeld-DSN laten staan in een actieve configuratie.

Samenvatting

Het veiligst is om te beginnen met backendmonitoring, voorzichtige frontendmonitoring en restrictieve privacy-instellingen. Wanneer de gegevens in Sentry stabiel en duidelijk worden, kunt u trace sampling, Replay en de omvang van de bedrijfscontext geleidelijk verhogen.