Kowal_Sentry installation and configuration guide

Module goal

Kowal_Sentry integrates Magento 2 with Sentry and allows you to monitor:

• PHP backend errors,
• JavaScript errors on the storefront and optionally in the admin panel,
• HTTP, CLI, and cron transactions,
• checkout breadcrumbs,
• Session Replay,
• User Feedback,
• release tracking and source map readiness.

The module is distributed as a Composer package and should run from vendor/kowal/module-sentry.

Requirements

• Magento Open Source / Adobe Commerce 2.4.x
• PHP 8.1+
• access to Sentry and at least one project
• GitHub token if the repository is installed via a private vcs

Installation

The commands below were copied from README.md.

composer config repositories.sentry vcs https://github.com/kowalco/sentrycomposer config --global --auth github-oauth.github.com <YOUR_TOKEN>composer require kowal/module-sentrybin/magento module:enable Kowal_Sentrybin/magento setup:upgradebin/magento cache:flush

Important

• The Composer package should work only from vendor/kowal/module-sentry.
• Do not keep the same module simultaneously in app/code/Kowal/Sentry.
• After installation, configuration can be found at:

Stores -> Configuration -> Kowal -> Sentry

Quick start

Minimal configuration required to start the module:

1. Set Enable Module = Yes.
2. Set Environment, for example production or staging.
3. Enable Enable Backend Monitoring and paste the Backend DSN.
4. If you want frontend monitoring, enable Enable Frontend Monitoring and paste the Frontend DSN.
5. Save configuration and clear cache if required in your environment.

Where to get Sentry settings

DSN

You can usually find DSN here:

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

For Backend DSN and Frontend DSN, paste only the DSN URL itself, for example:

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

Do not paste the full snippet:

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

Organization

The organization slug is easiest to read from the Sentry URL, for example:

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

In this example:

• acme is the Organization
• shop-frontend is the Project Slug

Project Slug

You can read it:

• from the project URL in Sentry,
• or from Settings -> Projects -> [project] -> Details.

Auth token for source maps

If you use sentry-cli, it is best to keep the token outside Magento, for example in an environment variable:

SENTRY_AUTH_TOKEN

Token creation:

• Settings -> Custom Integrations
• or User Settings -> Personal Tokens.

Post-install verification

After basic configuration, you can verify that the module is active and the SDK works. The smoke-test commands below were copied from README.md.

After enabling Enable Test Commands:

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

Configuration in Magento Admin

Path:

Stores -> Configuration -> Kowal -> Sentry

Below is an explanation of each section, available options, and configuration variants.

General section

This section controls module activation, environment, and how release is calculated.

Enable Module

• Yes enables the module globally.
• No disables backend and frontend initialization even if other options are enabled.

Recommendation:

• Use Yes in environments where you want to send data to Sentry.

Environment

Examples:

• production
• staging
• development

Variants:

• one shared name for the entire instance,
• different values per website or store view if you need to split events.

Recommendation:

• avoid spaces and slashes,
• keep naming consistent between backend, frontend, and CI/CD.

Release Strategy

Available variants:

• manual release is taken from Release Name Override
• env release is taken from environment variables
• file release is read from a file
• generated release is composed automatically by the module

When to use:

• manual when you want to set release manually, typically for simple deployments
• env best for CI/CD where release is passed by the deployment
• file good when deployment writes a version identifier into a shared file
• generated good as a starting point if you do not have a mature release pipeline yet

Supported environment variables:

• KOWAL_SENTRY_RELEASE
• SENTRY_RELEASE
• RELEASE_NAME
• GIT_COMMIT

Release Name Override

Used only with manual strategy.

Example:

magento-store@2.4.7-p1+20260410.1

Recommendation:

• use the exact same value when uploading source maps.

Project Name

An auxiliary project name used in module contexts. This is not the Sentry Project Slug.

Variants:

• store instance name,
• store group name,
• internal project name.

Debug Mode

• Yes enables more verbose diagnostic logging
• No production mode

Recommendation:

• No in production,
• Yes temporarily when diagnosing configuration.

Enable Test Commands

• Yes exposes test commands in bin/magento
• No hides them during normal operation

