Kowal_Sentry: installation and configuration guide

Module purpose

Kowal_Sentry integrates Magento 2 with Sentry and lets you 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 preparation for source maps.

The module was prepared as a Composer package and should run from the vendor/kowal/module-sentry location.

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 through 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 composer require kowal/module-sentrybin/magento module:enable Kowal_Sentrybin/magento setup:upgradebin/magento cache:flush

Important

• The Composer package is intended to work only from vendor/kowal/module-sentry.
• Do not keep the same module in app/code/Kowal/Sentry at the same time.
• After installation, you can find the configuration at:

Stores -> Configuration -> Kowal -> Sentry

Quick start

Minimum configuration required to run 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 to monitor the frontend, enable Enable Frontend Monitoring and paste the Frontend DSN.
5. Save the configuration and clear the cache if needed in the given environment.

Where to get the data from Sentry

DSN

You can usually find the DSN here:

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

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

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

Do not paste the entire snippet:

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

Organization

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

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

In this example:

• acme is Organization
• shop-frontend is Project Slug

Project Slug

You can read it from:

• the project URL in the Sentry panel,
• or from Settings -> Projects -> [projekt] -> 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

Creating a token:

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

Verification after installation

After basic configuration, you can check whether the module is active and whether 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 the Magento panel

Path:

Stores -> Configuration -> Kowal -> Sentry

Below is a description of each section, its capabilities, and setting variants.

General section

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

Enable Module

• Yes: enables the module globally.
• No: the backend and frontend will not be initialized, even if other options are enabled.

Recommendation:

• Yes in the environment 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/store view if you need to separate events.

Recommendation:

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

Release Strategy

Available variants:

• manual: release comes from the Release Name Override field
• env: release is loaded from environment variables
• file: release is read from a file
• generated: release is assembled automatically by the module

When to use:

• manual: when you want to enter the release manually, usually as a fallback or in simple deployments
• env: best for CI/CD when the release is passed by deployment
• file: good when deployment writes the version identifier to a shared file
• generated: good for getting started 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 the manual strategy.

Example:

magento-store@2.4.7-p1+20260410.1

Recommendation:

• the exact same value should be used when uploading source maps.

Project Name

Auxiliary project name in module contexts. This is not the Sentry Project Slug.

Variants:

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

Debug Mode

• Yes: more verbose diagnostic logging
• No: production mode

Recommendation:

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

Enable Test Commands

• Yes: makes test bin/magento commands available
• No: hides them during normal operation

Recommendation:

• Yes on staging or during testing,
• No in the permanent production configuration.

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: the backend does not send errors and traces to Sentry

Backend DSN

This is the primary DSN for the PHP SDK.

Variants:

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

Recommendation:

• in more mature implementations, keep separate backend and frontend projects,
• in smaller installations, you can start with one shared project.

Error Sample Rate

Range: 0-1

Examples:

• 1: send all errors
• 0.5: send about half
• 0.25: send about 25%

Recommendation:

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

Trace Sample Rate

Range: 0-1

Examples:

• 0.05: low sampling, good for production with high traffic
• 0.1: a reasonable starting point
• 0.2: more data at the cost of volume

Recommendation:

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

Profile Sample Rate

Range: 0-1

Variants:

• 0: profiling disabled
• low value, for example 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 facade for metrics
• No: metrics on the module side will not be active

Note:

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

Enable Cron Monitoring

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

You can find the data in Sentry in the section:

• 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 the backend to the storefront, API, cron, and CLI

Enable API Monitoring

• Yes: monitors REST, GraphQL, and other endpoints
• No: excludes the integration part 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: the frontend does not send data to Sentry

Frontend DSN

Variants:

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

Recommendation:

• ultimately, use a separate frontend project if you want clear Issues, Replay, and Performance.

Enable Storefront JS

• Yes: Browser SDK runs on the storefront
• No: no SDK on the public part of the store

Enable Admin JS

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

Recommendation:

• enable only when you are actually diagnosing JS issues in the admin.

JS Trace Sample Rate

Range: 0-1

Examples:

• 0.01: very cautious
• 0.05: good start for production
• 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 the session
• 0.5: replay after some errors

Recommendation:

• often a better start than high sampling of all sessions.

Enable Session Replay

• Yes: enables Replay
• No: no session recording

Recommendation:

• enable together with strong masking of checkout and payment data.

Enable User Feedback Widget

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

Note:

• depending on the Sentry plan and account, the feature may be marked as beta / experimental.

Enable Checkout Instrumentation

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

Recommendation:

• it is usually worth leaving 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:

• default module URL
• custom CDN mirror
• pinned specific bundle / specific version

Change only when:

• you pin the SDK version,
• you have custom CSP rules,
• you use asset mirroring.

Privacy / Security section

This section is responsible for minimizing the risk of sending sensitive data.

Send Default PII

• Yes: the 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
• No: keep the standard 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 checkout data leakage

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: the 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 them with:

• 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 include 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 limits noise and event volume.

Ignore Exceptions Regex

One regex rule per line.

Use case examples:

• known, harmless technical errors,
• exceptions from external integrations that are already handled differently.

Ignore URLs Regex

One regex rule per line.

Examples:

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

Ignore Transactions

One transaction name per line.

Recommendation:

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

Ignore Bots

• Yes: cuts off bot and crawler traffic
• No: you also monitor automated traffic

Recommendation:

• Yes for high SEO traffic.

Ignore Health Checks

• Yes: skips /health, /status, /ping, and similar requests
• No: such requests are sent to Sentry

Ignore Admin Routes

• Yes: limits admin events
• No: admin remains monitored

Ignore Static Resource Errors

• Yes: filters some asset errors for .js and .css
• No: all errors of this type remain visible

Recommendation:

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

Context section

Controls the amount of business context added to events.

Attach Store Context

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

Recommendation:

• Yes, especially for multistore.

Attach Website Context

• Yes: attaches website data
• No: no this level of identification

Attach Customer Context

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

Attach Quote Context

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

Attach Cart Totals

• Yes: attaches cart totals
• No: lighter event

Recommendation:

• enable only when this data actually helps with analysis.

Attach Order Context

• Yes: attaches order context
• No: no data about the order flow

Especially useful for:

• invoice,
• shipment,
• transactional emails,
• ERP / OMS integrations.

Attach Product Context

• Yes: attaches basic product context
• No: no this context

Attach Category Context

• Yes: attaches basic category context
• No: no this context

Attach Payment / Shipping Method

• Yes: attaches payment_method and shipping_method
• No: less data for checkout

Recommendation:

• this is one of the more valuable diagnostic settings.

Attach Module Version

• Yes: attaches the Kowal_Sentry version
• No: no this information in events

Attach Magento Version

• Yes: attaches the Magento version
• No: no platform context

Attach Deployment Metadata

• Yes: attaches additional deployment data if available
• No: no this metadata

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

Source Maps / Release section

This section organizes the parameters needed for release and source maps. The upload itself should happen in CI/CD, not during Magento runtime.

Enable Source Map Upload

• Yes: confirms that you organizationally use source maps
• No: the module does not assume source maps in the configuration

Note:

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

Source Map Upload Mode

Variants:

• manual: manual sentry-cli commands
• ci: upload in the CI/CD pipeline
• deploy_hook: upload in a 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 the stack trace. Otherwise, source maps will not be matched.

Release Dist

Optional dist for release.

Examples:

• storefront
• admin
• pl-store

Use when one release has several asset variants.

Organization

Organization slug used by sentry-cli and API.

How to find it:

• from the Sentry panel 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 -> [projekt] -> Details

Release File Path

Path to the file with the release name for the file strategy.

Examples:

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

User Feedback section

Configuration of the browser-side issue reporting widget.

Widget Theme

Variants:

• light
• dark
• system

Recommendation:

• usually system.

Widget Language

Examples:

• pl-PL
• en-US

Recommendation:

• in multistore, match it to the store view locale.

Auto-open after selected errors

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

Recommendation:

• use carefully so you are not too aggressive for the user.

Show on checkout success

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

Show on contact page

• Yes: trigger or widget on the contact page
• No: no exposure on the 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 to have a Zglos problem 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 connect the widget to your own button in the layout or CMS block.

Cron Monitoring section

This section controls check-ins and monitors for Magento crons.

Enable auto-registration of configured cron jobs

• Yes: the first check-in may create or update a monitor in Sentry
• No: the module sends check-ins without automatic monitor configuration

Recommendation:

• Yes if you have a controlled deployment and consciously defined jobs.

Monitored job codes

List of Magento job_code.

You can separate them with:

• commas,
• spaces,
• new lines.

Variants:

• empty field: monitor all crons
• list of selected job_code: monitor only critical tasks

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 sometimes 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 the limit is exceeded, Sentry may mark the monitor as problematic.

Check-in slug prefix

Example:

magento-

Useful when one Sentry organization monitors several Magento instances and you want to avoid name 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 careful with Replay: still maintain masking and blocking

Minimal backend-only variant

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

This is a good first step if you want to start by enabling exception and cron monitoring on the PHP side.

Most common configuration errors

• Pasting the entire Sentryinit(...) snippet instead of only the DSN.
• Having the module present in both 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 data masking.
• Leaving the example DSN in an active configuration.

Summary

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