From e6abca113552918c0cc3a155d21e2d1e1c99e32c Mon Sep 17 00:00:00 2001 From: Martin Linzmayer Date: Mon, 5 Oct 2026 13:37:40 +0200 Subject: [PATCH 1/5] feat(pii): data collection for PHP --- .../php/common/configuration/options.mdx | 44 +++ .../common/data-management/data-collected.mdx | 8 + .../data-management/data-collection.mdx | 254 ++++++++++++++++++ .../data-management/sensitive-data/index.mdx | 6 + 4 files changed, 312 insertions(+) create mode 100644 docs/platforms/php/common/data-management/data-collection.mdx diff --git a/docs/platforms/php/common/configuration/options.mdx b/docs/platforms/php/common/configuration/options.mdx index 4371b073c6b05..ef47eff5e6de8 100644 --- a/docs/platforms/php/common/configuration/options.mdx +++ b/docs/platforms/php/common/configuration/options.mdx @@ -69,8 +69,46 @@ This option is turned off by default. If you enable this option, be sure to manually remove what you don't want to send using our features for managing [_Sensitive Data_](../../data-management/sensitive-data/). + + + + +For more fine-grained control, use the [`data_collection`](#data_collection) option. `send_default_pii` remains fully supported until the next major version. + +If you set both, `send_default_pii` is ignored. + + + + + + + + + + + +Controls which categories of data the SDK collects automatically, replacing the single `send_default_pii` boolean with a per-category configuration. All keys are optional. + +```php +\Sentry\init([ + 'dsn' => '___PUBLIC_DSN___', + 'data_collection' => [ + 'user_info' => false, + 'http_bodies' => ['incomingRequest'], + ], +]); +``` + +Passing a `data_collection` array opts you into its defaults, which are more permissive than `send_default_pii` set to `false`. Any key you don't set falls back to its default, so the SDK collects rich debugging context (the user's IP address, cookies, and request and response bodies) and scrubs values whose keys match the built-in sensitive denylist (`auth`, `token`, `password`, and similar). + +If you set both `data_collection` and `send_default_pii`, `send_default_pii` is ignored. The `context_lines` option is ignored as well, in favor of `frame_context_lines`. + +For the full reference of available keys and their defaults, see Data Collection. + + + This option can be used to supply a server name. When provided, the name of the server is sent along and persisted in the event. For many integrations, the server name actually corresponds to the device hostname, even in situations where the machine is not actually a server. @@ -174,6 +212,12 @@ By default, the error types reported are determined by the value returned by the The number of context lines for each frame in the stack trace when loading a file. + + +This option is ignored when [`data_collection`](#data_collection) is set. Use its `frame_context_lines` key instead. + + + ## Tracing Options diff --git a/docs/platforms/php/common/data-management/data-collected.mdx b/docs/platforms/php/common/data-management/data-collected.mdx index 70d57a99fa85d..72aabaf911e9a 100644 --- a/docs/platforms/php/common/data-management/data-collected.mdx +++ b/docs/platforms/php/common/data-management/data-collected.mdx @@ -6,6 +6,14 @@ sidebar_order: 1 Sentry takes data privacy very seriously and has default settings in place that prioritize data safety, especially when it comes to personally identifiable information (PII) data. When you add the Sentry SDK to your application, you allow it to collect data and send it to Sentry during the runtime of your application. + + +For more fine-grained control, version 4.33.0 and later lets you opt in or out of each data category individually with the `data_collection` option. See Data Collection for details. + +This page describes the behavior controlled by the `send_default_pii` option, which remains fully supported until the next major version. + + + The category types and amount of data collected vary, depending on the integrations you've enabled in the Sentry SDK. Here's a list of data categories the Sentry PHP SDK collects: ## HTTP Headers diff --git a/docs/platforms/php/common/data-management/data-collection.mdx b/docs/platforms/php/common/data-management/data-collection.mdx new file mode 100644 index 0000000000000..80aec3cc1a4cd --- /dev/null +++ b/docs/platforms/php/common/data-management/data-collection.mdx @@ -0,0 +1,254 @@ +--- +title: Data Collection +description: "See what data the Sentry PHP SDK collects when you use the data_collection option, and how to control it." +sidebar_order: 2 +notSupported: + - php.laravel + - php.symfony +--- + +Sentry takes data privacy very seriously and has default settings in place that prioritize data safety, especially when it comes to personally identifiable information (PII) data. When you add the Sentry SDK to your application, you allow it to collect data and send it to Sentry during the runtime of your application. + +The category types and amount of data collected vary, depending on the integrations you've enabled in the Sentry SDK. This page lists data categories that the Sentry PHP SDK collects when you use the `data_collection` option. + + + +You can control the categories listed here with the `data_collection` option, which lets you opt in or out of each data category individually. The option is available in version 4.33.0 and later. + +The `send_default_pii` option remains fully supported until the next major version. Without `data_collection`, the SDK collects conservatively, and the defaults described on Data Collected apply. + +As soon as you pass a `data_collection` array, the categories you don't set explicitly fall back to the defaults described on this page, which are more permissive. For example, cookies, the user's IP address, and request and response bodies are then collected unless you opt out. Values whose keys match the built-in sensitive denylist are always scrubbed. + +If you set both, `send_default_pii` is ignored. The same applies to the `context_lines` option, which `data_collection` replaces with `frame_context_lines`. + +Regardless of these options, you can always scrub any data before it's sent to Sentry. See Scrubbing Sensitive Data for details. + + + +## HTTP Headers + +The SDK collects the headers of incoming requests, as well as the request and response headers of HTTP requests made with the `GuzzleTracingMiddleware`. Values of sensitive headers are scrubbed. Use `http_headers` to control this. A single behavior applies to both request and response headers: + +```php +\Sentry\init([ + 'dsn' => '___PUBLIC_DSN___', + 'data_collection' => [ + // Collect nothing: + 'http_headers' => ['mode' => 'off'], + // Or only send real values for the listed headers: + // 'http_headers' => ['mode' => 'allowList', 'terms' => ['content-type']], + // Or configure request and response headers separately: + // 'http_headers' => [ + // 'request' => ['mode' => 'denyList', 'terms' => ['-ip']], + // 'response' => ['mode' => 'off'], + // ], + ], +]); +``` + +Values whose keys match Sentry's built-in sensitive denylist (such as `auth`, `token`, or `password`) are always scrubbed, while the keys are kept. The `Cookie` and `Set-Cookie` headers are never included in the collected headers. Use the [`cookies`](#cookies) category to control them instead. See [Key-Value Collection Behavior](#key-value-collection-behavior) below for details on `mode` and `terms`. + +## Cookies + +The SDK collects the cookies of incoming requests, as well as the cookies sent and received by HTTP requests made with the `GuzzleTracingMiddleware`. Values of sensitive cookies are scrubbed. Opt out with `['mode' => 'off']`, or restrict which values are sent using `allowList` or `denyList` mode: + +```php +\Sentry\init([ + 'dsn' => '___PUBLIC_DSN___', + 'data_collection' => [ + 'cookies' => ['mode' => 'off'], + // Or only send the real value of the `locale` cookie: + // 'cookies' => ['mode' => 'allowList', 'terms' => ['locale']], + ], +]); +``` + +## Information About Logged-in User + +The SDK doesn't set the user's ID, email address, or username automatically. User data you set with `setUser()` is always sent to Sentry, regardless of `data_collection`. + +The `user_info` category controls the user data the SDK infers on its own, which is the user's IP address (see the next section). + +## Users' IP Address + +The SDK sends the IP address of incoming requests as the user's IP address by default. Disable it by setting `user_info` to `false`: + +```php +\Sentry\init([ + 'dsn' => '___PUBLIC_DSN___', + 'data_collection' => [ + 'user_info' => false, + ], +]); +``` + +Even when this is disabled, IP addresses can still reach Sentry through collected HTTP headers, cookies, or query parameters (for example, the `X-Forwarded-For` header). Add these terms to the deny lists for those categories so their values are filtered: + +```php +\Sentry\init([ + 'dsn' => '___PUBLIC_DSN___', + 'data_collection' => [ + 'user_info' => false, + 'http_headers' => [ + 'mode' => 'denyList', + 'terms' => ['forwarded', '-ip', 'remote-', 'via', '-user'], + ], + 'cookies' => [ + 'mode' => 'denyList', + 'terms' => ['forwarded', '-ip', 'remote-', 'via', '-user'], + ], + 'url_query_params' => [ + 'mode' => 'denyList', + 'terms' => ['forwarded', '-ip', 'remote-', 'via', '-user'], + ], + ], +]); +``` + +## Request URL + +The full URL of incoming requests and of HTTP requests made with the `GuzzleTracingMiddleware` is **always sent to Sentry**. Depending on your application, this could contain PII data. + +Credentials in the URL (for example, `https://user:password@example.com`) are replaced with `[Filtered]`, and the query string is filtered as described in [Request Query String](#request-query-string). + +## Request Query String + +By default, the query string of incoming requests and of HTTP requests made with the `GuzzleTracingMiddleware` is sent to Sentry. Depending on your application, this could contain PII data. For example, a query string like `?user_id=1234`, where `1234` is a user id (which may be considered PII). + +Use `url_query_params` to control this. Set it to `['mode' => 'off']` to disable collection entirely, or use `allowList` or `denyList` mode to filter which values are sent. Values whose keys match the built-in sensitive denylist (terms like `auth`, `token`, `password`, and `secret`) are scrubbed automatically. + +```php +\Sentry\init([ + 'dsn' => '___PUBLIC_DSN___', + 'data_collection' => [ + 'url_query_params' => ['mode' => 'off'], + ], +]); +``` + +Sentry also has some additional [server-side data scrubbing](/security-legal-pii/scrubbing/server-side-scrubbing/) in place to remove sensitive data from the query string. + +## Request and Response Bodies + +By default, the SDK collects the bodies of incoming requests, as well as the request and response bodies of HTTP requests made with the `GuzzleTracingMiddleware`. Whether a body is sent depends on its type and size: + +- **The type of the body:** + - JSON and form bodies are sent, with values whose keys match the built-in sensitive denylist scrubbed + - Bodies in other formats, or bodies that can't be parsed, are replaced with `[Filtered]` + - Uploaded files are never sent to Sentry +- **The size of the body:** The `max_request_body_size` option limits request bodies: `small` collects bodies up to 1,000 bytes, `medium` (the default) up to 10,000 bytes, and `always` up to 100,000 bytes. Response bodies are collected up to 100,000 bytes. Bodies that exceed the limit aren't sent. + +To disable body collection, set `http_bodies` to an empty array, or provide only the body types you want: + +```php +\Sentry\init([ + 'dsn' => '___PUBLIC_DSN___', + // Collect only incoming request bodies: + 'data_collection' => [ + 'http_bodies' => ['incomingRequest'], + ], +]); +``` + +The valid body types are: + +- `incomingRequest`: The body of the request your application handles. +- `outgoingRequest`: The body of a request sent with the `GuzzleTracingMiddleware`. +- `incomingResponse`: The body of a response received with the `GuzzleTracingMiddleware`. +- `outgoingResponse`: The body of the response your application sends. The PHP SDK doesn't capture these bodies. + +## Source Context + +When an unhandled exception is sent to Sentry, a snapshot of the source code surrounding the line where the error originates is sent with it. + +Use `frame_context_lines` to control how many lines above and below each stack frame are captured. It defaults to `5`. Set it to `0` to only send the line where the error occurred: + +```php +\Sentry\init([ + 'dsn' => '___PUBLIC_DSN___', + 'data_collection' => [ + 'frame_context_lines' => 0, + ], +]); +``` + +## Local Variables In Stack Trace + +When unhandled errors and exceptions are sent to Sentry, the names and values of local variables that were set when the errors occurred are sent at the same time. + +`stack_frame_variables` controls this and defaults to `true`. Values of variables whose names match the built-in sensitive denylist are scrubbed. Set it to `false` to stop sending variables, or use a key-value behavior to filter which variables are sent by name: + +```php +\Sentry\init([ + 'dsn' => '___PUBLIC_DSN___', + 'data_collection' => [ + 'stack_frame_variables' => false, + // Or filter additional variables by name: + // 'stack_frame_variables' => ['mode' => 'denyList', 'terms' => ['email']], + ], +]); +``` + +Setting `zend.exception_ignore_args=1` in your `php.ini` prevents PHP from providing variables to the SDK, regardless of `stack_frame_variables`. On some distributions, this setting is already set to `1` by default. + +## `data_collection` Reference + +### Keys + +| Key | Type | Default | Description | +| ----------------------- | ---------------------------------------------------------- | -------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `user_info` | `bool` | `true` | Send the IP address of incoming requests as the user's IP address. | +| `cookies` | key-value behavior | `['mode' => 'denyList']` | Collect cookies. | +| `http_headers` | key-value behavior, or `['request' => …, 'response' => …]` | `['mode' => 'denyList']` | Collect HTTP headers. A single behavior applies to both request and response headers. | +| `http_bodies` | `string[]` | `['incomingRequest', 'outgoingRequest', 'incomingResponse', 'outgoingResponse']` | Body types to collect. Set to `[]` to disable. | +| `url_query_params` | key-value behavior | `['mode' => 'denyList']` | Collect URL query parameters. | +| `stack_frame_variables` | `bool` or key-value behavior | `true` | Include variable values captured within stack frames. Accepts a boolean (`true` collects all variables, `false` collects none) or a key-value behavior to filter which variables are sent by name. | +| `frame_context_lines` | `int` | `5` | Source code lines captured above and below each stack frame. | + +`data_collection` also accepts the `gen_ai`, `database_query_data`, and `queues` keys, but the PHP SDK doesn't collect any of this data. + +Invalid values are ignored and the default is used instead. The SDK logs a debug message through the configured `logger` when this happens. + +### Key-Value Collection Behavior + +The `cookies`, `http_headers`, `url_query_params`, and `stack_frame_variables` categories take an array with a `mode` and an optional list of `terms`: + +```php +['mode' => 'denyList', 'terms' => ['forwarded', '-ip', 'remote-', 'via', '-user']] +``` + +| `mode` | Behavior | +| ------------- | --------------------------------------------------------------------------------------------------------------------- | +| `'denyList'` | Collect everything, replacing the value of any key matching `terms` (in addition to the built-in sensitive denylist). | +| `'allowList'` | Only keys matching `terms` send their real value. Every other key is kept, but its value is replaced. | +| `'off'` | Collect nothing in this category. | + +If you omit `mode`, it defaults to `'denyList'`. `terms` match partially and case-insensitively, so `'-ip'` matches `X-Real-IP`. Filtered values are replaced with `[Filtered]`; the key itself is always preserved. The built-in sensitive denylist (`auth`, `token`, `secret`, `password`, `key`, `session`, and similar) always applies, even in `'allowList'` mode. + +### Preserving `send_default_pii` Behavior + +To keep roughly the conservative collection you get with `send_default_pii` set to `false` while using `data_collection`, opt out of each category explicitly: + +```php +\Sentry\init([ + 'dsn' => '___PUBLIC_DSN___', + 'data_collection' => [ + 'user_info' => false, + 'cookies' => ['mode' => 'off'], + 'http_headers' => [ + 'request' => [ + 'mode' => 'denyList', + 'terms' => ['forwarded', '-ip', 'remote-', 'via', '-user'], + ], + 'response' => ['mode' => 'off'], + ], + 'url_query_params' => [ + 'mode' => 'denyList', + 'terms' => ['forwarded', '-ip', 'remote-', 'via', '-user'], + ], + 'http_bodies' => ['incomingRequest'], + ], +]); +``` + +If you previously set `send_default_pii` to `true`, pass an empty `data_collection` array to use the defaults described on this page. diff --git a/docs/platforms/php/common/data-management/sensitive-data/index.mdx b/docs/platforms/php/common/data-management/sensitive-data/index.mdx index 297f3b27982e9..6484d777060de 100644 --- a/docs/platforms/php/common/data-management/sensitive-data/index.mdx +++ b/docs/platforms/php/common/data-management/sensitive-data/index.mdx @@ -35,6 +35,12 @@ The SDK purposefully does not send PII to stay on the safe side. This behavior i Turning this option on is required for certain features in Sentry to work, but also means you will need to be even more careful about what data is being sent to Sentry (using the options below). + + +For more fine-grained control, use the [`data_collection`](../../configuration/options/#data_collection) option to collect or ignore specific categories of data. `send_default_pii` remains fully supported until the next major version. See Data Collection for details. + + + If you _do not_ wish to use the default PII behavior, you can also choose to identify users in a more controlled manner, using our [user identity context](../../enriching-events/identify-user/). ## Scrubbing Data From 607ea36a1147af4d7f910715a9630ce6092613e2 Mon Sep 17 00:00:00 2001 From: Martin Linzmayer Date: Mon, 5 Oct 2026 14:00:04 +0200 Subject: [PATCH 2/5] wip --- .../data-management/data-collection.mdx | 33 +++++++------------ 1 file changed, 11 insertions(+), 22 deletions(-) diff --git a/docs/platforms/php/common/data-management/data-collection.mdx b/docs/platforms/php/common/data-management/data-collection.mdx index 80aec3cc1a4cd..984e578f2c3cf 100644 --- a/docs/platforms/php/common/data-management/data-collection.mdx +++ b/docs/platforms/php/common/data-management/data-collection.mdx @@ -27,7 +27,7 @@ Regardless of these options, you can always scrub any data before it's sent to S ## HTTP Headers -The SDK collects the headers of incoming requests, as well as the request and response headers of HTTP requests made with the `GuzzleTracingMiddleware`. Values of sensitive headers are scrubbed. Use `http_headers` to control this. A single behavior applies to both request and response headers: +By default, the SDK collects HTTP request and response headers, with sensitive values scrubbed. Use `http_headers` to control this. A single behavior applies to both request and response headers: ```php \Sentry\init([ @@ -50,7 +50,7 @@ Values whose keys match Sentry's built-in sensitive denylist (such as `auth`, `t ## Cookies -The SDK collects the cookies of incoming requests, as well as the cookies sent and received by HTTP requests made with the `GuzzleTracingMiddleware`. Values of sensitive cookies are scrubbed. Opt out with `['mode' => 'off']`, or restrict which values are sent using `allowList` or `denyList` mode: +By default, the SDK collects cookies, with sensitive values scrubbed. Opt out with `['mode' => 'off']`, or restrict which values are sent using `allowList` or `denyList` mode: ```php \Sentry\init([ @@ -65,13 +65,11 @@ The SDK collects the cookies of incoming requests, as well as the cookies sent a ## Information About Logged-in User -The SDK doesn't set the user's ID, email address, or username automatically. User data you set with `setUser()` is always sent to Sentry, regardless of `data_collection`. - -The `user_info` category controls the user data the SDK infers on its own, which is the user's IP address (see the next section). +The `user_info` category controls the user data the SDK infers on its own, such as the user's IP address. User data you set with `setUser()` is always sent to Sentry, regardless of `data_collection`. ## Users' IP Address -The SDK sends the IP address of incoming requests as the user's IP address by default. Disable it by setting `user_info` to `false`: +By default, the SDK sends the user's IP address. Disable it by setting `user_info` to `false`: ```php \Sentry\init([ @@ -107,15 +105,13 @@ Even when this is disabled, IP addresses can still reach Sentry through collecte ## Request URL -The full URL of incoming requests and of HTTP requests made with the `GuzzleTracingMiddleware` is **always sent to Sentry**. Depending on your application, this could contain PII data. - -Credentials in the URL (for example, `https://user:password@example.com`) are replaced with `[Filtered]`, and the query string is filtered as described in [Request Query String](#request-query-string). +The full URL of incoming and outgoing HTTP requests is sent to Sentry. Depending on your application, this could contain PII data. Credentials in the URL (for example, `https://user:password@example.com`) are replaced with `[Filtered]`, and query parameters are filtered as described in [Request Query String](#request-query-string). ## Request Query String -By default, the query string of incoming requests and of HTTP requests made with the `GuzzleTracingMiddleware` is sent to Sentry. Depending on your application, this could contain PII data. For example, a query string like `?user_id=1234`, where `1234` is a user id (which may be considered PII). +By default, the SDK sends the query string of incoming and outgoing HTTP requests. Depending on your application, this could contain PII data. Values whose keys match the built-in sensitive denylist (such as `auth`, `token`, `password`, and `secret`) are replaced with `[Filtered]`. -Use `url_query_params` to control this. Set it to `['mode' => 'off']` to disable collection entirely, or use `allowList` or `denyList` mode to filter which values are sent. Values whose keys match the built-in sensitive denylist (terms like `auth`, `token`, `password`, and `secret`) are scrubbed automatically. +Use `url_query_params` to control this. Set it to `['mode' => 'off']` to disable collection entirely, or use `allowList` or `denyList` mode to filter which values are sent: ```php \Sentry\init([ @@ -130,13 +126,13 @@ Sentry also has some additional [server-side data scrubbing](/security-legal-pii ## Request and Response Bodies -By default, the SDK collects the bodies of incoming requests, as well as the request and response bodies of HTTP requests made with the `GuzzleTracingMiddleware`. Whether a body is sent depends on its type and size: +By default, the SDK collects HTTP request and response bodies. Whether a body is sent depends on its type and size: - **The type of the body:** - JSON and form bodies are sent, with values whose keys match the built-in sensitive denylist scrubbed - Bodies in other formats, or bodies that can't be parsed, are replaced with `[Filtered]` - Uploaded files are never sent to Sentry -- **The size of the body:** The `max_request_body_size` option limits request bodies: `small` collects bodies up to 1,000 bytes, `medium` (the default) up to 10,000 bytes, and `always` up to 100,000 bytes. Response bodies are collected up to 100,000 bytes. Bodies that exceed the limit aren't sent. +- **The size of the body:** There's a `max_request_body_size` option that's set to `medium` by default. Bodies that exceed the size limit aren't sent to Sentry. To disable body collection, set `http_bodies` to an empty array, or provide only the body types you want: @@ -150,12 +146,7 @@ To disable body collection, set `http_bodies` to an empty array, or provide only ]); ``` -The valid body types are: - -- `incomingRequest`: The body of the request your application handles. -- `outgoingRequest`: The body of a request sent with the `GuzzleTracingMiddleware`. -- `incomingResponse`: The body of a response received with the `GuzzleTracingMiddleware`. -- `outgoingResponse`: The body of the response your application sends. The PHP SDK doesn't capture these bodies. +The valid body types are `incomingRequest`, `outgoingRequest`, `incomingResponse`, and `outgoingResponse`. ## Source Context @@ -197,7 +188,7 @@ Setting `zend.exception_ignore_args=1` in your `php.ini` prevents PHP from provi | Key | Type | Default | Description | | ----------------------- | ---------------------------------------------------------- | -------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `user_info` | `bool` | `true` | Send the IP address of incoming requests as the user's IP address. | +| `user_info` | `bool` | `true` | Populate user fields, such as the IP address, from instrumentation. | | `cookies` | key-value behavior | `['mode' => 'denyList']` | Collect cookies. | | `http_headers` | key-value behavior, or `['request' => …, 'response' => …]` | `['mode' => 'denyList']` | Collect HTTP headers. A single behavior applies to both request and response headers. | | `http_bodies` | `string[]` | `['incomingRequest', 'outgoingRequest', 'incomingResponse', 'outgoingResponse']` | Body types to collect. Set to `[]` to disable. | @@ -205,8 +196,6 @@ Setting `zend.exception_ignore_args=1` in your `php.ini` prevents PHP from provi | `stack_frame_variables` | `bool` or key-value behavior | `true` | Include variable values captured within stack frames. Accepts a boolean (`true` collects all variables, `false` collects none) or a key-value behavior to filter which variables are sent by name. | | `frame_context_lines` | `int` | `5` | Source code lines captured above and below each stack frame. | -`data_collection` also accepts the `gen_ai`, `database_query_data`, and `queues` keys, but the PHP SDK doesn't collect any of this data. - Invalid values are ignored and the default is used instead. The SDK logs a debug message through the configured `logger` when this happens. ### Key-Value Collection Behavior From be47c2af70b2453949da5ba6b76b3beff19a2190 Mon Sep 17 00:00:00 2001 From: Martin Linzmayer Date: Thu, 8 Oct 2026 15:32:56 +0200 Subject: [PATCH 3/5] framework docs --- .../php/common/configuration/options.mdx | 56 +++- .../data-management/data-collection.mdx | 3 - .../data-management/sensitive-data/index.mdx | 4 - .../data-management/data-collected.mdx | 8 + .../data-management/data-collection.mdx | 289 +++++++++++++++++ .../data-management/data-collected.mdx | 8 + .../data-management/data-collection.mdx | 290 ++++++++++++++++++ 7 files changed, 643 insertions(+), 15 deletions(-) create mode 100644 docs/platforms/php/guides/laravel/data-management/data-collection.mdx create mode 100644 docs/platforms/php/guides/symfony/data-management/data-collection.mdx diff --git a/docs/platforms/php/common/configuration/options.mdx b/docs/platforms/php/common/configuration/options.mdx index ef47eff5e6de8..8e86d81a2f30f 100644 --- a/docs/platforms/php/common/configuration/options.mdx +++ b/docs/platforms/php/common/configuration/options.mdx @@ -69,8 +69,6 @@ This option is turned off by default. If you enable this option, be sure to manually remove what you don't want to send using our features for managing [_Sensitive Data_](../../data-management/sensitive-data/). - - For more fine-grained control, use the [`data_collection`](#data_collection) option. `send_default_pii` remains fully supported until the next major version. @@ -79,8 +77,6 @@ If you set both, `send_default_pii` is ignored. - - @@ -109,6 +105,54 @@ For the full reference of available keys and their defaults, see + + + + +Controls which categories of data the SDK collects automatically, replacing the single `send_default_pii` boolean with a per-category configuration. All keys are optional. + +{/* prettier-ignore */} +```yaml {filename:config/packages/sentry.yaml} +sentry: + options: + data_collection: + user_info: false + http_bodies: ['incomingRequest'] +``` + +Setting `data_collection` opts you into its defaults, which are more permissive than `send_default_pii` set to `false`. Any key you don't set falls back to its default, so the SDK collects rich debugging context (the logged-in user, cookies, request and response bodies, and database query parameters) and scrubs values whose keys match the built-in sensitive denylist (`auth`, `token`, `password`, and similar). Set it to `{}` to apply the defaults of every key. + +If you set both `data_collection` and `send_default_pii`, `send_default_pii` is ignored. The `context_lines` option is ignored as well, in favor of `frame_context_lines`. + +For the full reference of available keys and their defaults, see Data Collection. + + + + + + + + + +Controls which categories of data the SDK collects automatically, replacing the single `send_default_pii` boolean with a per-category configuration. All keys are optional. + +```php {filename:config/sentry.php} +'data_collection' => [ + 'user_info' => false, + 'http_bodies' => ['incomingRequest'], +], +``` + +Passing a `data_collection` array opts you into its defaults, which are more permissive than `send_default_pii` set to `false`. Any key you don't set falls back to its default, so the SDK collects rich debugging context (the logged-in user, cookies, request and response bodies, SQL query bindings, and AI prompts and responses) and scrubs values whose keys match the built-in sensitive denylist (`auth`, `token`, `password`, and similar). Pass an empty array to apply the defaults of every key. + +If you set both `data_collection` and `send_default_pii`, `send_default_pii` is ignored. The `context_lines`, `breadcrumbs.sql_bindings`, and `tracing.sql_bindings` options are ignored as well, in favor of `frame_context_lines` and `database_query_data`. + +For the full reference of available keys and their defaults, see Data Collection. + + + + + This option can be used to supply a server name. When provided, the name of the server is sent along and persisted in the event. For many integrations, the server name actually corresponds to the device hostname, even in situations where the machine is not actually a server. @@ -212,12 +256,8 @@ By default, the error types reported are determined by the value returned by the The number of context lines for each frame in the stack trace when loading a file. - - This option is ignored when [`data_collection`](#data_collection) is set. Use its `frame_context_lines` key instead. - - ## Tracing Options diff --git a/docs/platforms/php/common/data-management/data-collection.mdx b/docs/platforms/php/common/data-management/data-collection.mdx index 984e578f2c3cf..e6cb351072f3e 100644 --- a/docs/platforms/php/common/data-management/data-collection.mdx +++ b/docs/platforms/php/common/data-management/data-collection.mdx @@ -2,9 +2,6 @@ title: Data Collection description: "See what data the Sentry PHP SDK collects when you use the data_collection option, and how to control it." sidebar_order: 2 -notSupported: - - php.laravel - - php.symfony --- Sentry takes data privacy very seriously and has default settings in place that prioritize data safety, especially when it comes to personally identifiable information (PII) data. When you add the Sentry SDK to your application, you allow it to collect data and send it to Sentry during the runtime of your application. diff --git a/docs/platforms/php/common/data-management/sensitive-data/index.mdx b/docs/platforms/php/common/data-management/sensitive-data/index.mdx index 6484d777060de..484bc065f0b15 100644 --- a/docs/platforms/php/common/data-management/sensitive-data/index.mdx +++ b/docs/platforms/php/common/data-management/sensitive-data/index.mdx @@ -35,12 +35,8 @@ The SDK purposefully does not send PII to stay on the safe side. This behavior i Turning this option on is required for certain features in Sentry to work, but also means you will need to be even more careful about what data is being sent to Sentry (using the options below). - - For more fine-grained control, use the [`data_collection`](../../configuration/options/#data_collection) option to collect or ignore specific categories of data. `send_default_pii` remains fully supported until the next major version. See Data Collection for details. - - If you _do not_ wish to use the default PII behavior, you can also choose to identify users in a more controlled manner, using our [user identity context](../../enriching-events/identify-user/). ## Scrubbing Data diff --git a/docs/platforms/php/guides/laravel/data-management/data-collected.mdx b/docs/platforms/php/guides/laravel/data-management/data-collected.mdx index ddc4bdfab2e22..f381124b4f6b5 100644 --- a/docs/platforms/php/guides/laravel/data-management/data-collected.mdx +++ b/docs/platforms/php/guides/laravel/data-management/data-collected.mdx @@ -7,6 +7,14 @@ sidebar_section: configuration Sentry takes data privacy very seriously and has default settings in place that prioritize data safety, especially when it comes to personally identifiable information (PII) data. When you add the Sentry SDK to your application, you allow it to collect data and send it to Sentry during the runtime of your application. + + +For more fine-grained control, version 4.29.0 and later lets you opt in or out of each data category individually with the `data_collection` option. See Data Collection for details. + +This page describes the behavior controlled by the `send_default_pii` option, which remains fully supported until the next major version. + + + The category types and amount of data collected vary, depending on the integrations you've enabled in the Sentry SDK. Here's a list of data categories the Sentry PHP SDK collects: ## HTTP Headers diff --git a/docs/platforms/php/guides/laravel/data-management/data-collection.mdx b/docs/platforms/php/guides/laravel/data-management/data-collection.mdx new file mode 100644 index 0000000000000..341d7be9f3bec --- /dev/null +++ b/docs/platforms/php/guides/laravel/data-management/data-collection.mdx @@ -0,0 +1,289 @@ +--- +title: Data Collection +description: "See what data the Sentry Laravel SDK collects when you use the data_collection option, and how to control it." +sidebar_order: 3 +sidebar_section: configuration +--- + +Sentry takes data privacy very seriously and has default settings in place that prioritize data safety, especially when it comes to personally identifiable information (PII) data. When you add the Sentry SDK to your application, you allow it to collect data and send it to Sentry during the runtime of your application. + +The category types and amount of data collected vary, depending on the integrations you've enabled in the Sentry SDK. This page lists data categories that the Sentry Laravel SDK collects when you use the `data_collection` option. + + + +You can control the categories listed here with the `data_collection` option, which lets you opt in or out of each data category individually. The option is available in version 4.29.0 and later. + +Configure it with the `data_collection` key in `config/sentry.php`. The default value, `null`, keeps the legacy options. An empty array applies the defaults of every category: + +```php {filename:config/sentry.php} +'data_collection' => [], +``` + +The `send_default_pii` option remains fully supported until the next major version. Without `data_collection`, the SDK collects conservatively, and the defaults described on Data Collected apply. + +As soon as you pass a `data_collection` array, the categories you don't set explicitly fall back to the defaults described on this page, which are more permissive. For example, cookies, the logged-in user, request and response bodies, SQL query bindings, and AI prompts and responses are then collected unless you opt out. Values whose keys match the built-in sensitive denylist are always scrubbed. + +If you set both, `send_default_pii` is ignored. The same applies to the `context_lines` option, which `data_collection` replaces with `frame_context_lines`, and to the `breadcrumbs.sql_bindings` and `tracing.sql_bindings` options, which `data_collection` replaces with `database_query_data`. Run `php artisan about` to check whether `data_collection` is set. + +Regardless of these options, you can always scrub any data before it's sent to Sentry. See Scrubbing Sensitive Data for details. + + + +## HTTP Headers + +By default, the SDK collects the headers of the requests your application handles and of the responses it sends, as well as the request and response headers of the Laravel HTTP client. Values of sensitive headers are scrubbed. Use `http_headers` to control this. A single behavior applies to both request and response headers: + +```php {filename:config/sentry.php} +'data_collection' => [ + // Collect nothing: + 'http_headers' => ['mode' => 'off'], + // Or only send real values for the listed headers: + // 'http_headers' => ['mode' => 'allowList', 'terms' => ['content-type']], + // Or configure request and response headers separately: + // 'http_headers' => [ + // 'request' => ['mode' => 'denyList', 'terms' => ['-ip']], + // 'response' => ['mode' => 'off'], + // ], +], +``` + +Values whose keys match Sentry's built-in sensitive denylist (such as `auth`, `token`, or `password`) are always scrubbed, while the keys are kept. The `Cookie` and `Set-Cookie` headers are never included in the collected headers. Use the [`cookies`](#cookies) category to control them instead. See [Key-Value Collection Behavior](#key-value-collection-behavior) below for details on `mode` and `terms`. + +## Cookies + +By default, the SDK collects cookies, with sensitive values scrubbed. Opt out with `['mode' => 'off']`, or restrict which values are sent using `allowList` or `denyList` mode: + +```php {filename:config/sentry.php} +'data_collection' => [ + 'cookies' => ['mode' => 'off'], + // Or only send the real value of the `locale` cookie: + // 'cookies' => ['mode' => 'allowList', 'terms' => ['locale']], +], +``` + +The values of the Laravel session cookie, the remember-me cookies (`remember_*`), and the `XSRF-TOKEN` cookie of the requests your application handles and the responses it sends are always replaced with `[Filtered]`, even if they're in an `allowList`. + +## Information About Logged-in User + +By default, when a user is authenticated, including with Laravel Sanctum, the SDK sends the user's ID. If the user is an Eloquent model, its `email` (or `mail`) and `username` attributes are sent as well. + +The `user_info` category controls this, as well as the user's IP address (see the next section). User data you set with `setUser()` is always sent to Sentry, regardless of `data_collection`. + +## Users' IP Address + +By default, the SDK sends the user's IP address, as resolved by Laravel with your trusted proxies configuration. Disable it, together with the logged-in user information, by setting `user_info` to `false`: + +```php {filename:config/sentry.php} +'data_collection' => [ + 'user_info' => false, +], +``` + +Even when this is disabled, IP addresses can still reach Sentry through collected HTTP headers, cookies, or query parameters (for example, the `X-Forwarded-For` header). Add these terms to the deny lists for those categories so their values are filtered: + +```php {filename:config/sentry.php} +'data_collection' => [ + 'user_info' => false, + 'http_headers' => [ + 'mode' => 'denyList', + 'terms' => ['forwarded', '-ip', 'remote-', 'via', '-user'], + ], + 'cookies' => [ + 'mode' => 'denyList', + 'terms' => ['forwarded', '-ip', 'remote-', 'via', '-user'], + ], + 'url_query_params' => [ + 'mode' => 'denyList', + 'terms' => ['forwarded', '-ip', 'remote-', 'via', '-user'], + ], +], +``` + +## Request URL + +The full URL of the requests your application handles and of the requests made with the Laravel HTTP client is sent to Sentry. Depending on your application, this could contain PII data. Credentials in the URL (for example, `https://user:password@example.com`) are replaced with `[Filtered]`, and query parameters are filtered as described in [Request Query String](#request-query-string). + +## Request Query String + +By default, the SDK sends the query string of incoming and outgoing HTTP requests. Depending on your application, this could contain PII data. Values whose keys match the built-in sensitive denylist (such as `auth`, `token`, `password`, and `secret`) are replaced with `[Filtered]`. + +Use `url_query_params` to control this. Set it to `['mode' => 'off']` to disable collection entirely, or use `allowList` or `denyList` mode to filter which values are sent: + +```php {filename:config/sentry.php} +'data_collection' => [ + 'url_query_params' => ['mode' => 'off'], +], +``` + +Sentry also has some additional [server-side data scrubbing](/security-legal-pii/scrubbing/server-side-scrubbing/) in place to remove sensitive data from the query string. + +## Request and Response Bodies + +By default, the SDK collects HTTP request and response bodies. Whether a body is sent depends on its type and size: + +- **The type of the body:** + - JSON and form bodies are sent, with values whose keys match the built-in sensitive denylist scrubbed + - Bodies in other formats, or bodies that can't be parsed, are replaced with `[Filtered]` + - Streamed responses and file downloads aren't sent to Sentry + - Uploaded files are never sent to Sentry +- **The size of the body:** There's a `max_request_body_size` option that's set to `medium` by default. Bodies that exceed the size limit aren't sent to Sentry. + +To disable body collection, set `http_bodies` to an empty array, or provide only the body types you want: + +```php {filename:config/sentry.php} +'data_collection' => [ + // Collect only incoming request bodies: + 'http_bodies' => ['incomingRequest'], +], +``` + +The valid body types are: + +- `incomingRequest`: The body of the request your application handles. +- `outgoingResponse`: The body of the response your application sends. +- `outgoingRequest`: The body of a request sent with the Laravel HTTP client. +- `incomingResponse`: The body of a response received with the Laravel HTTP client. + +## Database Query Parameters + +By default, the SDK attaches the bindings of SQL queries to `db.sql.query` breadcrumbs and, when tracing is enabled, to `db.sql.query` spans. The same setting controls the command parameters on `db.redis` spans, if you enabled `tracing.redis_commands`. Disable this by setting `database_query_data` to `false`: + +```php {filename:config/sentry.php} +'data_collection' => [ + 'database_query_data' => false, +], +``` + + + +Query bindings are usually positional rather than named, so the built-in sensitive denylist can't recognize them and their values are sent as is. If your queries contain sensitive values, such as passwords or tokens, set `database_query_data` to `false`. + + + +The `breadcrumbs.sql_bindings` and `tracing.sql_bindings` options are ignored when you use `data_collection`. + +## Queue Jobs + +When tracing is enabled, the SDK attaches the data of queued jobs to `queue.publish` and `queue.process` spans, with values whose keys match the built-in sensitive denylist scrubbed. This only applies to jobs pushed with an array of data, such as `Queue::push(ProcessPodcast::class, ['podcast_id' => 1])`. The data of job classes, such as `ProcessPodcast::dispatch($podcast)`, isn't collected. + +Disable this by setting `queues` to `false`: + +```php {filename:config/sentry.php} +'data_collection' => [ + 'queues' => false, +], +``` + +## Laravel AI + +When Agent Tracing is active, Sentry collects metadata about agent activity. This can include agent names, provider names, model names, token usage, streaming state, finish reasons, conversation IDs, and tool names. + +By default, the SDK also collects the inputs and outputs of LLMs and tools: + +- **Inputs:** Prompts, system instructions, attachments, tool definitions, tool call arguments, embedding inputs, and the questions of classifications. +- **Outputs:** Assistant responses, tool call results, and the answers of classifications. + +The SDK truncates large message payloads and replaces binary or base64 content with a placeholder before sending it to Sentry. Use `gen_ai` to opt out of inputs, outputs, or both: + +```php {filename:config/sentry.php} +'data_collection' => [ + 'gen_ai' => [ + 'inputs' => false, + 'outputs' => false, + ], +], +``` + +## Source Context + +When an unhandled exception is sent to Sentry, a snapshot of the source code surrounding the line where the error originates is sent with it. + +Use `frame_context_lines` to control how many lines above and below each stack frame are captured. It defaults to `5`. Set it to `0` to only send the line where the error occurred: + +```php {filename:config/sentry.php} +'data_collection' => [ + 'frame_context_lines' => 0, +], +``` + +## Local Variables In Stack Trace + +When unhandled errors and exceptions are sent to Sentry, the names and values of local variables that were set when the errors occurred are sent at the same time. + +`stack_frame_variables` controls this and defaults to `true`. Values of variables whose names match the built-in sensitive denylist are scrubbed. Set it to `false` to stop sending variables, or use a key-value behavior to filter which variables are sent by name: + +```php {filename:config/sentry.php} +'data_collection' => [ + 'stack_frame_variables' => false, + // Or filter additional variables by name: + // 'stack_frame_variables' => ['mode' => 'denyList', 'terms' => ['email']], +], +``` + +Setting `zend.exception_ignore_args=1` in your `php.ini` prevents PHP from providing variables to the SDK, regardless of `stack_frame_variables`. On some distributions, this setting is already set to `1` by default. + +## `data_collection` Reference + +### Keys + +| Key | Type | Default | Description | +| ----------------------- | ---------------------------------------------------------- | -------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `user_info` | `bool` | `true` | Populate user fields, such as the ID, email address, and IP address, from instrumentation. | +| `cookies` | key-value behavior | `['mode' => 'denyList']` | Collect cookies. | +| `http_headers` | key-value behavior, or `['request' => …, 'response' => …]` | `['mode' => 'denyList']` | Collect HTTP headers. A single behavior applies to both request and response headers. | +| `http_bodies` | `string[]` | `['incomingRequest', 'outgoingRequest', 'incomingResponse', 'outgoingResponse']` | Body types to collect. Set to `[]` to disable. | +| `url_query_params` | key-value behavior | `['mode' => 'denyList']` | Collect URL query parameters. | +| `database_query_data` | `bool` | `true` | Collect SQL query bindings and Redis command parameters. | +| `queues` | `bool` | `true` | Collect the data of queued jobs. | +| `gen_ai` | `['inputs' => bool, 'outputs' => bool]` | `['inputs' => true, 'outputs' => true]` | Collect the inputs and outputs of LLMs and tools. | +| `stack_frame_variables` | `bool` or key-value behavior | `true` | Include variable values captured within stack frames. Accepts a boolean (`true` collects all variables, `false` collects none) or a key-value behavior to filter which variables are sent by name. | +| `frame_context_lines` | `int` | `5` | Source code lines captured above and below each stack frame. | + +Invalid values are ignored and the default is used instead. The SDK logs a debug message through the configured `logger` when this happens. + +### Key-Value Collection Behavior + +The `cookies`, `http_headers`, `url_query_params`, and `stack_frame_variables` categories take an array with a `mode` and an optional list of `terms`: + +```php +['mode' => 'denyList', 'terms' => ['forwarded', '-ip', 'remote-', 'via', '-user']] +``` + +| `mode` | Behavior | +| ------------- | --------------------------------------------------------------------------------------------------------------------- | +| `'denyList'` | Collect everything, replacing the value of any key matching `terms` (in addition to the built-in sensitive denylist). | +| `'allowList'` | Only keys matching `terms` send their real value. Every other key is kept, but its value is replaced. | +| `'off'` | Collect nothing in this category. | + +If you omit `mode`, it defaults to `'denyList'`. `terms` match partially and case-insensitively, so `'-ip'` matches `X-Real-IP`. Filtered values are replaced with `[Filtered]`; the key itself is always preserved. The built-in sensitive denylist (`auth`, `token`, `secret`, `password`, `key`, `session`, and similar) always applies, even in `'allowList'` mode. + +### Preserving `send_default_pii` Behavior + +To keep roughly the conservative collection you get with `send_default_pii` set to `false` while using `data_collection`, opt out of each category explicitly: + +```php {filename:config/sentry.php} +'data_collection' => [ + 'user_info' => false, + 'cookies' => ['mode' => 'off'], + 'http_headers' => [ + 'request' => [ + 'mode' => 'denyList', + 'terms' => ['forwarded', '-ip', 'remote-', 'via', '-user'], + ], + 'response' => ['mode' => 'off'], + ], + 'url_query_params' => [ + 'mode' => 'denyList', + 'terms' => ['forwarded', '-ip', 'remote-', 'via', '-user'], + ], + 'http_bodies' => ['incomingRequest'], + 'database_query_data' => false, + 'queues' => false, + 'gen_ai' => [ + 'inputs' => false, + 'outputs' => false, + ], +], +``` + +If you previously set `send_default_pii` to `true`, set `data_collection` to an empty array to use the defaults described on this page. diff --git a/docs/platforms/php/guides/symfony/data-management/data-collected.mdx b/docs/platforms/php/guides/symfony/data-management/data-collected.mdx index 0304468e331ad..ba524b71e0800 100644 --- a/docs/platforms/php/guides/symfony/data-management/data-collected.mdx +++ b/docs/platforms/php/guides/symfony/data-management/data-collected.mdx @@ -7,6 +7,14 @@ sidebar_section: configuration Sentry takes data privacy very seriously and has default settings in place that prioritize data safety, especially when it comes to personally identifiable information (PII) data. When you add the Sentry SDK to your application, you allow it to collect data and send it to Sentry during the runtime of your application. + + +For more fine-grained control, version 5.14.0 and later lets you opt in or out of each data category individually with the `data_collection` option. See Data Collection for details. + +This page describes the behavior controlled by the `send_default_pii` option, which remains fully supported until the next major version. + + + The category types and amount of data collected vary, depending on the integrations you've enabled in the Sentry SDK. Here's a list of data categories the Sentry PHP SDK collects: ## HTTP Headers diff --git a/docs/platforms/php/guides/symfony/data-management/data-collection.mdx b/docs/platforms/php/guides/symfony/data-management/data-collection.mdx new file mode 100644 index 0000000000000..879653aa58826 --- /dev/null +++ b/docs/platforms/php/guides/symfony/data-management/data-collection.mdx @@ -0,0 +1,290 @@ +--- +title: Data Collection +description: "See what data the Sentry Symfony SDK collects when you use the data_collection option, and how to control it." +sidebar_order: 3 +sidebar_section: configuration +--- + +Sentry takes data privacy very seriously and has default settings in place that prioritize data safety, especially when it comes to personally identifiable information (PII) data. When you add the Sentry SDK to your application, you allow it to collect data and send it to Sentry during the runtime of your application. + +The category types and amount of data collected vary, depending on the integrations you've enabled in the Sentry SDK. This page lists data categories that the Sentry Symfony SDK collects when you use the `data_collection` option. + + + +You can control the categories listed here with the `data_collection` option, which lets you opt in or out of each data category individually. The option is available in version 5.14.0 and later. + +Configure it under `sentry.options.data_collection` in `config/packages/sentry.yaml`. Omitting it, or setting it to `~` (`null`), keeps the legacy options. An empty map applies the defaults of every category: + +{/* prettier-ignore */} +```yaml {filename:config/packages/sentry.yaml} +sentry: + options: + data_collection: {} +``` + +Setting `data_collection` to `~` in a later config file, such as an environment-specific one, switches back to the legacy options, even if an earlier file opted in. `false` isn't a valid value. + +The `send_default_pii` option remains fully supported until the next major version. Without `data_collection`, the SDK collects conservatively, and the defaults described on Data Collected apply. + +As soon as you set `data_collection`, the categories you don't set explicitly fall back to the defaults described on this page, which are more permissive. For example, cookies, the user's IP address, request and response bodies, and database query parameters are then collected unless you opt out. Values whose keys match the built-in sensitive denylist are always scrubbed. + +If you set both, `send_default_pii` is ignored. The same applies to the `context_lines` option, which `data_collection` replaces with `frame_context_lines`. + +Regardless of these options, you can always scrub any data before it's sent to Sentry. See Scrubbing Sensitive Data for details. + + + +## HTTP Headers + +By default, the SDK collects the headers of the requests your application handles and of the responses it sends, as well as the request and response headers of the Symfony HTTP Client. Values of sensitive headers are scrubbed. Use `http_headers` to control this. A single behavior applies to both request and response headers: + +{/* prettier-ignore */} +```yaml {filename:config/packages/sentry.yaml} +sentry: + options: + data_collection: + # Collect nothing: + http_headers: + mode: 'off' + # Or only send real values for the listed headers: + # http_headers: + # mode: allowList + # terms: ['content-type'] + # Or configure request and response headers separately: + # http_headers: + # request: + # mode: denyList + # terms: ['-ip'] + # response: + # mode: 'off' +``` + +Values whose keys match Sentry's built-in sensitive denylist (such as `auth`, `token`, or `password`) are always scrubbed, while the keys are kept. The `Cookie` and `Set-Cookie` headers are never included in the collected headers. Use the [`cookies`](#cookies) category to control them instead. See [Key-Value Collection Behavior](#key-value-collection-behavior) below for details on `mode` and `terms`. + +For the Symfony HTTP Client, the SDK only collects the headers you pass with the `headers` option, including the client's default headers. Headers the client adds itself, for example, through the `auth_bearer` or `json` options, aren't collected. + +## Cookies + +By default, the SDK collects cookies, with sensitive values scrubbed. Opt out with `mode: 'off'`, or restrict which values are sent using `allowList` or `denyList` mode: + +{/* prettier-ignore */} +```yaml {filename:config/packages/sentry.yaml} +sentry: + options: + data_collection: + cookies: + mode: 'off' + # Or only send the real value of the `locale` cookie: + # cookies: + # mode: allowList + # terms: ['locale'] +``` + +## Information About Logged-in User + +By default, when a user is authenticated with the Symfony Security component, the SDK sends the user identifier as the user's ID. If the user is being impersonated, the username of the impersonator is sent as well. + +The `user_info` category controls this, as well as the user's IP address (see the next section). User data you set with `setUser()` is always sent to Sentry, regardless of `data_collection`. + +## Users' IP Address + +By default, the SDK sends the user's IP address. Disable it, together with the logged-in user information, by setting `user_info` to `false`: + +{/* prettier-ignore */} +```yaml {filename:config/packages/sentry.yaml} +sentry: + options: + data_collection: + user_info: false +``` + +Even when this is disabled, IP addresses can still reach Sentry through collected HTTP headers, cookies, or query parameters (for example, the `X-Forwarded-For` header). Add these terms to the deny lists for those categories so their values are filtered: + +{/* prettier-ignore */} +```yaml {filename:config/packages/sentry.yaml} +sentry: + options: + data_collection: + user_info: false + http_headers: + mode: denyList + terms: ['forwarded', '-ip', 'remote-', 'via', '-user'] + cookies: + mode: denyList + terms: ['forwarded', '-ip', 'remote-', 'via', '-user'] + url_query_params: + mode: denyList + terms: ['forwarded', '-ip', 'remote-', 'via', '-user'] +``` + +## Request URL + +The full URL of the requests your application handles and of the requests made with the Symfony HTTP Client is sent to Sentry. Depending on your application, this could contain PII data. Credentials in the URL (for example, `https://user:password@example.com`) are replaced with `[Filtered]`, and query parameters are filtered as described in [Request Query String](#request-query-string). + +## Request Query String + +By default, the SDK sends the query string of incoming and outgoing HTTP requests. Depending on your application, this could contain PII data. Values whose keys match the built-in sensitive denylist (such as `auth`, `token`, `password`, and `secret`) are replaced with `[Filtered]`. + +Use `url_query_params` to control this. Set its `mode` to `'off'` to disable collection entirely, or use `allowList` or `denyList` mode to filter which values are sent: + +{/* prettier-ignore */} +```yaml {filename:config/packages/sentry.yaml} +sentry: + options: + data_collection: + url_query_params: + mode: 'off' +``` + +Sentry also has some additional [server-side data scrubbing](/security-legal-pii/scrubbing/server-side-scrubbing/) in place to remove sensitive data from the query string. + +## Request and Response Bodies + +By default, the SDK collects HTTP request and response bodies. Whether a body is sent depends on its type and size: + +- **The type of the body:** + - JSON and form bodies are sent, with values whose keys match the built-in sensitive denylist scrubbed + - Bodies in other formats, or bodies that can't be parsed, are replaced with `[Filtered]` + - Streamed responses and file downloads (`StreamedResponse` and `BinaryFileResponse`) are replaced with `[Filtered]` + - Uploaded files are never sent to Sentry +- **The size of the body:** There's a `max_request_body_size` option that's set to `medium` by default. Bodies that exceed the size limit aren't sent to Sentry. + +To disable body collection, set `http_bodies` to an empty list, or provide only the body types you want: + +{/* prettier-ignore */} +```yaml {filename:config/packages/sentry.yaml} +sentry: + options: + data_collection: + # Collect only incoming request bodies: + http_bodies: ['incomingRequest'] +``` + +The valid body types are: + +- `incomingRequest`: The body of the request your application handles. +- `outgoingResponse`: The body of the response your application sends. +- `outgoingRequest`: The body of a request sent with the Symfony HTTP Client. +- `incomingResponse`: The body of a response received with the Symfony HTTP Client. It's only collected when your application reads it with `getContent()` or `toArray()`. + +## Database Query Parameters + +When tracing is enabled, the SDK attaches the parameters of Doctrine DBAL queries to `db.sql.execute` spans. Disable this by setting `database_query_data` to `false`: + +{/* prettier-ignore */} +```yaml {filename:config/packages/sentry.yaml} +sentry: + options: + data_collection: + database_query_data: false +``` + + + +Doctrine usually binds parameters by position rather than by name, so the built-in sensitive denylist can't recognize them and their values are sent as is. If your queries contain sensitive values, such as passwords or tokens, set `database_query_data` to `false`. + + + +## Console Commands + +When an error occurs in a console command, the SDK attaches the command as it was run to the event. Values of arguments and options whose names match the built-in sensitive denylist are replaced with `[Filtered]`. For example, `app:import --password=secret` becomes `app:import --password=[Filtered]`. + +If the input can't be parsed, for example, because it contains an unknown option, all arguments and options are replaced with `[Filtered]`. + +## Source Context + +When an unhandled exception is sent to Sentry, a snapshot of the source code surrounding the line where the error originates is sent with it. + +Use `frame_context_lines` to control how many lines above and below each stack frame are captured. It defaults to `5`. Set it to `0` to only send the line where the error occurred: + +{/* prettier-ignore */} +```yaml {filename:config/packages/sentry.yaml} +sentry: + options: + data_collection: + frame_context_lines: 0 +``` + +## Local Variables In Stack Trace + +When unhandled errors and exceptions are sent to Sentry, the names and values of local variables that were set when the errors occurred are sent at the same time. + +`stack_frame_variables` controls this and defaults to `true`. Values of variables whose names match the built-in sensitive denylist are scrubbed. Set it to `false` to stop sending variables, or use a key-value behavior to filter which variables are sent by name: + +{/* prettier-ignore */} +```yaml {filename:config/packages/sentry.yaml} +sentry: + options: + data_collection: + stack_frame_variables: false + # Or filter additional variables by name: + # stack_frame_variables: + # mode: denyList + # terms: ['email'] +``` + +Setting `zend.exception_ignore_args=1` in your `php.ini` prevents PHP from providing variables to the SDK, regardless of `stack_frame_variables`. On some distributions, this setting is already set to `1` by default. + +## `data_collection` Reference + +### Keys + +| Key | Type | Default | Description | +| ----------------------- | ---------------------------------------------------- | -------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `user_info` | `bool` | `true` | Populate user fields, such as the user identifier and IP address, from instrumentation. | +| `cookies` | key-value behavior | `{ mode: denyList }` | Collect cookies. | +| `http_headers` | key-value behavior, or `{ request: …, response: … }` | `{ mode: denyList }` | Collect HTTP headers. A single behavior applies to both request and response headers. | +| `http_bodies` | `string[]` | `['incomingRequest', 'outgoingRequest', 'incomingResponse', 'outgoingResponse']` | Body types to collect. Set to `[]` to disable. | +| `url_query_params` | key-value behavior | `{ mode: denyList }` | Collect URL query parameters. | +| `database_query_data` | `bool` | `true` | Collect the parameters of Doctrine DBAL queries. | +| `stack_frame_variables` | `bool` or key-value behavior | `true` | Include variable values captured within stack frames. Accepts a boolean (`true` collects all variables, `false` collects none) or a key-value behavior to filter which variables are sent by name. | +| `frame_context_lines` | `int` | `5` | Source code lines captured above and below each stack frame. | + +The `gen_ai` and `queues` keys are accepted as well, but the Symfony SDK doesn't collect any data in these categories yet. + +Invalid values, such as an unknown `mode` or body type, fail the container build with a configuration error. + +### Key-Value Collection Behavior + +The `cookies`, `http_headers`, `url_query_params`, and `stack_frame_variables` categories take a `mode` and an optional list of `terms`: + +{/* prettier-ignore */} +```yaml +mode: denyList +terms: ['forwarded', '-ip', 'remote-', 'via', '-user'] +``` + +| `mode` | Behavior | +| ----------- | --------------------------------------------------------------------------------------------------------------------- | +| `denyList` | Collect everything, replacing the value of any key matching `terms` (in addition to the built-in sensitive denylist). | +| `allowList` | Only keys matching `terms` send their real value. Every other key is kept, but its value is replaced. | +| `'off'` | Collect nothing in this category. | + +If you omit `mode`, it defaults to `denyList`. `terms` match partially and case-insensitively, so `-ip` matches `X-Real-IP`. Filtered values are replaced with `[Filtered]`; the key itself is always preserved. The built-in sensitive denylist (`auth`, `token`, `secret`, `password`, `key`, `session`, and similar) always applies, even in `allowList` mode. + +### Preserving `send_default_pii` Behavior + +To keep roughly the conservative collection you get with `send_default_pii` set to `false` while using `data_collection`, opt out of each category explicitly: + +{/* prettier-ignore */} +```yaml {filename:config/packages/sentry.yaml} +sentry: + options: + data_collection: + user_info: false + cookies: + mode: 'off' + http_headers: + request: + mode: denyList + terms: ['forwarded', '-ip', 'remote-', 'via', '-user'] + response: + mode: 'off' + url_query_params: + mode: denyList + terms: ['forwarded', '-ip', 'remote-', 'via', '-user'] + http_bodies: ['incomingRequest'] + database_query_data: false +``` + +If you previously set `send_default_pii` to `true`, set `data_collection` to an empty map (`{}`) to use the defaults described on this page. From f600dd2dbe3678b8a422458496fe08149d082836 Mon Sep 17 00:00:00 2001 From: Martin Linzmayer Date: Thu, 8 Oct 2026 15:58:27 +0200 Subject: [PATCH 4/5] fix --- .../php/guides/laravel/data-management/data-collection.mdx | 2 +- .../php/guides/symfony/data-management/data-collection.mdx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/platforms/php/guides/laravel/data-management/data-collection.mdx b/docs/platforms/php/guides/laravel/data-management/data-collection.mdx index 341d7be9f3bec..25bfc1d4f6dd5 100644 --- a/docs/platforms/php/guides/laravel/data-management/data-collection.mdx +++ b/docs/platforms/php/guides/laravel/data-management/data-collection.mdx @@ -65,7 +65,7 @@ The values of the Laravel session cookie, the remember-me cookies (`remember_*`) ## Information About Logged-in User -By default, when a user is authenticated, including with Laravel Sanctum, the SDK sends the user's ID. If the user is an Eloquent model, its `email` (or `mail`) and `username` attributes are sent as well. +By default, when a user is authenticated, including with Laravel Sanctum, the SDK sends the user's ID and its `email` (or `mail`) and `username` attributes. This only applies to users that are Eloquent models. The `user_info` category controls this, as well as the user's IP address (see the next section). User data you set with `setUser()` is always sent to Sentry, regardless of `data_collection`. diff --git a/docs/platforms/php/guides/symfony/data-management/data-collection.mdx b/docs/platforms/php/guides/symfony/data-management/data-collection.mdx index 879653aa58826..960e82c487dc0 100644 --- a/docs/platforms/php/guides/symfony/data-management/data-collection.mdx +++ b/docs/platforms/php/guides/symfony/data-management/data-collection.mdx @@ -187,7 +187,7 @@ Doctrine usually binds parameters by position rather than by name, so the built- ## Console Commands -When an error occurs in a console command, the SDK attaches the command as it was run to the event. Values of arguments and options whose names match the built-in sensitive denylist are replaced with `[Filtered]`. For example, `app:import --password=secret` becomes `app:import --password=[Filtered]`. +When a console command runs, the SDK attaches the command as it was run to the events captured during it. Values of arguments and options whose names match the built-in sensitive denylist are replaced with `[Filtered]`. For example, `app:import --password=secret` becomes `app:import --password=[Filtered]`. If the input can't be parsed, for example, because it contains an unknown option, all arguments and options are replaced with `[Filtered]`. From eb2d14c30c9121f55fe46310f414e191a34ce0d8 Mon Sep 17 00:00:00 2001 From: Martin Linzmayer Date: Thu, 8 Oct 2026 16:00:54 +0200 Subject: [PATCH 5/5] fix --- .../php/guides/laravel/data-management/data-collection.mdx | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/platforms/php/guides/laravel/data-management/data-collection.mdx b/docs/platforms/php/guides/laravel/data-management/data-collection.mdx index 25bfc1d4f6dd5..a3234f8a635c3 100644 --- a/docs/platforms/php/guides/laravel/data-management/data-collection.mdx +++ b/docs/platforms/php/guides/laravel/data-management/data-collection.mdx @@ -61,8 +61,6 @@ By default, the SDK collects cookies, with sensitive values scrubbed. Opt out wi ], ``` -The values of the Laravel session cookie, the remember-me cookies (`remember_*`), and the `XSRF-TOKEN` cookie of the requests your application handles and the responses it sends are always replaced with `[Filtered]`, even if they're in an `allowList`. - ## Information About Logged-in User By default, when a user is authenticated, including with Laravel Sanctum, the SDK sends the user's ID and its `email` (or `mail`) and `username` attributes. This only applies to users that are Eloquent models.