Recommendation:

• Yes on staging or during testing,
• No for a permanent production setup.

Backend SDK section

Applies to the PHP SDK used by storefront HTTP, admin, API, cron, and CLI.

Enable Backend Monitoring

• Yes enables backend monitoring
• No backend will not send errors or traces to Sentry

Backend DSN

The primary DSN for the PHP SDK.

Variants:

• a separate Sentry project for backend only
• the same project for both backend and frontend

Recommendation:

• for mature deployments, keep separate backend and frontend projects,
• for smaller installations, you can start with a single shared project.

Error Sample Rate

Range: 0-1

Examples:

• 1 send all errors
• 0.5 send about half
• 0.25 send about 25 percent

Recommendation:

• typically 1.0 for errors, at least at the beginning.

Trace Sample Rate

Range: 0-1

Examples:

• 0.05 low sampling, good for high-traffic production
• 0.1 reasonable starting point
• 0.2 more data at higher volume cost

Recommendation:

• in production usually 0.05-0.2, depending on traffic and Sentry plan.

Profile Sample Rate

Range: 0-1

Variants:

• 0 profiling disabled
• low value such as 0.01 periodic performance diagnostics

Recommendation:

• 0 or a very low value in production.

Enable Logs

• Yes sends structured logs
• No no logs in Sentry

When to enable:

• when you want to correlate logs with traces and errors.

Enable Metrics API

• Yes enables the module metrics facade
• No module-side metrics will not be active

Note:

• current sentry/sentry 4.24.x treats backend metrics as a deprecated API and a no-op.

Enable Cron Monitoring

• Yes sends cron check-ins and transactions
• No cron jobs will not be monitored by Sentry

You can find the data in Sentry under:

• Crons
• Monitors

Enable CLI Monitoring

• Yes monitors bin/magento commands
• No no CLI process monitoring

Useful for:

• imports,
• reindexing,
• custom integration commands.

Enable Adminhtml Monitoring

• Yes monitors admin panel requests
• No limits backend to storefront, API, cron, and CLI

Enable API Monitoring

• Yes monitors REST, GraphQL, and other endpoints
• No disables the integration layer from monitoring

Frontend SDK section

Applies to the Browser SDK loaded on the storefront and optionally in the admin panel.

Enable Frontend Monitoring

• Yes loads the Browser SDK
• No frontend will not send data to Sentry

Frontend DSN

Variants:

• a separate frontend project
• the same DSN as backend
• empty field so the module tries to fall back to Backend DSN

Recommendation:

• ideally a separate frontend project for clear Issues, Replay, and Performance.

Enable Storefront JS

• Yes Browser SDK runs on the storefront
• No no SDK on the public site

Enable Admin JS

• Yes Browser SDK also runs in admin
• No JS monitoring is limited to storefront

Recommendation:

• enable only when you actually need to diagnose JS issues in admin.

JS Trace Sample Rate

Range: 0-1

Examples:

• 0.01 very cautious
• 0.05 good production starting point
• 0.1 more data, higher volume

JS Replay Session Sample Rate

Range: 0-1

Examples:

• 0 no full replays
• 0.01 safe start
• 0.05 more data for UX and error analysis

JS Replay On Error Sample Rate

Range: 0-1

Examples:

• 1 replay after every error in a session
• 0.5 replay for a portion of error sessions

Recommendation:

• often a better starting point than high sampling for all sessions.

Enable Session Replay

• Yes enables Replay
• No no session recording

Recommendation:

• enable together with strong masking for checkout and payments.

Enable User Feedback Widget

• Yes Feedback widget is available
• No widget is not loaded

Note:

• depending on Sentry plan and account, this feature may be marked beta or experimental.

Enable Checkout Instrumentation

• Yes adds checkout breadcrumbs and tags
• No no additional checkout context

Recommendation:

• typically worth keeping enabled.

Enable Ajax Instrumentation

• Yes breadcrumbs for AJAX, fetch, XHR
• No less context for frontend issues

Browser SDK CDN URL

By default it points to the official Sentry bundle.

Variants:

• module default URL
• custom CDN mirror
• pinned bundle or pinned version

Change only if:

