README

Magento 2 Sentry Logger

This Magento 2 module integrates Sentry into magento 2. Depending on the log level configured in the backend of magento 2, notifications and errors can be sent to sentry.

Features

Send exceptions and logs to Sentry
Show detailed context on thrown exceptions (Like Magento user/api consumer id)
Easily control which events get sent to Sentry
Backend and frontend error reporting
Performance sampling (tracing & profiling)
- Database Queries (Detect N+1 queries)
- Events
- Template rendering
- Cache monitoring
- Queue monitoring
Cron Monitoring
Session replay
Sentry feedback form after an error

LogRocket? LogRocket support moved out of this module into justbetter/magento2-sentry-logrocket as of 5.0.0. If you were using it before, install that module — no configuration changes needed.

Installation

composer require justbetter/magento2-sentry
bin/magento module:enable JustBetter_Core JustBetter_Sentry
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento setup:static-content:deploy

Configuration

For configuration with Adobe Cloud, check below.

This module uses the Magento Deployment Configuration for most it's configuration. This means that you need to add this array to your app/etc/env.php:

'sentry' => [
    'dsn' => 'example.com',
    'environment' => null,
    'log_level' => \Monolog\Level::Warning->value,
    'exception_log_levels' => [
        \GraphQL\Error\Error::class => \Monolog\Level::Error->value,
    ],
    'graphql_report_client_safe_errors' => false,
    'error_types' => E_ALL,
    'ignore_exceptions' => [],
    'mage_mode_development' => false,
    'js_sdk_version' => \JustBetter\Sentry\Block\SentryScript::CURRENT_VERSION,
    'tracing_enabled' => true,
    'traces_sample_rate' => 0.5,
    'disable_default_integrations' => [
        \Sentry\Integration\ModulesIntegration::class,
    ],
    'performance_tracking_enabled' => true,
    'performance_tracking_excluded_areas' => [\Magento\Framework\App\Area::AREA_ADMINHTML, \Magento\Framework\App\Area::AREA_CRONTAB],
    'profiles_sample_rate' => 0.5,
    'ignore_js_errors' => [],
    'enable_csp_report_url' => true,
    // Resilient delivery
    'async_sending_enabled' => true,
    'circuit_breaker_failure_threshold' => 5,
    'circuit_breaker_recovery_timeout' => 60,
    'circuit_breaker_success_threshold' => 2,
    'http_timeout' => 2,
    'http_connect_timeout' => 1,
]

Next to that there are some configuration options under Stores > Configuration > JustBetter > Sentry.

Configuration values

