docs(java): Document Data Collection controls

docs/platforms/android/configuration/options.mdx

@@ -100,6 +100,10 @@ AndroidManifest.xml key: `io.sentry.additional-context`.
 
 If this flag is enabled, certain personally identifiable information (PII) is added by active integrations.
 
+This is a legacy flag. Use [`dataCollection`](#dataCollection) for granular control over automatically collected data.
+
+For backwards compatibility, `sendDefaultPii` keeps its existing behavior when no Data Collection field is configured. As soon as you configure any `dataCollection` field, Data Collection becomes the source of truth for its categories and `sendDefaultPii` no longer controls them.
+
 <Alert>
 
 If you are using Sentry in your mobile app, read our [frequently asked questions about mobile data privacy](/security-legal-pii/security/mobile-privacy/) to assist with Apple App Store and Google Play app privacy details.
@@ -110,6 +114,110 @@ If you enable this option, be sure to manually remove what you don't want to sen
 
 </SdkOption>
 
+<SdkOption name="dataCollection" type="DataCollection" availableSince="8.58.0">
+
+Controls which categories of data SDK integrations collect automatically. Data Collection applies only where an integration supports the category. It doesn't remove data you add explicitly through scopes, event processors, or callbacks such as `beforeSend`.
+
+<Alert>
+
+Call `options.getDataCollection().forceDataCollection()` or explicitly configure any field to enable Data Collection. All fields you don't configure use the defaults below, and the `sendDefaultPii` option is ignored.
+
+</Alert>
+
+| Field                    | Type                         | Default        | Behavior                                                                                                                                  |
+| ------------------------ | ---------------------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| `userInfo`               | `boolean`                    | `true`         | Allows integrations to populate user identity and IP address information.                                                                 |
+| `cookies`\*              | `KeyValueCollectionBehavior` | `DENY_LIST`    | Collects cookies and filters sensitive values.                                                                                            |
+| `httpHeaders.request`\*  | `KeyValueCollectionBehavior` | `DENY_LIST`    | Collects request headers and filters sensitive values.                                                                                    |
+| `httpHeaders.response`\* | `KeyValueCollectionBehavior` | `DENY_LIST`    | Collects response headers and filters sensitive values.                                                                                   |
+| `httpBodies`             | `Set<HttpBodyType>`          | all body types | Collects supported incoming and outgoing request and response bodies. An empty set disables body collection.                              |
+| `urlQueryParams`\*       | `KeyValueCollectionBehavior` | `DENY_LIST`    | Collects URL query parameters and filters sensitive values.                                                                               |
+| `graphql.document`       | `boolean`                    | `true`         | Collects GraphQL documents.                                                                                                               |
+| `graphql.variables`      | `boolean`                    | `true`         | Collects GraphQL variables.                                                                                                               |
+| `filePaths`              | `boolean`                    | `true`         | Allows File I/O instrumentation to collect file names and absolute paths. File extensions and byte counts remain available when disabled. |
+
+\* Fields marked with an asterisk take a single `KeyValueCollectionBehavior` value in code. Properties, environment variables, Spring Boot, and Android manifest metadata expose that value as separate `mode` and `terms` settings. `terms` contains additional matching terms for deny-list or allow-list behavior.
+
+The marked fields support three modes:
+
+- `OFF` (`KeyValueCollectionBehavior.off()`): Don't collect the category.
+- `DENY_LIST` (`KeyValueCollectionBehavior.denyList(...)`): Collect values except those matching the built-in sensitive list or additional configured terms. The no-argument constructor uses this mode without custom terms.
+- `ALLOW_LIST` (`KeyValueCollectionBehavior.allowList(...)`): Include plaintext values only for keys that match configured terms and don't match the built-in sensitive list. Sensitive values are always replaced with `"[Filtered]"`.
+
+Matching is partial and case-insensitive. The built-in terms are `auth`, `token`, `secret`, `password`, `passwd`, `pwd`, `key`, `jwt`, `bearer`, `sso`, `saml`, `csrf`, `xsrf`, `credentials`, `session`, `sid`, and `identity`. Filtered values are replaced with `"[Filtered]"`. Custom deny-list terms extend the built-in list rather than replacing it.
+
+When migrating from `sendDefaultPii=false`, configuring Data Collection causes supported integrations to send HTTP request and response headers by default. Review these headers for sensitive data and adjust `httpHeaders.request` and `httpHeaders.response` as needed.
+
+The legacy header filtering also omitted sensitive headers such as `X-Forwarded-For`, `X-Real-IP`, and `Remote-Addr` in supported integrations. After you configure any Data Collection field, `sendDefaultPii` no longer controls these headers. Data Collection's default deny list filters credential and secret values but doesn't automatically match those identifying headers. To continue filtering them, add `forwarded`, `-ip`, `remote-`, `via`, and `-user` to a deny list. These terms also match keys such as `CF-Connecting-IP` and `X-User-Id`. Add them to `cookies`, `httpHeaders.request`, `httpHeaders.response`, or `urlQueryParams` as needed.
+
+Configure Data Collection in `AndroidManifest.xml`:
+
+```xml {filename:AndroidManifest.xml}
+<application>
+  <meta-data
+      android:name="io.sentry.data-collection.user-info"
+      android:value="false" />
+  <meta-data
+      android:name="io.sentry.data-collection.http-bodies"
+      android:value="outgoing_request,incoming_response" />
+  <meta-data
+      android:name="io.sentry.data-collection.http-headers.request.mode"
+      android:value="deny_list" />
+  <meta-data
+      android:name="io.sentry.data-collection.http-headers.request.terms"
+      android:value="forwarded,-ip,remote-,via,-user" />
+  <meta-data
+      android:name="io.sentry.data-collection.url-query-params.mode"
+      android:value="off" />
+  <meta-data
+      android:name="io.sentry.data-collection.file-paths"
+      android:value="false" />
+</application>
+```
+
+Supported manifest keys are:
+
+- `io.sentry.data-collection.user-info`
+- `io.sentry.data-collection.http-bodies`
+- `io.sentry.data-collection.cookies.mode` and `.terms`
+- `io.sentry.data-collection.http-headers.request.mode` and `.terms`
+- `io.sentry.data-collection.http-headers.response.mode` and `.terms`
+- `io.sentry.data-collection.url-query-params.mode` and `.terms`
+- `io.sentry.data-collection.graphql.document`
+- `io.sentry.data-collection.graphql.variables`
+- `io.sentry.data-collection.file-paths`
+
+For manual initialization, use the same Java API as the Java SDK:
+
+```kotlin
+import io.sentry.KeyValueCollectionBehavior
+import io.sentry.android.core.SentryAndroid
+
+SentryAndroid.init(this) { options ->
+  options.dataCollection.userInfo = false
+  options.dataCollection.filePaths = false
+  options.dataCollection.urlQueryParams = KeyValueCollectionBehavior.off()
+  options.dataCollection.httpHeaders.request =
+    KeyValueCollectionBehavior.denyList("forwarded", "-ip", "remote-", "via", "-user")
+}
+```
+
+### Migrating From `sendDefaultPii`
+
+Data Collection preserves existing applications until you opt in:
+
+| Configuration             | Result                                                                                                                                       |
+| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| No Data Collection fields | Existing `sendDefaultPii` behavior is preserved.                                                                                             |
+| `forceDataCollection()`   | All Data Collection categories use the defaults above.                                                                                       |
+| Any Data Collection field | That field uses its configured value, omitted fields use the defaults above, and `sendDefaultPii` is ignored for Data Collection categories. |
+
+If you previously used `sendDefaultPii=false`, either leave Data Collection unset to preserve that behavior or explicitly disable every category you don't want collected. If you used `sendDefaultPii=true`, call `options.getDataCollection().forceDataCollection()` to opt into the new filtered defaults.
+
+Data Collection doesn't control Session Replay. Configure Replay's URL, header, and body collection separately in the <PlatformLink to="/session-replay/configuration/">Session Replay options</PlatformLink>.
+
+</SdkOption>
+
 <SdkOption name="autoSessionTracking" type="bool" defaultValue="true">
 
 When set to `true`, the SDK will send session events to Sentry. This is supported in all browser SDKs, emitting one session per pageload and page navigation to Sentry. In mobile SDKs, when the app goes to the background for longer than 30 seconds, sessions are ended.

docs/platforms/android/data-management/data-collected.mdx

@@ -6,45 +6,47 @@ 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.
 
-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 Android SDK collects.
+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 Android SDK collects. Use <PlatformLink to="/configuration/options/#dataCollection"><PlatformIdentifier name="data-collection" /></PlatformLink> to control automatic collection for supported categories.
 
-Many of the categories listed here require you to enable the <PlatformLink to="/configuration/options/#sendDefaultPii">sendDefaultPii option</PlatformLink>.
+After you configure any Data Collection field or call `options.getDataCollection().forceDataCollection()`, unconfigured fields use their documented defaults.
+
+Data Collection controls only data added automatically by SDK integrations. Data you add through scopes, event processors, `beforeSend`, or other APIs is still sent.
 
 ## HTTP Headers
 
-By default, the Sentry SDK doesn't send any headers for outgoing HTTP requests. Even when sending HTTP headers is enabled, we have a [denylist](https://github.com/getsentry/sentry-java/blob/main/sentry/src/main/java/io/sentry/util/HttpUtils.java#L21-L34) in place, which filters out any headers that contain sensitive data.
+Request and response headers use `DENY_LIST` by default. Supported integrations collect header names and non-sensitive values while replacing sensitive values with `"[Filtered]"`.
 
-To start sending HTTP headers, set <PlatformLink to="/configuration/options/#sendDefaultPii">`sendDefaultPii=true`</PlatformLink>. Outside of the `sendDefaultPii` flag, you can opt to have specific headers captured in recorded user sessions. See the [Session Replay network detail options](/platforms/android/session-replay/configuration/) for more details.
+Configure <PlatformLink to="/configuration/options/#dataCollection">`dataCollection.httpHeaders.request`</PlatformLink> and <PlatformLink to="/configuration/options/#dataCollection">`dataCollection.httpHeaders.response`</PlatformLink> to control header collection. `Cookie` and `Set-Cookie` values in the general HTTP header map are always replaced with `"[Filtered]"`; use `dataCollection.cookies` to control separately collected cookie data. OkHttp, Ktor Client, and Apollo 3 and 4 can attach available request and response headers to captured HTTP client errors.
 
-## Cookies
+Session Replay network details use [separate options](/platforms/android/session-replay/configuration/).
 
-By default, the Sentry SDK doesn't send cookies. Sentry tries to remove any cookies that contain sensitive information, such as the Session ID and CSRF Token cookies.
+## Cookies
 
-If you want to send cookies, set <PlatformLink to="/configuration/options/#send-default-pii">`sendDefaultPii=true`</PlatformLink>.
+Cookies use `DENY_LIST` by default. Supported integrations collect cookies while replacing sensitive values with `"[Filtered]"`. Use `dataCollection.cookies` to control cookie collection.
 
 ## Information About Logged-in User
 
-By default, the Sentry SDK doesn't send any information about the logged-in user, such as email address, user ID, or username. Even if enabled, the type of logged-in user information you'll be able to send depends on the integrations you enable in Sentry's SDK. Most integrations won't send any user information. Some will only set the user ID, but there are a few that will set the user ID, username, and email address.
+The SDK assigns a random installation ID when an event has no user ID. This ID is generated once per app installation and isn't controlled by Data Collection.
 
-To start sending logged-in user information, set <PlatformLink to="/configuration/options/#send-default-pii">`sendDefaultPii=true`</PlatformLink>.
+`dataCollection.userInfo` allows integrations to populate other user identity information automatically. It defaults to `true`. Set it to `false` to disable automatic user enrichment. User information you set explicitly with `Sentry.setUser()` or on a scope isn't removed.
 
 ## Users' IP Addresses
 
-By default, the Sentry SDK doesn't send the user's IP address. Once enabled, the Sentry backend services will infer the user ip address based on the incoming request, unless certain integrations you can enable override this behavior.
-
-To enable sending the user's IP address, set <PlatformLink to="/configuration/options/#send-default-pii">`sendDefaultPii=true`</PlatformLink>.
+When `dataCollection.userInfo` is `true`, the SDK adds `"{{auto}}"` as the user's IP address so Sentry can infer it from the connection. Set `dataCollection.userInfo=false` to disable automatic IP enrichment.
 
 ## Request URL
 
-The full request URL of outgoing and incoming HTTP requests is **always sent to Sentry**. Depending on your application, this could contain PII data.
+The request URL (without the query string) of outgoing and incoming HTTP requests is **always sent to Sentry**. Depending on your application, this could contain PII data.
 
 ## Request Query String
 
-The full request query string of outgoing and incoming HTTP requests is **always sent to Sentry**. Depending on your application, this could contain PII data.
+Query parameters use `DENY_LIST` by default. Use `dataCollection.urlQueryParams` to filter or disable query string collection for instrumented request URLs.
 
 ## Request and Response Bodies
 
-By default, no request or response bodies are sent to Sentry from the Android SDK. If you want to collect request or response bodies in recorded user sessions, see the Session Replay [network detail configuration docs](/platforms/android/session-replay/configuration/).
+All request and response body directions are enabled by default, but integrations collect bodies only where supported. Some integrations collect body content, while others collect only body sizes.
+
+Use `dataCollection.httpBodies` to choose which directions to collect or an empty set to disable body collection. Session Replay network body collection uses [separate options](/platforms/android/session-replay/configuration/).
 
 ## Source Context
 
@@ -54,20 +56,26 @@ To opt into sending this source context to Sentry, you have to enable the featur
 
 ## File I/O
 
-By default the Sentry SDK does not send the name or path of files when instrumenting File I/O.
+File I/O instrumentation collects file names and absolute paths by default. Set `dataCollection.filePaths=false` to omit them. File extensions and byte counts remain available when paths are disabled.
+
+## Device Context
 
-If you want to send file names and paths, set <PlatformLink to="/configuration/options/#send-default-pii">`sendDefaultPii=true`</PlatformLink>.
+The SDK automatically collects device and operating-system context, including the manufacturer, model, architecture, orientation, display details, boot time, timezone, memory size, and emulator status.
 
-## Device Information
+Set <PlatformLink to="/configuration/options/#collectAdditionalContext">`collectAdditionalContext=false`</PlatformLink> to reduce additional dynamic context such as battery level, available memory, storage state, and connectivity.
 
-By default the Sentry SDK does not send the name of the device (Android phone).
+## GraphQL Data
 
-If you want to send the device name, set <PlatformLink to="/configuration/options/#send-default-pii">`sendDefaultPii=true`</PlatformLink>.
+GraphQL document and variable collection default to `true`. Use `dataCollection.graphql.document` and `dataCollection.graphql.variables` to disable either category. Operation metadata used for tracing and grouping can still be collected when document or variable content is disabled.
 
 ## SQL Queries
 
 While SQL queries are sent to Sentry, neither the full SQL query (`UPDATE app_user SET password='supersecret' WHERE id=1;`), nor the values of its parameters will ever be sent. A parameterized version of the query (`UPDATE app_user SET password=? WHERE id=?;`) is sent instead.
 
+## Logs
+
+Log messages, parameters, and breadcrumb content may contain application data. Data Collection doesn't filter this content. Use `beforeBreadcrumb` for breadcrumbs, `beforeSend` for events, or `options.getLogs().setBeforeSend(...)` for Sentry Logs when you need application-specific filtering.
+
 ## Session Replay
 
 By default, our Session Replay SDK masks all text content, images, webviews, and user input. This helps ensure that no sensitive data is exposed. You can find <PlatformLink to="/session-replay/privacy/">more details in the Session Replay documentation</PlatformLink>.