• you pin SDK versions,
• you have custom CSP rules,
• you mirror assets.

Privacy / Security section

This section minimizes the risk of sending sensitive data.

Send Default PII

• Yes SDK may send the default set of user and request data
• No more conservative privacy policy

Recommendation:

• usually No.

Anonymize IP

• Yes do not send the full IP address
• No keep default behavior

Recommendation:

• usually Yes.

Mask Customer Data

• Yes masks customer data
• No less data protection

Recommendation:

• almost always Yes in production.

Mask Checkout Fields

• Yes masks checkout fields
• No risk of data leakage from checkout

Recommendation:

• always Yes.

Mask Payment Fields

• Yes masks payment-related fields
• No very risky

Recommendation:

• always Yes.

Block Authorization Headers

• Yes removes or masks Authorization and tokens
• No risk of sending authentication data

Recommendation:

• always Yes.

Block Cookies

• Yes removes cookies from event data
• No higher risk of session data leakage

Recommendation:

• usually Yes.

Block POST Bodies

• Yes removes POST bodies
• No sends more request data

Recommendation:

• usually Yes, especially for checkout, login, and forms.

Redact Query Params

• Yes masks query string parameters
• No query string remains more readable but less secure

Additional Redacted Keys

Text field for additional keys to redact.

Examples:

• token
• api_key
• customer_email
• external_customer_id

You can separate values by:

• commas,
• spaces,
• new lines.

Replay Mask Selectors

CSS selectors whose content should be masked in Replay.

Examples:

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

Replay Block Selectors

CSS selectors that should be fully blocked in Replay.

Examples:

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

Allowed Domains for Replay Network Details

List of domains for which Replay may attach network request details.

Examples:

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

Recommendation:

• enter only your own and trusted domains.

Filtering section

This section reduces noise and event volume.

Ignore Exceptions Regex

One regex rule per line.

Typical use cases:

• known harmless technical errors,
• exceptions from external integrations already handled elsewhere.

Ignore URLs Regex

One regex rule per line.

Examples:

• health-check endpoints,
• test webhooks,
• technical assets.

Ignore Transactions

One transaction name per line.

Recommendation:

• collect data first,
• then filter low-value and repetitive transactions.

Ignore Bots

• Yes filters bots and crawlers
• No monitors automated traffic as well

Recommendation:

• Yes for high SEO traffic.

Ignore Health Checks

• Yes skips /health, /status, /ping, and similar routes
• No those requests will be sent to Sentry

Ignore Admin Routes

• Yes reduces events from admin
• No admin remains monitored

Ignore Static Resource Errors

• Yes filters some asset errors for .js and .css
• No all such errors remain visible

Recommendation:

• usually Yes if you do not want to flood the project with noise after deployments.

Context section

Controls how much business context is attached to events.

Attach Store Context

• Yes attaches store_id, store_code, store name, and currency
• No no store context

Recommendation:

• Yes, especially for multistore.

Attach Website Context

• Yes attaches website data
• No no website-level identification

Attach Customer Context

• Yes attaches anonymized customer context
• No no customer status data

Attach Quote Context

• Yes attaches cart or quote context
• No less data for checkout diagnosis

Attach Cart Totals

• Yes attaches cart totals
• No lighter event payload

Recommendation:

• enable only if it truly helps your analysis.

Attach Order Context

• Yes attaches order context
• No no order flow data

Especially useful for:

• invoices,
• shipments,
• transactional emails,
• ERP or OMS integrations.

Attach Product Context

• Yes attaches basic product context
• No no product context

Attach Category Context

• Yes attaches basic category context
• No no category context

Attach Payment / Shipping Method

• Yes attaches payment_method and shipping_method
• No less checkout data

Recommendation:

• one of the most valuable diagnostic settings.

Attach Module Version

• Yes attaches Kowal_Sentry version
• No no module version in events

Attach Magento Version

• Yes attaches Magento version
• No no platform context

Attach Deployment Metadata

• Yes attaches extra deployment metadata if available
• No no deployment metadata

Useful when you want to quickly link an issue to a rollout or a specific build.

Source Maps / Release section

This section organizes parameters needed for release and source maps. Upload should be done in CI/CD, not during Magento runtime.