Name	Default	Description
`dsn`	—	The DSN you got from Sentry for your project. You can find the DSN in the project settings under "Client Key (DSN)"
`release`	the current deployed version in `deployed_version.txt`	Specify the current release version. Example with dynamic git hash: `trim(exec('git --git-dir ' . BP . '/.git' . ' log --pretty="%h" -n1 HEAD'))`
`mage_mode_development`	`false`	If set to true, you will receive issues in Sentry even if Magento is running in develop mode.
`environment`	—	Specify the environment under which the deployed version is running. Common values: production, staging, development. Helps differentiate errors between environments.
`max_breadcrumbs`	`100`	This variable controls the total amount of breadcrumbs that should be captured.
`attach_stacktrace`	`false`	When enabled, stack traces are automatically attached to all messages logged. Even if they are not exceptions.
`prefixes`	[BP]	A list of prefixes that should be stripped from the filenames of captured stacktraces to make them relative.
`sample_rate`	`1.0`	Configures the sample rate for error events, in the range of 0.0 to 1.0.
`ignore_exceptions`	`[]`	If the class being thrown matches any in this list, do not send it to Sentry, e.g., `[\Magento\Framework\Exception\NoSuchEntityException::class]`
`error_types`	`E_ALL`	If the Exception is an instance of ErrorException, send the error to Sentry if it matches the error reporting. Uses the same syntax as Error Reporting, e.g., `E_ERROR`
`log_level`	`\Monolog\Level::Warning`	Specify from which logging level on Sentry should get the messages.
`exception_log_levels`	`[]`	Override `log_level` per exception class, e.g. `[\GraphQL\Error\Error::class => \Monolog\Level::Error->value]`. Previous exceptions are checked as well, the first match wins. See GraphQL errors.
`graphql_report_client_safe_errors`	`false`	If set to true, client safe GraphQL errors (e.g. not logged in or an invalid coupon code) also use `exception_log_levels`. Otherwise they use `log_level`.
`clean_stacktrace`	`true`	Whether unnecessary files (like Interceptor.php, Proxy.php, and Factory.php) should be removed from the stacktrace. (They will not be removed if they threw the error.)
`tracing_enabled`	`false`	If set to true, tracing is enabled (bundle file is loaded automatically).
`traces_sample_rate`	`0.2`	If tracing is enabled, set the sample rate. A number between 0 and 1, controlling the percentage chance a given transaction will be sent to Sentry.
`traces_sample_rate_cli`	The value of `traces_sample_rate`	If tracing is enabled, set the sample rate for CLI. A number between 0 and 1, controlling the percentage chance a given transaction will be sent to Sentry.
`profiles_sample_rate`	`0` (disabled)	if this option is larger than 0 (zero), the module will create a profile of the request. Please note that you have to install Excimer on your server to use profiling. Sentry documentation. You have to enable tracing too.
`performance_tracking_enabled`	`false`	if performance tracking is enabled, a performance report gets generated for the request.
`performance_tracking_excluded_areas`	`['adminhtml', 'crontab']`	if `performance_tracking_enabled` is enabled, we recommend to exclude the `adminhtml` & `crontab` area.
`enable_logs`	`false`	This option enables the logging integration, which allows the SDK to capture logs and send them to Sentry.
`logger_log_level`	`\Monolog\Level::Notice`	If the logging integration is enabled, specify from which logging level the logger should log
`js_sdk_version`	`\JustBetter\Sentry\Block\SentryScript::CURRENT_VERSION`	If set, loads the explicit version of the JavaScript SDK of Sentry.
`ignore_js_errors`	`[]`	Array of JavaScript error messages which should not be sent to Sentry. (See also `ignoreErrors` in Sentry documentation)
`disable_default_integrations`	`[]`	Provide a list of FQCN of default integrations you do not want to use. List of default integrations.
`cron_monitoring_enabled`	`false`	Wether to enable cron check ins
`track_crons`	`[]`	Cron handles of crons to track with cron monitoring, Sentry only supports 6 check-ins per minute Magento does many more.
`spotlight`	`false`	Enable Spotlight on the page
`spotlight_url`	-	Override the Sidecar url
`enable_csp_report_url`	`false`	If set to true, the report-uri will be automatically added based on the DSN.
`async_sending_enabled`	`false`	Send Sentry events asynchronously via Magento Message Queue (`justbetter.sentry.event.send`).
`circuit_breaker_failure_threshold`	`5`	Consecutive HTTP failures before the circuit opens.
`circuit_breaker_recovery_timeout`	`60`	Seconds to wait before allowing a probe request after the circuit opens.
`circuit_breaker_success_threshold`	`2`	Successful probes in half-open state required before closing the circuit.
`http_timeout`	`2`	Total HTTP timeout (seconds) for Sentry envelope delivery (sync + consumer).
`http_connect_timeout`	`1`	HTTP connect timeout (seconds) for Sentry envelope delivery.

Resilient delivery

Event delivery can be configured as either synchronous or asynchronous:

(Default) Sync mode (async_sending_enabled = false): Events are sent over HTTP immediately.
Async mode (async_sending_enabled = true): Events are serialized immediately with exact capture timestamps and published to the justbetter.sentry.event.send message queue. A background consumer delivers them to Sentry via HTTP.

Both modes share two safeguards, kept in the Magento cache so every process sees them:

Circuit breaker (Sentry is unreachable): when consecutive failures (5xx, network errors) reach circuit_breaker_failure_threshold, the circuit opens. All events are dropped without blocking Magento until circuit_breaker_recovery_timeout has passed.
Rate limits (Sentry refuses a data category, e.g. quota exhausted): Sentry's X-Sentry-Rate-Limits header is tracked per category (errors, transactions, cron check-ins, logs), until the time Sentry sends. A limit on one category does not block the others, so cron check-ins keep arriving when the transaction quota runs out. A Retry-After header without categories, or a bare HTTP 429, limits all categories; the bare 429 lasts circuit_breaker_recovery_timeout.
While either applies, async mode does not publish the affected events, and the consumer drops queued ones without calling Sentry.

The consumer never retries a failed envelope. Failures are written to var/log/sentry.log and are never sent to Sentry themselves. Rate-limit responses are not logged: they are expected while the quota is exhausted, and delivery already backs off.

To run the queue consumer manually:

bin/magento queue:consumers:start justbetter.sentry.event

Javascript issue grouping

These settings live in the Magento configuration under Stores > Configuration > JustBetter > Sentry > Sentry issue grouping (sentry/issue_grouping/*).

Name	Default	Description
`strip_static_content_version`	`false`	Strip `version1234567890/` from stacktrace filenames so a static content deploy does not create new issues.
`strip_store_code`	`false`	Strip the store code from stacktrace filenames. Replaces the first occurrence only.
`add_action_context`	`false`	Send the Magento controller action of the current page (for example `catalog_product_view`, the same value Magento adds to the body tag) to the browser. Every Javascript event gets the `magento.route`, `magento.controller`, `magento.action` and `magento.full_action` tags, `event.transaction` is set to the full action name, and the pageload transaction is named after the action instead of the URL path.

Errors thrown from inline scripts (x-magento-init, inline require([...]), inline event handlers) are reported by the browser with the page URL as their filename, so Sentry creates a separate issue for every product, category and CMS URL. Group these with Sentry's own project settings: a Stack Trace Rule like family:javascript stack.abs_path:"*.html" -group removes document-URL frames from grouping entirely, and Fingerprint Rules can use {{ transaction }}, which is the full action name once add_action_context is enabled, to group them per page type.

Adding your own Javascript context

add_action_context dispatches the sentry_javascript_context event with a Magento\Framework\DataObject before it is rendered, so you can add tags or change the transaction name:

public function execute(\Magento\Framework\Event\Observer $observer)
{
    $context = $observer->getEvent()->getContext();
    $context->setData('tags', array_merge($context->getData('tags'), ['magento.theme' => 'hyva']));
}

The result is rendered inline into the (possibly full-page-cached) HTML and is readable as window.sentryMagentoContext, so anything you add must be derivable from the URL alone and must never contain customer data.

Configuration for Adobe Cloud

Since Adobe Cloud doesn't allow you to add manually add content to the env.php file, the configuration can be done using the "Variables" in Adobe Commerce using the following variables:

Name	Type
`CONFIG__SENTRY__ENVIRONMENT__ENABLED`	boolean
`CONFIG__SENTRY__ENVIRONMENT__DSN`	string
`CONFIG__SENTRY__ENVIRONMENT__MAGE_MODE_DEVELOPMENT`	string
`CONFIG__SENTRY__ENVIRONMENT__ENVIRONMENT`	string
`CONFIG__SENTRY__ENVIRONMENT__MAX_BREADCRUMBS`	integer
`CONFIG__SENTRY__ENVIRONMENT__ATTACH_STACKTRACE`	boolean
`CONFIG__SENTRY__ENVIRONMENT__SAMPLE_RATE`	float
`CONFIG__SENTRY__ENVIRONMENT__IGNORE_EXCEPTIONS`	JSON array of classes
`CONFIG__SENTRY__ENVIRONMENT__ERROR_TYPES`	integer
`CONFIG__SENTRY__ENVIRONMENT__LOG_LEVEL`	integer
`CONFIG__SENTRY__ENVIRONMENT__EXCEPTION_LOG_LEVELS`	JSON object of classes and log levels
`CONFIG__SENTRY__ENVIRONMENT__GRAPHQL_REPORT_CLIENT_SAFE_ERRORS`	boolean
`CONFIG__SENTRY__ENVIRONMENT__CLEAN_STACKTRACE`	boolean
`CONFIG__SENTRY__ENVIRONMENT__TRACING_ENABLED`	boolean
`CONFIG__SENTRY__ENVIRONMENT__TRACES_SAMPLE_RATE`	float
`CONFIG__SENTRY__ENVIRONMENT__PROFILES_SAMPLE_RATE`	float
`CONFIG__SENTRY__ENVIRONMENT__PERFORMANCE_TRACKING_ENABLED`	boolean
`CONFIG__SENTRY__ENVIRONMENT__PERFORMANCE_TRACKING_EXCLUDED_AREAS`	boolean
`CONFIG__SENTRY__ENVIRONMENT__ENABLE_LOGS`	boolean
`CONFIG__SENTRY__ENVIRONMENT__LOGGER_LOG_LEVEL`	boolean
`CONFIG__SENTRY__ENVIRONMENT__JS_SDK_VERSION`	string
`CONFIG__SENTRY__ENVIRONMENT__IGNORE_JS_ERRORS`	JSON array of error messages

The following configuration settings can be overridden in the Magento admin. This is limited to ensure that changes to particular config settings can only be done on server level and can't be broken by changes in the admin.

Please note, that it is not possible to use profiling within the Adobe Cloud.

GraphQL errors

Magento logs every GraphQL error with level ERROR (400). With log_level set to CRITICAL (500) these never reach Sentry, which hides bugs in GraphQL based checkouts (like Rapidez). Use exception_log_levels to send GraphQL errors from ERROR while keeping everything else on CRITICAL:

'sentry' => [
    'log_level' => \Monolog\Level::Critical->value,
    'exception_log_levels' => [
        \GraphQL\Error\Error::class => \Monolog\Level::Error->value,
    ],
],

Expected client errors, like a customer query without a token or an invalid coupon code, are marked client safe by GraphQL and keep using log_level, so they stay out of Sentry. Set graphql_report_client_safe_errors to true to send those as well.

Optional error page configuration

Optional you can configure custom error pages in pub/errors. You can use the sentry feedback form and insert here the sentry log ID. The Sentry Log Id is captured in de customer session and can be retrieved in processor.php.

Sending additional data to Sentry when logging errors

When calling any function from the Psr\Log\LoggerInterface you can pass any data to the parameter $context and it will be send to Sentry as 'Custom context'.

Change / Filter events

This module has an event called sentry_before_send that is dispatched before setting the config before_send. This provides the means to edit / filter events. You could for example add extra criteria to determine if the exception should be captured to Sentry. To prevent the Exception from being captured you can set the event to null or unset it completly.

public function execute(\Magento\Framework\Event\Observer $observer)
{
    $observer->getEvent()->getSentryEvent()->unsEvent();
}

Example: https://github.com/justbetter/magento2-sentry-filter-events

This same thing is the case for


sentry_before_send	https://docs.sentry.io/platforms/php/configuration/options/#before_send
sentry_before_send_transaction	https://docs.sentry.io/platforms/php/configuration/options/#before_send_transaction
sentry_before_send_check_in	https://docs.sentry.io/platforms/php/configuration/options/#before_send_check_in
sentry_before_breadcrumb	https://docs.sentry.io/platforms/php/configuration/options/#before_breadcrumb
sentry_before_send_log	https://docs.sentry.io/platforms/php/configuration/options/#before_send_log

The sentry_javascript_context event is dispatched server-side when sentry/issue_grouping/add_action_context is enabled, before the request context is rendered into the page for the browser SDK. See Adding your own Javascript context above.

Compatibility

The module is tested on Magento version 2.4.x with sentry sdk version 4.x. feel free to fork this project or make a pull request.

Ideas, bugs or suggestions?

Please create a issue or a pull request.

Contributing

Contributing? Awesome! Thank you for your help improving the module!

Please see CONTRIBUTING for details.

Most importantly:

When making a PR please add a description what you've added, and if relevant why.
To save time on codestyle feedback, please run
- composer install
- composer run codestyle
- composer run analyse

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

License

The MIT License (MIT). Please see License File for more information.

We’re a innovative development agency from The Netherlands.

justbetter / magento2-sentry

Package info

Security

Statistics