Kowal_Sentry: installatie- en configuratiehandleiding

Doel van de module

Kowal_Sentry integreert Magento 2 met Sentry en maakt het mogelijk om het volgende 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 vanaf de locatie vendor/kowal/module-sentry.

Vereisten

• Magento Open Source / Adobe Commerce 2.4.x
• PHP 8.1+
• toegang tot Sentry en ten minste één project
• het e-mailadres van de klant en een licentietoken voor de Kowal Composer-repository

Installatie

De onderstaande opdrachten zijn gekopieerd uit README.md.

De toegangsgegevens voor de Composer-repository, het e-mailadres van de klant en het licentietoken, ontvangt u na aankoop per e-mail. Ze zijn ook beschikbaar in het klantenpaneel nadat u bent ingelogd op kowal.store. Vervang TWOJ_EMAIL_KLIENTA door het e-mailadres van uw account en TWOJ_TOKEN door het ontvangen token. Voer de opdrachten uit in de hoofdmap van 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

Belangrijk

• Het Composer-pakket mag 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 dat in de betreffende omgeving nodig is.

Waar vindt u de gegevens uit Sentry

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 het volledige snippet:

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

Organization

De slug van de organisatie leest u het eenvoudigst af 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-testopdrachten 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 instellingsvarianten.

Sectie General

Deze sectie regelt de activering van de module, de omgeving en de manier waarop release wordt berekend.

Enable Module

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

Aanbeveling:

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

Environment

Voorbeelden:

• production
• staging
• development

Varianten:

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

Aanbeveling:

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

Release Strategy

Beschikbare varianten:

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

Wanneer gebruiken:

• manual: wanneer u de release handmatig wilt invullen, eerder als noodoplossing of bij eenvoudige deployments
• env: het beste in CI/CD, wanneer de release door de deployment wordt doorgegeven
• file: geschikt wanneer de deployment de versie-identificatie in een gedeeld bestand opslaat
• generated: geschikt om mee te starten als u nog geen volwassen release-pipeline hebt

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 het uploaden van source maps.

Project Name

Een ondersteunende projectnaam in de contexten van de module. Dit is niet de Project Slug uit Sentry.

Varianten:

• naam van de winkelinstantie,
• naam van de winkelgroep,
• naam van het interne project.

Debug Mode

• Yes: uitgebreidere diagnostische logging
• No: productiemodus

Aanbeveling:

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

Enable Test Commands

• Yes: maakt testopdrachten 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: de backend verzendt geen fouten en traces naar Sentry

Backend DSN

Dit is de primaire DSN voor de PHP SDK.

Varianten:

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

Aanbeveling:

• houd bij meer volwassen deployments aparte backend- en frontendprojecten aan,
• bij kleinere installaties kunt u beginnen met één gemeenschappelijk 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 bij de start.

Trace Sample Rate

Bereik: 0-1

Voorbeelden:

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

Aanbeveling:

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

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 modulefacade voor metrics in
• No: metrics aan de 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: crons worden niet door Sentry gemonitord

U vindt de gegevens in Sentry in de sectie:

• Crons
• Monitors

Enable CLI Monitoring

• Yes: monitort bin/magento-opdrachten
• No: geen monitoring van CLI-processen

Nuttig voor:

• imports,
• herindexering,
• aangepaste integratieopdrachten.

Enable Adminhtml Monitoring

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

Enable API Monitoring

• Yes: monitort REST, GraphQL en andere endpoints
• No: sluit het integratiedeel 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: de frontend verzendt geen gegevens naar Sentry

Frontend DSN

Varianten:

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

Aanbeveling:

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

Enable Storefront JS

• Yes: Browser SDK werkt op de storefront
• No: geen SDK op het openbare deel van de winkel

Enable Admin JS

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

Aanbeveling:

• schakel dit 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 UX- en foutanalyse

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 betere start dan hoge sampling van alle sessies.

Enable Session Replay

• Yes: schakelt Replay in
• No: geen sessieopname

Aanbeveling:

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

Enable User Feedback Widget

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

Let op:

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

Enable Checkout Instrumentation

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

Aanbeveling:

• meestal is het de moeite waard om dit 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
• vastgepinde specifieke bundle / specifieke versie

Wijzig dit alleen wanneer:

• u de SDK-versie pint,
• u eigen CSP-regels hebt,
• u asset-mirroring gebruikt.

Sectie Privacy / Security

Deze sectie is verantwoordelijk voor het minimaliseren van het risico dat gevoelige gegevens worden verzonden.

Send Default PII

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

