Skip to content

ref(python): Move data_collection config to Data Collected page #19573

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
sentrivana wants to merge 3 commits into
base: master
Choose a base branch
from
+76 −72
Open

ref(python): Move data_collection config to Data Collected page #19573

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
63220b2
ref(python): Move data_collection config to Data Management page
sentrivana Sep 23, 2026
d402ef7
.
sentrivana Sep 23, 2026
c9e619b
.
sentrivana Sep 23, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
72 changes: 4 additions & 68 deletions docs/platforms/python/configuration/options.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -126,84 +126,20 @@ 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 <PlatformLink to="/data-management/data-collected/">Data Collected</PlatformLink>.

### 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 <PlatformLink to="/data-management/data-collected/">Data Collected</PlatformLink>.

</SdkOption>

<SdkOption name="event_scrubber" type='sentry_sdk.scrubber.EventScrubber' defaultValue='None'>

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 <PlatformLink to="/data-management/data-collected/">Data Collected</PlatformLink>.

</SdkOption>

<SdkOption name="include_source_context" type='bool' defaultValue='True'>
Expand Down
70 changes: 69 additions & 1 deletion docs/platforms/python/data-management/data-collected.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 <PlatformLink to="/configuration/options/#data_collection">the `data_collection` reference</PlatformLink> 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.

Expand Down Expand Up @@ -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"],
},
},
)
```
Loading
Loading