Enable Source Map Upload

• Yes confirms you use source maps organizationally
• No module will not assume source maps in configuration

Note:

• this is a configuration flag, not an upload mechanism.

Source Map Upload Mode

Variants:

• manual manual sentry-cli commands
• ci upload in CI/CD pipeline
• deploy_hook upload in deployment hook

Recommendation:

• in production most often ci.

Assets Base URL

Example:

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

This value must match what the Browser SDK sees in stack traces, otherwise source maps will not resolve.

Release Dist

Optional dist for the release.

Examples:

• storefront
• admin
• pl-store

Use when one release has multiple asset variants.

Organization

Organization slug used by sentry-cli and the API.

How to find it:

• from the Sentry URL,
• for example https://sentry.io/settings/acme/projects/shop-frontend/ -> acme

Project Slug

Project slug used by the release and source maps workflow.

How to find it:

• from the project URL,
• or Settings -> Projects -> [project] -> Details.

Release File Path

Path to the release name file when using file strategy.

Examples:

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

User Feedback section

Configuration for the in-browser issue reporting widget.

Widget Theme

Variants:

• light
• dark
• system

Recommendation:

• usually system.

Widget Language

Examples:

• pl-PL
• en-US

Recommendation:

• in multistore, match the store view locale.

Auto-open after selected errors

• Yes after selected frontend errors, a feedback prompt may appear
• No the widget will not open automatically

Recommendation:

• use cautiously to avoid being too aggressive for users.

Show on checkout success

• Yes Feedback trigger may appear on the order success page
• No no trigger in that location

Show on contact page

• Yes trigger or widget on the contact page
• No no exposure on contact page

Show in footer

• Yes always-visible trigger in the footer or as a persistent page element
• No no persistent trigger

This is the simplest option if you want a Report an issue button.

Custom Trigger Selector

CSS selector of an existing element that opens Feedback.

Examples:

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

Use this field if you want to attach the widget to your own button in a layout or CMS block.

Cron Monitoring section

This section controls check-ins and monitors for Magento cron jobs.

Enable auto-registration of configured cron jobs

• Yes the first check-in may create or update the monitor in Sentry
• No the module sends check-ins without auto-configuring the monitor

Recommendation:

• Yes if you have controlled deployments and deliberately defined jobs.

Monitored job codes

List of Magento job_code values.

You can separate values by:

• commas,
• spaces,
• new lines.

Variants:

• empty field monitor all cron jobs
• selected job_code list monitor only critical jobs

Examples:

• sales_clean_quotes
• catalog_product_alert
• indexer_reindex_all_invalid

Timeout threshold per job

One rule per line:

job_code:minutes

Example:

catalog_product_alert:10

Use when a cron runs irregularly and you want to reduce false alerts.

Max runtime per job

One rule per line:

job_code:minutes

Example:

indexer_reindex_all_invalid:30

After exceeding the limit, Sentry may flag the monitor as unhealthy.

Check-in slug prefix

Example:

magento-

Useful when one Sentry organization monitors multiple Magento instances and you want to avoid naming collisions.

Recommended configuration profiles

Safe production start

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

Diagnostic profile for staging

• higher Trace Sample Rate, for example 0.2
• higher JS Trace Sample Rate, for example 0.1
• temporarily Debug Mode = Yes
• Enable Test Commands = Yes
• be cautious with Replay keep masking and blocks enabled

Minimal backend-only variant

• Enable Backend Monitoring = Yes
• Backend DSN filled in
• Enable Frontend Monitoring = No

This is a good first step if you want to start with PHP exception and cron monitoring first.

Most common configuration mistakes

• Pasting the full Sentryinit(...) snippet instead of only the DSN.
• Keeping the module both in vendor/ and app/code/ at the same time.
• Different release values between events and source maps.
• Overly aggressive Replay sampling in production.
• Disabling checkout and payment masking.
• Leaving an example DSN in an active configuration.

Summary

The safest approach is to start with backend monitoring, cautious frontend monitoring, and strict privacy settings. Once Sentry data becomes stable and readable, you can gradually increase trace sampling, Replay, and business context scope.