From 6cdf409858e7f440336777b21d88391cd85ae82c Mon Sep 17 00:00:00 2001 From: Martin Linzmayer Date: Thu, 11 Sep 2025 16:28:26 +0200 Subject: [PATCH 1/2] Update available options and add symfony specific section about integrations --- .../symfony/configuration/symfony-options.mdx | 1 + .../php/guides/symfony/integrations/index.mdx | 104 ++++++++++++++++++ 2 files changed, 105 insertions(+) create mode 100644 docs/platforms/php/guides/symfony/integrations/index.mdx diff --git a/docs/platforms/php/guides/symfony/configuration/symfony-options.mdx b/docs/platforms/php/guides/symfony/configuration/symfony-options.mdx index 0ee0bb78e1292..36049661a45d2 100644 --- a/docs/platforms/php/guides/symfony/configuration/symfony-options.mdx +++ b/docs/platforms/php/guides/symfony/configuration/symfony-options.mdx @@ -70,6 +70,7 @@ sentry: messenger: enabled: true capture_soft_fails: false + isolate_breadcrumbs_by_message: false tracing: enabled: true diff --git a/docs/platforms/php/guides/symfony/integrations/index.mdx b/docs/platforms/php/guides/symfony/integrations/index.mdx new file mode 100644 index 0000000000000..0895d6d240c4b --- /dev/null +++ b/docs/platforms/php/guides/symfony/integrations/index.mdx @@ -0,0 +1,104 @@ +--- +title: Integrations +description: "Learn about the automatic integrations Sentry provides and how to configure them." +sidebar_order: 500 +--- + +## Default Integrations + +These integrations are enabled by default and integrate into the +standard library or the interpreter itself. They are documented so you can be both aware of what they do and disable them if they cause issues. + +To disable system integrations in Symfony, set `options.default_integrations: false` in your bundle configuration: + +```yaml {filename:config/packages/sentry.yaml} +sentry: + options: + default_integrations: false +``` + +### ExceptionListenerIntegration + +This integration catches all global uncaught exceptions and emits events when an error occurs. + +To do so, it ensures that Sentry's `ErrorHandler` is registered, and adds a callback to it as an exception listener. + +### ErrorListenerIntegration + +This integration hooks into the global PHP `error_handler` and emits events when an error occurs. + +To do so, it ensures that Sentry's `ErrorHandler` is registered, and adds a callback to it as an error listener. By default, the `ErrorHandler` reserves 16 KiB of memory to handle fatal errors. When handling out of memory errors, the `ErrorHandler` additionally increases the [`memory_limit`](https://www.php.net/manual/en/ini.core.php#ini.memory-limit) by an additional 5 MiB to have enough room to send the out of memory event to Sentry. This change is only done once and only affects the handling of the out of memory error. + +To change the amount of memory reserved for fatal error handling or the amount the `memory_limit` is increased when handling an out of memory error, you can register the fatal error handler yourself before calling `\Sentry\init(...)`: + +```php +// The amount of reserved memory every request (in bytes), this has to be a positive integer amount of bytes. Defaults to 16 KiB +$errorHandler = \Sentry\ErrorHandler::registerOnceFatalErrorHandler(16 * 1024); +// The amount of memory in bytes to increase the `memory_limit` to when handling a out of memory error, can also be set to `null` to disable increasing the `memory_limit`. Defaults to 5 MiB +$errorHandler->setMemoryLimitIncreaseOnOutOfMemoryErrorInBytes(5 * 1024 * 1024); +``` + +For some frameworks or projects, specific integrations are provided both officially and by third-party users that automatically register the error handlers. Please refer to their documentation. + +By default, the error*types option defaults to the value returned by the `error_reporting()` function, which can change at runtime. Alternately, you can set the option to a fixed value by setting its value to a bitmask of the PHP `E*\*`constants in`\Sentry\init()`. In this case, Sentry will log only errors of those specific types regardless of the current reporting level. + +### FatalErrorListenerIntegration + +This integration catches all fatal errors and emits the corresponding events. + +To do so, it ensures that Sentry's `ErrorHandler` is registered, and adds a callback to it as a fatal error listener. + +### RequestIntegration + +This integration adds to the event request data: + +- HTTP method +- URL (including the query string) +- Body (by default only if the body is 10Kb or less) + +If the send_default_pii option is enabled, it will also send the following PII: + +- IP address +- Cookies +- Headers + +### TransactionIntegration + +This integration sets the `transaction` attribute of the event to the value found in the raw event payload or to the value of the `PATH_INFO` server var if present. + +### FrameContextifierIntegration + +This integration reads excerpts of code around the line that originated an error. + +### EnvironmentIntegration + +This integration fills the event data with PHP runtime and server OS information. + +### ModulesIntegration + +This integration logs all the versions of the packages installed with Composer with the event details; the root project is also included. + +## Custom Integrations + +You can customize the list of integrations without disabling the defaults by using the `options.integrations` setting in Symfony. Provide service IDs for classes implementing `\Sentry\Integration\IntegrationInterface`. + +```yaml {filename:config/packages/sentry.yaml} +sentry: + options: + integrations: + - "sentry.integration.my_custom_integration" +``` + +Register your integration as a service: + +```yaml {filename:config/services.yaml} +services: + sentry.integration.my_custom_integration: + class: App\Sentry\Integration\MyCustomIntegration +``` + +If you want to remove one or more default integrations, set `options.default_integrations: false` and then explicitly list the integrations you want to enable via `options.integrations`. + +### Use a Callback to Customize Integrations + +For advanced cases, you can provide a callback (service) instead of a fixed list to customize integrations. See how to reference callables in Symfony configuration here: Callables in Symfony Options. From 44aff4ec86bb018e595a118550e6be875b37508b Mon Sep 17 00:00:00 2001 From: Martin Linzmayer Date: Thu, 18 Sep 2025 13:33:04 +0200 Subject: [PATCH 2/2] feedback --- .../php/guides/symfony/integrations/index.mdx | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/platforms/php/guides/symfony/integrations/index.mdx b/docs/platforms/php/guides/symfony/integrations/index.mdx index 0895d6d240c4b..593837d2767a9 100644 --- a/docs/platforms/php/guides/symfony/integrations/index.mdx +++ b/docs/platforms/php/guides/symfony/integrations/index.mdx @@ -21,20 +21,20 @@ sentry: This integration catches all global uncaught exceptions and emits events when an error occurs. -To do so, it ensures that Sentry's `ErrorHandler` is registered, and adds a callback to it as an exception listener. +It does this by ensuring that Sentry's `ErrorHandler` is registered, and adds a callback to it as an exception listener. ### ErrorListenerIntegration This integration hooks into the global PHP `error_handler` and emits events when an error occurs. -To do so, it ensures that Sentry's `ErrorHandler` is registered, and adds a callback to it as an error listener. By default, the `ErrorHandler` reserves 16 KiB of memory to handle fatal errors. When handling out of memory errors, the `ErrorHandler` additionally increases the [`memory_limit`](https://www.php.net/manual/en/ini.core.php#ini.memory-limit) by an additional 5 MiB to have enough room to send the out of memory event to Sentry. This change is only done once and only affects the handling of the out of memory error. +It does this by ensuring that Sentry's `ErrorHandler` is registered, and adds a callback to it as an error listener. By default, the `ErrorHandler` reserves 16 KiB of memory to handle fatal errors. When handling out of memory errors, the `ErrorHandler` additionally increases the [`memory_limit`](https://www.php.net/manual/en/ini.core.php#ini.memory-limit) by an additional 5 MiB to have enough room to send the out of memory event to Sentry. This change is only done once and only affects the handling of the out of memory error. To change the amount of memory reserved for fatal error handling or the amount the `memory_limit` is increased when handling an out of memory error, you can register the fatal error handler yourself before calling `\Sentry\init(...)`: ```php -// The amount of reserved memory every request (in bytes), this has to be a positive integer amount of bytes. Defaults to 16 KiB +// The amount of reserved memory for every request (in bytes), this has to be a positive integer in bytes. Defaults to 16 KiB $errorHandler = \Sentry\ErrorHandler::registerOnceFatalErrorHandler(16 * 1024); -// The amount of memory in bytes to increase the `memory_limit` to when handling a out of memory error, can also be set to `null` to disable increasing the `memory_limit`. Defaults to 5 MiB +// The amount of memory in bytes to increase the `memory_limit` to when handling an out of memory error. It can also be set to `null` to disable increasing the `memory_limit`. Defaults to 5 MiB $errorHandler->setMemoryLimitIncreaseOnOutOfMemoryErrorInBytes(5 * 1024 * 1024); ``` @@ -46,7 +46,7 @@ By default, the error*types option defaults to the value returned by the `error_ This integration catches all fatal errors and emits the corresponding events. -To do so, it ensures that Sentry's `ErrorHandler` is registered, and adds a callback to it as a fatal error listener. +It does this by ensuring that Sentry's `ErrorHandler` is registered, and adds a callback to it as a fatal error listener. ### RequestIntegration @@ -54,7 +54,7 @@ This integration adds to the event request data: - HTTP method - URL (including the query string) -- Body (by default only if the body is 10Kb or less) +- Body (only if the body is 10Kb or less) If the send_default_pii option is enabled, it will also send the following PII: @@ -101,4 +101,4 @@ If you want to remove one or more default integrations, set `options.default_int ### Use a Callback to Customize Integrations -For advanced cases, you can provide a callback (service) instead of a fixed list to customize integrations. See how to reference callables in Symfony configuration here: Callables in Symfony Options. +For advanced cases, you can provide a callback (service) instead of a fixed list to customize integrations. See how to reference callables in Symfony configuration here: [Callables in Symfony Options](/platforms/php/guides/symfony/configuration/symfony-options/#callables).