Aanbeveling:

• meestal No.

Anonymize IP

• Yes: stuur niet het volledige IP-adres door
• No: behoud het standaardgedrag

Aanbeveling:

• meestal Yes.

Mask Customer Data

• Yes: maskeert klantgegevens
• No: minder gegevensbescherming

Aanbeveling:

• praktisch altijd Yes op productie.

Mask Checkout Fields

• Yes: maskeert checkoutvelden
• No: risico op gegevenslekken uit de checkout

Aanbeveling:

• altijd Yes.

Mask Payment Fields

• Yes: maskeert velden die met betaling te maken hebben
• No: zeer riskant

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 lekken 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 geredigeerd moeten worden.

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 gemaskeerd moet worden.

Voorbeelden:

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

Replay Block Selectors

CSS-selectors die volledig in Replay moeten worden geblokkeerd.

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:

• vul alleen uw eigen en vertrouwde domeinen in.

Sectie Filtering

Deze sectie beperkt ruis en het volume van events.

Ignore Exceptions Regex

Eén regex-regel per regel.

Voorbeelden van gebruik:

• bekende, onschuldige 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 uit die weinig waarde hebben en repetitief zijn.

Ignore Bots

• Yes: sluit verkeer van bots en crawlers 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 komen in Sentry terecht

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 uw project niet wilt vullen met ruis na deployments.

Sectie Context

Regelt de hoeveelheid bedrijfscontext die aan events wordt toegevoegd.

Attach Store Context

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

Aanbeveling:

• Yes, vooral bij multistore.

Attach Website Context

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

Attach Customer Context

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

Attach Quote Context

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

Attach Cart Totals

• Yes: voegt winkelwagentotalen toe
• No: lichter event

Aanbeveling:

• schakel dit 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: deze context ontbreekt

Attach Category Context

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

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 de Magento-versie toe
• No: zonder platformcontext

Attach Deployment Metadata

• Yes: voegt extra deploymentgegevens toe als die beschikbaar zijn
• No: deze metadata ontbreekt

Nuttig wanneer u een probleem snel wilt koppelen aan een rollout of een 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 en niet tijdens Magento runtime.

Enable Source Map Upload

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

Let op:

• dit is een configuratieflag, geen uploadmechanisme.

Source Map Upload Mode

Varianten:

• manual: handmatige sentry-cli-opdrachten
• ci: upload in de CI/CD-pipeline
• deploy_hook: upload in de 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 de release.

Voorbeelden:

• storefront
• admin
• pl-store

Gebruik dit wanneer één release meerdere assetvarianten heeft.

Organization

De organisatie-slug die door sentry-cli en API wordt gebruikt.

Hoe te vinden:

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

Project Slug

De projectslug die wordt gebruikt door de release- en source maps-workflow.

Hoe te 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 probleemmeldingen aan de browserzijde.

Widget Theme

Varianten:

• light
• dark
• system

Aanbeveling:

• meestal system.

Widget Language

Voorbeelden:

• pl-PL
• en-US

Aanbeveling:

• stem dit bij 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 wordt niet automatisch geopend

Aanbeveling:

• gebruik dit voorzichtig, zodat het niet te opdringerig is voor de gebruiker.

Show on checkout success

• Yes: de Feedback-trigger kan op de succespagina van de bestelling 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 van 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 uw eigen knop in de layout of in een CMS block wilt koppelen.

Sectie Cron Monitoring

Deze sectie regelt check-ins en monitors voor Magento-crons.

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 en bewust gedefinieerde jobs hebt.

Monitored job codes

Lijst met Magento job_code.

U kunt scheiden met:

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

Varianten:

• leeg veld: monitor alle crons
• 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 dit wanneer een 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 voor 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 exception- en cronmonitoring aan de PHP-zijde wilt starten.

Meest voorkomende configuratiefouten

• Het volledige snippet \Sentry\init(...) plakken in plaats van alleen de DSN.
• De module tegelijkertijd aanwezig hebben in vendor/ en app/code/.
• Verschillende waarden voor release tussen events en source maps.
• Te agressieve Replay-sampling op productie.
• Het uitschakelen van maskering van checkout en betalingen.
• Een voorbeeld-DSN in de actieve configuratie laten staan.

Samenvatting

Het veiligst is om te beginnen met backendmonitoring, voorzichtige frontendmonitoring en strikte privacyinstellingen. Wanneer de gegevens in Sentry stabiel en overzichtelijk worden, kunt u trace sampling, Replay en de omvang van de bedrijfscontext geleidelijk vergroten.