diff --git a/docs/platforms/python/configuration/options.mdx b/docs/platforms/python/configuration/options.mdx
index 34993c39071f53..801bcf640a37eb 100644
--- a/docs/platforms/python/configuration/options.mdx
+++ b/docs/platforms/python/configuration/options.mdx
@@ -126,77 +126,11 @@ sentry_sdk.init(
)
```
-Passing a `data_collection` dictionary opts you into its defaults, which are more permissive than `send_default_pii=False`. Any key you don't set falls back to the default in the table below, so the SDK collects rich debugging context (user identity, request bodies, generative AI content) and scrubs values whose keys match the built-in sensitive denylist (`auth`, `token`, `password`, and similar).
+Passing a `data_collection` dictionary opts you into its defaults, which are more permissive than `send_default_pii=False`. Any key you don't set falls back to its default, so the SDK collects rich debugging context (user identity, request bodies, generative AI content) 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 entirely and the SDK emits a `DeprecationWarning`.
-For more on what data Sentry collects and how to control it, see Data Collected.
-
-### Keys
-
-| Key | Type | Default | Description |
-| ----------------------- | --------------------------------------- | ---------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `user_info` | `bool` | `True` | Populate `user.*` fields (`id`, `email`, `username`, `ip_address`) from instrumentation. |
-| `cookies` | key-value behavior | `{"mode": "denylist"}` | Collect cookies. |
-| `http_headers` | `{"request": key-value behavior}` | `{"request": {"mode": "denylist"}}` | Collect HTTP request headers. The Python SDK currently doesn't capture response headers. |
-| `http_bodies` | `list[str]` | `["incoming_request", "outgoing_request"]` | Body types to collect. Set to `[]` to disable. The Python SDK currently doesn't capture response bodies. |
-| `url_query_params` | key-value behavior | `{"mode": "denylist"}` | Collect URL query parameters. |
-| `graphql` | `{"document": bool, "variables": bool}` | both `True` | Collect the GraphQL query document and its variables. |
-| `gen_ai` | `{"inputs": bool, "outputs": bool}` | both `True` | Collect generative AI input and output content. Metadata such as the model ID and token counts is always collected. |
-| `database_query_data` | `bool` | `True` | Collect database query data. Query parameter values are never sent; queries are parameterized first. |
-| `queues` | `bool` | `True` | Collect message body data for queue and task-queue integrations. |
-| `stack_frame_variables` | `bool` or key-value behavior | `True` | Include local 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 (see [Filtering Stack Frame Variables](https://develop.sentry.dev/sdk/foundations/client/data-collection/#filtering-stack-frame-variables)). |
-| `frame_context_lines` | `int` or `bool` | `5` | Source code lines captured above and below each stack frame. `True` means the default of `5`, `False` means `0`. |
-
-### Key-Value Collection Behavior
-
-The `cookies`, `http_headers["request"]`, and `url_query_params` categories take a dictionary with a `mode` and an optional list of `terms`:
-
-```python
-{"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. |
-
-`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=False` Behavior
-
-To keep the conservative collection you get from `send_default_pii=False` while using `data_collection`, opt out of each category explicitly:
-
-```python
-import sentry_sdk
-
-sentry_sdk.init(
- dsn="___PUBLIC_DSN___",
- data_collection={
- "user_info": False,
- "gen_ai": {"inputs": False, "outputs": False},
- "graphql": {"document": False, "variables": False},
- "database_query_data": False,
- "queues": False,
- "http_bodies": [],
- "cookies": {
- "mode": "denylist",
- "terms": ["forwarded", "-ip", "remote-", "via", "-user"],
- },
- "http_headers": {
- "request": {
- "mode": "denylist",
- "terms": ["forwarded", "-ip", "remote-", "via", "-user"],
- },
- },
- "url_query_params": {
- "mode": "denylist",
- "terms": ["forwarded", "-ip", "remote-", "via", "-user"],
- },
- },
-)
-```
+For the full reference of available keys and their defaults, see Data Collected.
@@ -204,6 +138,8 @@ sentry_sdk.init(
Scrubs the event payload for sensitive information such as cookies, sessions, and passwords from a `denylist`. It can additionally be used to scrub from another `pii_denylist` if `send_default_pii` is disabled. See how to [configure the scrubber here](../../data-management/sensitive-data/#event-scrubber).
+Only runs if `data_collection` is not defined. See Data Collected.
+
diff --git a/docs/platforms/python/data-management/data-collected.mdx b/docs/platforms/python/data-management/data-collected.mdx
index 3ebe700b97a94f..76f8e740d80726 100644
--- a/docs/platforms/python/data-management/data-collected.mdx
+++ b/docs/platforms/python/data-management/data-collected.mdx
@@ -48,7 +48,7 @@ sentry_sdk.init(
)
```
-Values whose keys match Sentry's built-in sensitive denylist (such as `auth`, `token`, or `password`) are always scrubbed, while the keys are kept. See the `data_collection` reference for details on `mode` and `terms`.
+Values whose keys match Sentry's built-in sensitive denylist (such as `auth`, `token`, or `password`) are always scrubbed, while the keys are kept. See [Key-Value Collection Behavior](#key-value-collection-behavior) below for details on `mode` and `terms`.
Additionally a [data scrubber](/platforms/python/data-management/sensitive-data/) removes sensitive data from headers (and a lot of other fields) right before sending data to Sentry.
@@ -290,3 +290,71 @@ sentry_sdk.init(
```
`gen_ai` supersedes the per-integration `include_prompts` parameter. When `data_collection` is set, `gen_ai` determines whether prompt content is recorded, regardless of what an individual integration's `include_prompts` is set to.
+
+## `data_collection` Reference
+
+### Keys
+
+| Key | Type | Default | Description |
+| ----------------------- | --------------------------------------- | ---------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `user_info` | `bool` | `True` | Populate `user.*` fields (`id`, `email`, `username`, `ip_address`) from instrumentation. |
+| `cookies` | key-value behavior | `{"mode": "denylist"}` | Collect cookies. |
+| `http_headers` | `{"request": key-value behavior}` | `{"request": {"mode": "denylist"}}` | Collect HTTP request headers. The Python SDK currently doesn't capture response headers. |
+| `http_bodies` | `list[str]` | `["incoming_request", "outgoing_request"]` | Body types to collect. Set to `[]` to disable. The Python SDK currently doesn't capture response bodies. |
+| `url_query_params` | key-value behavior | `{"mode": "denylist"}` | Collect URL query parameters. |
+| `graphql` | `{"document": bool, "variables": bool}` | both `True` | Collect the GraphQL query document and its variables. |
+| `gen_ai` | `{"inputs": bool, "outputs": bool}` | both `True` | Collect generative AI input and output content. Metadata such as the model ID and token counts is always collected. |
+| `database_query_data` | `bool` | `True` | Collect database query data. Query parameter values are never sent; queries are parameterized first. |
+| `queues` | `bool` | `True` | Collect message body data for queue and task-queue integrations. |
+| `stack_frame_variables` | `bool` or key-value behavior | `True` | Include local 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 (see [Filtering Stack Frame Variables](https://develop.sentry.dev/sdk/foundations/client/data-collection/#filtering-stack-frame-variables)). |
+| `frame_context_lines` | `int` or `bool` | `5` | Source code lines captured above and below each stack frame. `True` means the default of `5`, `False` means `0`. |
+
+### Key-Value Collection Behavior
+
+The `cookies`, `http_headers["request"]`, and `url_query_params` categories take a dictionary with a `mode` and an optional list of `terms`:
+
+```python
+{"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. |
+
+`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=False` Behavior
+
+To keep the conservative collection you get from `send_default_pii=False` while using `data_collection`, opt out of each category explicitly:
+
+```python
+import sentry_sdk
+
+sentry_sdk.init(
+ dsn="___PUBLIC_DSN___",
+ data_collection={
+ "user_info": False,
+ "gen_ai": {"inputs": False, "outputs": False},
+ "graphql": {"document": False, "variables": False},
+ "database_query_data": False,
+ "queues": False,
+ "http_bodies": [],
+ "cookies": {
+ "mode": "denylist",
+ "terms": ["forwarded", "-ip", "remote-", "via", "-user"],
+ },
+ "http_headers": {
+ "request": {
+ "mode": "denylist",
+ "terms": ["forwarded", "-ip", "remote-", "via", "-user"],
+ },
+ },
+ "url_query_params": {
+ "mode": "denylist",
+ "terms": ["forwarded", "-ip", "remote-", "via", "-user"],
+ },
+ },
+)
+```
diff --git a/docs/platforms/python/data-management/sensitive-data/index.mdx b/docs/platforms/python/data-management/sensitive-data/index.mdx
index b397e17d31cdf6..e12b491821416b 100644
--- a/docs/platforms/python/data-management/sensitive-data/index.mdx
+++ b/docs/platforms/python/data-management/sensitive-data/index.mdx
@@ -31,9 +31,9 @@ Ensure that your team is aware of your company's policy around what can and cann
## Personally Identifiable Information (PII)
-The SDK purposefully does not send PII to stay on the safe side. This behavior is controlled by an option called [`send_default_pii`](../../configuration/options/#send_default_pii).
+The SDK can be configured to collect or ignore specific data using the [`data_collection`](../../configuration/options/#data_collection) option.
-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).
+Alternately, you can use the simpler [`send_default_pii`](../../configuration/options/#send_default_pii) option by setting it to `True` or `False`. Note that this option will be phased out in favor of the more fine-grained [`data_collection`](../../configuration/options/#data_collection).
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/).
@@ -41,7 +41,7 @@ If you _do not_ wish to use the default PII behavior, you can also choose to ide
### `event_scrubber`
-You can use the configuration parameter to simplify removing sensitive data from your event payload.
+If using `send_default_pii`, you can use the configuration parameter to simplify removing sensitive data from your event payload. The event scrubber has no effect when using `data_collection`.