From 29c775772349c1862acd1b80ef861766af1b241d Mon Sep 17 00:00:00 2001 From: Alexander Dinauer Date: Fri, 11 Sep 2026 08:29:46 +0200 Subject: [PATCH 1/8] docs(java): Document Data Collection controls Replace sendDefaultPii guidance with granular Data Collection options across Java and Android documentation. Document defaults, migration behavior, integration coverage, and onboarding configuration. Co-Authored-By: Claude --- .../android/configuration/options.mdx | 92 ++++++++++++++++- .../data-management/data-collected.mdx | 92 ++++++++++------- .../data-management/sensitive-data/index.mdx | 14 +-- .../enriching-events/identify-user/index.mdx | 5 +- docs/platforms/android/index.mdx | 39 +++++--- .../android/integrations/apollo3/index.mdx | 13 ++- .../android/integrations/apollo4/index.mdx | 19 ++-- .../integrations/ktor-client/index.mdx | 29 ++++-- .../android/integrations/okhttp/index.mdx | 14 ++- docs/platforms/android/manual-setup/index.mdx | 32 +++--- .../java/common/configuration/options.mdx | 98 ++++++++++++++++++- .../common/data-management/data-collected.mdx | 91 +++++++++-------- .../data-management/sensitive-data/index.mdx | 14 +-- .../enriching-events/identify-user/index.mdx | 3 +- .../java/common/integrations/graphql.mdx | 18 ++++ .../java/common/integrations/graphql22.mdx | 18 ++++ .../tracing/instrumentation/apollo3.mdx | 11 ++- .../tracing/instrumentation/apollo4.mdx | 11 ++- .../tracing/instrumentation/ktor-client.mdx | 22 ++++- .../common/tracing/instrumentation/okhttp.mdx | 11 ++- .../tracing/instrumentation/open-feign.mdx | 17 ++++ .../java/guides/spring-boot/record-user.mdx | 9 +- .../java/guides/spring/advanced-usage.mdx | 62 +----------- .../getting-started-config/java.jul.mdx | 11 ++- .../getting-started-config/java.log4j2.mdx | 60 ++++++------ .../getting-started-config/java.logback.mdx | 44 +++------ .../getting-started-config/java.mdx | 19 ++-- .../getting-started-config/java.servlet.mdx | 23 +++-- .../java.spring-boot.mdx | 14 +-- .../getting-started-config/java.spring.mdx | 70 +++---------- .../opentelemetry/java.mdx | 6 +- 31 files changed, 615 insertions(+), 366 deletions(-) diff --git a/docs/platforms/android/configuration/options.mdx b/docs/platforms/android/configuration/options.mdx index 3ab6d49cb0fb4..aa8666f54db56 100644 --- a/docs/platforms/android/configuration/options.mdx +++ b/docs/platforms/android/configuration/options.mdx @@ -98,15 +98,101 @@ AndroidManifest.xml key: `io.sentry.additional-context`. -If this flag is enabled, certain personally identifiable information (PII) is added by active integrations. +Controls legacy collection of personally identifiable information (PII) by active integrations. 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. + +File paths aren't a Data Collection category. They continue to use `sendDefaultPii`. -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. +Read our [frequently asked questions about mobile data privacy](/security-legal-pii/security/mobile-privacy/) when completing Apple App Store or Google Play privacy details. -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/). + + + + +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`. + +Passing an empty `DataCollection` or configuring any field enables Data Collection. Omitted fields then use these defaults: + +| 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` | 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. | +| `databaseQueryData` | `boolean` | `true` | Allows supported integrations to collect associated query data. Sanitized statements and structural metadata aren't affected. | + +Configure Data Collection in `AndroidManifest.xml`: + +```xml {filename:AndroidManifest.xml} + + + + + + + +``` + +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.database-query-data` + +The `cookies`, HTTP header, and URL query parameter fields support `off`, `deny_list`, and `allow_list`. Matching terms are comma-separated. Matching is partial and case-insensitive, and the built-in sensitive list always applies. Filtered values are replaced with `"[Filtered]"`. + +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.urlQueryParams = KeyValueCollectionBehavior.off() + options.dataCollection.httpHeaders.request = + KeyValueCollectionBehavior.allowList("content-type", "x-request-id") +} +``` + +### Migrating From `sendDefaultPii` + +Data Collection preserves existing applications until you opt in: + +| Configuration | Result | +| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | +| No Data Collection fields | Existing `sendDefaultPii` behavior is preserved. | +| An empty `DataCollection` | 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`, an empty `DataCollection` opts into the new filtered defaults. Keep `sendDefaultPii=true` only if you also need file paths. + +Data Collection doesn't control Session Replay. Configure Replay's URL, header, and body collection separately in the Session Replay options. diff --git a/docs/platforms/android/data-management/data-collected.mdx b/docs/platforms/android/data-management/data-collected.mdx index 1bc7e3e689792..ec30d069f1a23 100644 --- a/docs/platforms/android/data-management/data-collected.mdx +++ b/docs/platforms/android/data-management/data-collected.mdx @@ -1,73 +1,99 @@ --- title: Data Collected -description: "See what data is collected by the Sentry Android SDK." +description: "See what data is collected by the Sentry Android SDK and how to control automatic collection." 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 Sentry Android SDK collects crashes, errors, traces, logs, and device context through the integrations you enable. Review this page before release so the SDK's automatic collection matches your mobile privacy disclosures and requirements. -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 Data Collection to control supported categories. The first Data Collection field you configure activates the documented Data Collection defaults for every omitted field. If you don't configure Data Collection, the SDK preserves the existing `sendDefaultPii` behavior. -Many of the categories listed here require you to enable the sendDefaultPii option. +Data Collection controls only data added automatically by SDK integrations. Data you add through scopes, event processors, `beforeSend`, or other APIs is still sent. + + + +Read our [mobile data privacy FAQ](/security-legal-pii/security/mobile-privacy/) when completing Apple App Store or Google Play privacy details. + + + +## Filtering Key-Value Data + +Cookies, HTTP headers, and URL query parameters support three collection modes: + +- `OFF` collects nothing in the category. +- `DENY_LIST` collects values except those matching the built-in sensitive list or your additional terms. +- `ALLOW_LIST` sends plaintext values only for keys matching your terms. The built-in sensitive list still applies. + +Matching is partial and case-insensitive. Sensitive values are replaced with `"[Filtered]"` rather than removed. See the Data Collection option for manifest and manual-initialization examples. + +## User Information and IP Addresses + +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. + +`dataCollection.userInfo` controls other user information populated automatically, including the `"{{auto}}"` IP address value that asks Sentry to infer the address from the connection. The Data Collection default is `true`. Set it to `false` to prevent automatic IP enrichment. + +User information you set explicitly with `Sentry.setUser()` or on a scope isn't removed. ## 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. +`dataCollection.httpHeaders.request` and `dataCollection.httpHeaders.response` control request and response headers independently. With the default `DENY_LIST` mode, supported HTTP client integrations collect available headers and replace sensitive values with `"[Filtered]"`. + +This applies to captured errors from OkHttp, Ktor Client, and Apollo 3 and 4. Cookie headers are filtered separately through `dataCollection.cookies`. -To start sending HTTP headers, set `sendDefaultPii=true`. 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. +Session Replay network details use separate options. See Session Replay Configuration. ## Cookies -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. +`dataCollection.cookies` controls cookies collected by supported HTTP client integrations. The default `DENY_LIST` mode collects cookie names while filtering values with the built-in sensitive list. -If you want to send cookies, set `sendDefaultPii=true`. +Set the mode to `OFF` to omit cookies, or use `ALLOW_LIST` to expose only selected non-sensitive values. -## Information About Logged-in User +## Request URLs and Query Parameters -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 base request URL is sent without its query string or fragment where an HTTP client integration records a request. URL fragments may be sent in a separate field and aren't controlled by Data Collection, so avoid placing sensitive values in fragments or scrub them with `beforeSend`. -To start sending logged-in user information, set `sendDefaultPii=true`. +`dataCollection.urlQueryParams` controls query parameters for instrumented outgoing URLs. The default `DENY_LIST` mode keeps parameter names and non-sensitive values while replacing sensitive values with `"[Filtered]"`. Set the mode to `OFF` to omit the query string. -## Users' IP Addresses +## HTTP Bodies -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. +`dataCollection.httpBodies` can control incoming and outgoing request and response bodies, but an integration collects a body only when that body is available. -To enable sending the user's IP address, set `sendDefaultPii=true`. +On Android, Apollo 3 and 4 can collect outgoing GraphQL request bodies and incoming GraphQL response bodies. OkHttp and Ktor Client error events collect body sizes, not body content. Use an empty set to disable all body collection. -## Request URL +Session Replay's network body collection remains separate. See Session Replay Configuration. -The full request URL of outgoing and incoming HTTP requests is **always sent to Sentry**. Depending on your application, this could contain PII data. +## GraphQL Data -## Request Query String +`dataCollection.graphql.document` controls GraphQL documents, and `dataCollection.graphql.variables` controls variables. Both default to `true` when Data Collection is active. -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. +These fields apply to Apollo 3 and 4. Operation metadata used for tracing and grouping can still be collected when document or variable content is disabled. -## Request and Response Bodies +## Database Query Data -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/). +The SDK sends SQL statements in parameterized form. For example, it sends `UPDATE app_user SET password=? WHERE id=?` instead of literal values. -## Source Context +`dataCollection.databaseQueryData` controls additional query data where an integration supports it. Sanitized statements and structural database metadata remain available when this option is `false`. -Our build tool plugins for Gradle and Maven can upload your source code to Sentry, which can then used to show the lines of code where an error happened in the Issue Details page. +## Device Context -To opt into sending this source context to Sentry, you have to enable the feature as described in the Source Context documentation. +The SDK automatically collects device and operating-system context. This can include battery level, memory use, storage state, orientation, boot time, emulator status, and connectivity. -## File I/O +Static device context, such as the manufacturer and hardware model, is collected independently of Data Collection. Set `collectAdditionalContext=false` to reduce additional dynamic context. -By default the Sentry SDK does not send the name or path of files when instrumenting File I/O. - -If you want to send file names and paths, set `sendDefaultPii=true`. +## Source Context -## Device Information +The Sentry Gradle plugin can upload source code to Sentry so Issue Details can show the lines around an error. This is opt-in and configured separately. See Source Context. -By default the Sentry SDK does not send the name of the device (Android phone). +## File I/O -If you want to send the device name, set `sendDefaultPii=true`. +File names and paths aren't part of Data Collection yet. File I/O instrumentation omits them unless `sendDefaultPii=true`. -## SQL Queries +## Logs -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. +Data Collection doesn't filter log messages or breadcrumb content. Avoid placing sensitive values in logs, and use `beforeBreadcrumb` or `beforeSend` 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 more details in the Session Replay documentation. +Session Replay has separate privacy defaults and configuration. By default, Replay masks text, images, webviews, and user input. Data Collection doesn't change Replay's URL, header, body, masking, or screenshot settings. + +See Session Replay Privacy for details. diff --git a/docs/platforms/android/data-management/sensitive-data/index.mdx b/docs/platforms/android/data-management/sensitive-data/index.mdx index 5adffa96c8b96..f3afe68c43d3c 100644 --- a/docs/platforms/android/data-management/sensitive-data/index.mdx +++ b/docs/platforms/android/data-management/sensitive-data/index.mdx @@ -33,11 +33,11 @@ If you are using Sentry in your mobile app, read our [frequently asked questions ## Personally Identifiable Information (PII) -Our newer SDKs do not purposefully send PII to stay on the safe side. This behavior is controlled by an option called [`send-default-pii`](../../configuration/options/#sendDefaultPii). +Use [`dataCollection`](../../configuration/options/#dataCollection) to control user information, cookies, HTTP headers and bodies, URL query parameters, GraphQL content, and database query data added automatically by integrations. Its built-in filters replace sensitive key-value data with `"[Filtered]"` before the event leaves the device. -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). +Data Collection doesn't remove information you add explicitly. Use the hooks below for application-specific scrubbing, and review [Data Collected](../data-collected/) for categories that remain outside 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/). +The legacy [`sendDefaultPii`](../../configuration/options/#sendDefaultPii) option remains supported. If no Data Collection field is configured, the SDK preserves its existing behavior. Session Replay also keeps its separate privacy configuration. ## Scrubbing Data @@ -50,11 +50,11 @@ SDKs provide a hook, which is invoked Sensitive data may appear in the following areas: - Stack-locals → Some SDKs (Python, PHP and Node) will pick up variable values within the stack trace. These can be scrubbed, or this behavior can be disabled altogether if necessary. -- Breadcrumbs → Some SDKs (JavaScript and the Java logging integrations, for example) will pick up previously executed log statements. **Do not log PII** if using this feature and including log statements as breadcrumbs in the event. Some backend SDKs will also record database queries, which may need to be scrubbed. Most SDKs will add the HTTP query string and fragment as a data attribute to the breadcrumb, which may need to be scrubbed. -- User context → Automated behavior is controlled via . -- HTTP context → Query strings may be picked up in some frameworks as part of the HTTP request context. +- Breadcrumbs → Android integrations can capture previous log statements. **Do not log PII** when including logs as breadcrumbs. Data Collection filters query parameters on supported HTTP breadcrumbs, but application-defined breadcrumb data may still need custom scrubbing. +- User context → Automatic enrichment is controlled by [`dataCollection.userInfo`](../../configuration/options/#dataCollection). Explicitly set user data isn't removed. +- HTTP context → Use Data Collection to control supported cookies, headers, query parameters, and bodies. URL fragments aren't controlled by Data Collection. - Transaction Names → In certain situations, transaction names might contain sensitive data. For example, a browser's pageload transaction might have a raw URL like `/users/1234/details` as its name (where `1234` is a user id, which may be considered PII). In most cases, our SDKs can parameterize URLs and routes successfully, that is, turn `/users/1234/details` into `/users/:userid/details`. However, depending on the framework, your routing configuration, race conditions, and a few other factors, the SDKs might not be able to completely parameterize all of your URLs. -- HTTP Spans → Most SDKs will include the HTTP query string and fragment as a data attribute, which means the HTTP span may need to be scrubbed. +- HTTP spans → Data Collection filters query parameters added by supported integrations. Review URL fragments and span data you add yourself. For more details and data filtering instructions, see Filtering Events. diff --git a/docs/platforms/android/enriching-events/identify-user/index.mdx b/docs/platforms/android/enriching-events/identify-user/index.mdx index 832665e025e30..ae68705cfffce 100644 --- a/docs/platforms/android/enriching-events/identify-user/index.mdx +++ b/docs/platforms/android/enriching-events/identify-user/index.mdx @@ -28,11 +28,10 @@ An alternative, or addition, to the username. Sentry is aware of email addresses ### `ip_address` The user's IP address. If the user is unauthenticated, Sentry uses the IP address as a unique identifier for the user. -Serverside SDKs that instrument incoming requests will attempt to pull the IP address from the HTTP request data (`request.env.REMOTE_ADDR` field in JSON), if available. That might require set to `true` in the SDK options. -If the user's `ip_address` is set to `"{{auto}}"`, Sentry will infer the IP address from the connection between your app and Sentry's server. +Set [`dataCollection.userInfo`](../../configuration/options/#dataCollection) to `true` to let the SDK add `"{{auto}}"` automatically. Sentry then infers the IP address from the connection between the device and Sentry's server. If Data Collection isn't configured, the SDK preserves the legacy behavior. -If the field is omitted, the default value is `null`. However, due to backwards compatibility concerns, certain platforms (in particular JavaScript) have a different default value for `"{{auto}}"`. SDKs and other clients should not rely on this behavior and should set IP addresses or `"{{auto}}"` explicitly. +If you set user data explicitly, Data Collection doesn't remove it. To opt out of storing users' IP addresses in your event data, users with project admin permissions (Org Owner, Org Manager, Team Admin, or Org Admin) can go to your project settings, click on "Security & Privacy", and enable "Prevent Storing of IP Addresses". Alternatively, use Sentry's [server-side data](/security-legal-pii/scrubbing/) scrubbing to remove `$user.ip_address`. Adding such a rule ultimately overrules any other logic. diff --git a/docs/platforms/android/index.mdx b/docs/platforms/android/index.mdx index 76b8cb4fa49aa..e9b9711c6f49b 100644 --- a/docs/platforms/android/index.mdx +++ b/docs/platforms/android/index.mdx @@ -30,18 +30,24 @@ Select which Sentry features you'd like to install in addition to Error Monitori - On Android 15 (API level 35) and higher, profiling uses the Android ProfilingManager to capture Perfetto traces. On older devices, the SDK automatically falls back to the legacy profiler. + On Android 15 (API level 35) and higher, profiling uses the Android{" "} + + ProfilingManager + {" "} + to capture Perfetto traces. On older + devices, the SDK automatically falls back to the{" "} + legacy profiler. @@ -112,13 +118,13 @@ The wizard will prompt you to log in to Sentry. It'll then automatically do the Configuration is done via the application `AndroidManifest.xml`. Here's an example config which should get you started: - ```xml {filename:AndroidManifest.xml} - - + + + @@ -183,7 +189,14 @@ class MyActivity : AppCompatActivity() { ## Next Steps - Explore [practical guides](/get-started/guides/) on what to monitor, log, track, and investigate after setup -- Learn about the features of Sentry's Android SDK -- Learn how to enhance stack traces of your Sentry errors -- Enrich events with additional context to make debugging simpler -- Diagnose ANRs with profiling and automatic fingerprinting +- + Learn about the features of Sentry's Android SDK + +- + Learn how to enhance stack traces of your Sentry errors + +- + Enrich events with additional context to make debugging simpler + +- Diagnose ANRs + with profiling and automatic fingerprinting diff --git a/docs/platforms/android/integrations/apollo3/index.mdx b/docs/platforms/android/integrations/apollo3/index.mdx index f349f0f22fd9d..faa2c8dae3bdb 100644 --- a/docs/platforms/android/integrations/apollo3/index.mdx +++ b/docs/platforms/android/integrations/apollo3/index.mdx @@ -158,17 +158,20 @@ val apollo = ApolloClient.builder() .build() ``` -By default, error events won't contain `Headers` or `Cookies`, but you can change this behavior by setting the `sendDefaultPii` option to `true`: +Use Data Collection to control headers, cookies, URL query parameters, request and response bodies, GraphQL documents, and GraphQL variables. For example, disable GraphQL variables and all HTTP body collection: ```xml {filename:AndroidManifest.xml} - + + ``` -Error events will contain the raw bodies of GraphQL requests and responses, which may include sensitive data. To avoid this, parameterize your queries using the [variables](https://spec.graphql.org/October2021/#sec-Language.Variables) field. [Relay](/product/relay) will then run [PII Data Scrubbing](/product/relay/#pii-data-scrubbing), automatically transforming values into `[Filtered]`. - -Alternatively, you can customize the event and scrub the data yourself. +Configuring any field activates the Data Collection defaults for omitted fields. GraphQL request and response bodies may contain sensitive data, so review both `graphql` and `httpBodies` before enabling them. You can also customize the event and scrub application-specific data yourself. ### Customize or Drop the Error Event diff --git a/docs/platforms/android/integrations/apollo4/index.mdx b/docs/platforms/android/integrations/apollo4/index.mdx index f18825566d98a..b32fccaf59fdc 100644 --- a/docs/platforms/android/integrations/apollo4/index.mdx +++ b/docs/platforms/android/integrations/apollo4/index.mdx @@ -154,23 +154,20 @@ val apollo = ApolloClient.builder() .build() ``` -By default, error events won't contain `Headers` or `Cookies`, but you can change this behavior by setting the `sendDefaultPii` option to `true`: - -```kotlin -Sentry.init { options -> - options.isSendDefaultPii = true -} -``` +Use Data Collection to control headers, cookies, URL query parameters, request and response bodies, GraphQL documents, and GraphQL variables. For example, disable GraphQL variables and all HTTP body collection: ```xml {filename:AndroidManifest.xml} - + + ``` -Error events will contain the raw bodies of GraphQL requests and responses, which may include sensitive data. To avoid this, parameterize your queries using the [variables](https://spec.graphql.org/October2021/#sec-Language.Variables) field. [Relay](/product/relay) will then run [PII Data Scrubbing](/product/relay/#pii-data-scrubbing), automatically transforming values into `[Filtered]`. - -Alternatively, you can customize the event and scrub the data yourself. +Configuring any field activates the Data Collection defaults for omitted fields. GraphQL request and response bodies may contain sensitive data, so review both `graphql` and `httpBodies` before enabling them. You can also customize the event and scrub application-specific data yourself. ### Customize or Drop the Error Event diff --git a/docs/platforms/android/integrations/ktor-client/index.mdx b/docs/platforms/android/integrations/ktor-client/index.mdx index 8278b5ff0b4b7..86a865883f260 100644 --- a/docs/platforms/android/integrations/ktor-client/index.mdx +++ b/docs/platforms/android/integrations/ktor-client/index.mdx @@ -12,6 +12,7 @@ The `sentry-ktor-client` library provides [Ktor Client](https://ktor.io/) suppor On this page, we get you up and running with Sentry's Ktor Client Integration. The integration supports: + - Adding breadcrumbs for each HTTP request. - Capturing spans for each HTTP Request, with support for distributed tracing. The span will be created as a child of the current span bound to the scope (if any). - Capturing certain request failures as errors in Sentry. @@ -19,9 +20,14 @@ The integration supports: The Sentry Ktor Client integration supports Ktor Client version `3.x`. - If you're using Ktor Client with OKHttp as the engine, and you're already using the [Sentry OkHttp integration](/platforms/android/integrations/okhttp/), - either with manual or automatic installation (via the Sentry Android Gradle Plugin), you should avoid using this integration, otherwise the SDK will produce duplicate data, instrumenting each HTTP request twice. - Use the [Sentry OkHttp integration](/platforms/android/integrations/okhttp/) instead, as it provides more detailed information about HTTP request. + If you're using Ktor Client with OKHttp as the engine, and you're already + using the [Sentry OkHttp + integration](/platforms/android/integrations/okhttp/), either with manual or + automatic installation (via the Sentry Android Gradle Plugin), you should + avoid using this integration, otherwise the SDK will produce duplicate data, + instrumenting each HTTP request twice. Use the [Sentry OkHttp + integration](/platforms/android/integrations/okhttp/) instead, as it provides + more detailed information about HTTP request. ## Install @@ -37,7 +43,6 @@ implementation 'io.sentry:sentry-ktor-client:{{@inject packages.version('sentry. Create the Ktor HTTP Client with your preferred engine, and install the Sentry Ktor Client Plugin: - ```kotlin import io.ktor.client.* import io.ktor.client.engine.android.* @@ -76,7 +81,7 @@ suspend fun run(url: String): String? { - Learn more about manually capturing an error or message in our Usage documentation. +Learn more about manually capturing an error or message in our Usage documentation. @@ -143,14 +148,24 @@ val ktorClient = HttpClient(Android) { } ``` -By default, error events won't contain any PII data, such as `Headers` and `Cookies`, but you can change this behavior by setting the `sendDefaultPii` option to `true`: +Use Data Collection to control the request and response headers, cookies, and URL query parameters attached to error events. For example, allow selected request headers and omit cookies: ```xml {filename:AndroidManifest.xml} - + + + ``` +Configuring any field activates the Data Collection defaults for omitted fields. Sensitive values still use the built-in filtering rules. + Those events are searchable and you can set alerts on them if you use the `http.url` and `http.status_code` properties. Learn more in our full [Searchable Properties](/concepts/search/searchable-properties/) documentation. ### Customize or Drop the Error Event diff --git a/docs/platforms/android/integrations/okhttp/index.mdx b/docs/platforms/android/integrations/okhttp/index.mdx index 56402df144e64..003a1c2187e9d 100644 --- a/docs/platforms/android/integrations/okhttp/index.mdx +++ b/docs/platforms/android/integrations/okhttp/index.mdx @@ -387,14 +387,24 @@ private final OkHttpClient client = new OkHttpClient.Builder() .build(); ``` -By default, error events won't contain any PII data, such as `Headers` and `Cookies`, but you can change this behavior by setting the `sendDefaultPii` option to `true`: +Use Data Collection to control the request and response headers, cookies, and URL query parameters attached to error events. For example, allow selected request headers and omit cookies: ```xml {filename:AndroidManifest.xml} - + + + ``` +Configuring any field activates the Data Collection defaults for omitted fields. Sensitive values still use the built-in filtering rules. + Those events are searchable and you can set alerts on them if you use the `http.url` and `http.status_code` properties. Learn more in our full [Searchable Properties](/concepts/search/searchable-properties/) documentation. ### Customize or Drop the Error Event diff --git a/docs/platforms/android/manual-setup/index.mdx b/docs/platforms/android/manual-setup/index.mdx index 6de84aa4c2bd9..41887b09e97da 100644 --- a/docs/platforms/android/manual-setup/index.mdx +++ b/docs/platforms/android/manual-setup/index.mdx @@ -52,14 +52,14 @@ If you're using multiple Sentry dependencies, you can add a [bill of materials]( Configuration is done via the application `AndroidManifest.xml`. Here's an example config which should get you started: - ```xml {filename:AndroidManifest.xml} - - + + + @@ -129,11 +129,12 @@ The SDK can catch errors and crashes only after you've initialized it. For that Configuration options will be loaded from the manifest so that you don't need to have the static properties in your code. In the `init` method, you can provide a callback that will modify the configuration and also register new options. ```kotlin -import io.sentry.ScreenshotStrategyType; -import io.sentry.SentryLevel; -import io.sentry.ProfileLifecycle; -import io.sentry.android.core.SentryAndroid; -import android.app.Application; +import io.sentry.DataCollection +import io.sentry.ScreenshotStrategyType +import io.sentry.SentryLevel +import io.sentry.ProfileLifecycle +import io.sentry.android.core.SentryAndroid +import android.app.Application import io.sentry.SentryOptions class MyApplication : Application() { @@ -143,8 +144,11 @@ class MyApplication : Application() { SentryAndroid.init(this) { options -> // Required: set your sentry.io project identifier (DSN) options.dsn = "___PUBLIC_DSN___" - // Add data like request headers, user ip address and device name, see https://docs.sentry.io/platforms/android/data-management/data-collected/ for more info - options.isSendDefaultPii = true + // Use Data Collection defaults but don't collect automatic user information. + // https://docs.sentry.io/platforms/android/data-management/data-collected/ + options.dataCollection = DataCollection().apply { + userInfo = false + } // enable automatic traces for user interactions (clicks, swipes, scrolls) options.isEnableUserInteractionTracing = true // enable screenshot for crashes @@ -187,6 +191,7 @@ class MyApplication : Application() { ``` ```java +import io.sentry.DataCollection; import io.sentry.ScreenshotStrategyType; import io.sentry.SentryLevel; import io.sentry.ProfileLifecycle; @@ -200,8 +205,11 @@ public class MyApplication extends Application { SentryAndroid.init(this, options -> { // Required: set your sentry.io project identifier (DSN) options.setDsn("___PUBLIC_DSN___"); - // Add data like request headers, user ip address and device name, see https://docs.sentry.io/platforms/android/data-management/data-collected/ for more info - options.setSendDefaultPii(true); + // Use Data Collection defaults but don't collect automatic user information. + // https://docs.sentry.io/platforms/android/data-management/data-collected/ + DataCollection dataCollection = new DataCollection(); + dataCollection.setUserInfo(false); + options.setDataCollection(dataCollection); // enable automatic traces for user interactions (clicks, swipes, scrolls) options.setEnableUserInteractionTracing(true); // enable screenshot for crashes diff --git a/docs/platforms/java/common/configuration/options.mdx b/docs/platforms/java/common/configuration/options.mdx index 8b1e769fb5cf0..55f36c3779e19 100644 --- a/docs/platforms/java/common/configuration/options.mdx +++ b/docs/platforms/java/common/configuration/options.mdx @@ -102,11 +102,100 @@ Note that enabling this option may increase the payload size of events sent to S -If this flag is enabled, certain personally identifiable information (PII) is added by active integrations. By default, no such data is sent. +Controls legacy collection of personally identifiable information (PII) by active integrations. Use [`dataCollection`](#dataCollection) for granular control over automatically collected data. -This option is turned off by default. +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. + +File paths and unencoded Logback messages aren't Data Collection categories. OpenTelemetry-derived HTTP header attributes also aren't controlled by Data Collection yet. These paths continue to use `sendDefaultPii`. + + + + + +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`. + +Passing an empty `DataCollection` or configuring any field enables Data Collection. Omitted fields then use these defaults: + +| 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` | 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. | +| `databaseQueryData` | `boolean` | `true` | Allows supported integrations to collect associated query data, such as bound parameters, write payloads, and results. Sanitized statements and structural metadata aren't affected. | + +Configure only the fields that differ from these defaults: + +```java +import io.sentry.KeyValueCollectionBehavior; +import io.sentry.Sentry; + +Sentry.init( + options -> { + options.getDataCollection().setUserInfo(false); + options + .getDataCollection() + .setUrlQueryParams(KeyValueCollectionBehavior.off()); + options + .getDataCollection() + .getHttpHeaders() + .setRequest( + KeyValueCollectionBehavior.allowList( + "content-type", "x-request-id")); + }); +``` + +The `cookies`, `httpHeaders.request`, `httpHeaders.response`, and `urlQueryParams` fields support three modes: + +- `OFF`: Don't collect the category. +- `DENY_LIST`: Collect values except those matching the built-in sensitive list or additional configured terms. +- `ALLOW_LIST`: Include plaintext values only when their keys match configured terms. The built-in sensitive list still applies. + +Matching is partial and case-insensitive. The built-in list includes terms such as `auth`, `token`, `secret`, `password`, `key`, `session`, and `identity`. Filtered values are replaced with `"[Filtered]"`. Custom deny-list terms extend the built-in list rather than replacing it. + +You can also configure Data Collection through external properties: + +```properties {filename:sentry.properties} +data-collection.user-info=false +data-collection.http-bodies=incoming_request,outgoing_request +data-collection.cookies.mode=deny_list +data-collection.cookies.terms=session-id,tracking-id +data-collection.http-headers.request.mode=allow_list +data-collection.http-headers.request.terms=content-type,x-request-id +data-collection.http-headers.response.mode=off +data-collection.url-query-params.mode=off +data-collection.graphql.document=false +data-collection.graphql.variables=false +data-collection.database-query-data=false +``` + +Environment variables use the same names in uppercase with the `SENTRY_` prefix, for example, `SENTRY_DATA_COLLECTION_USER_INFO` and `SENTRY_DATA_COLLECTION_HTTP_BODIES`. + +Spring Boot uses the `sentry.` prefix and kebab-case enum values: + +```properties {filename:application.properties} +sentry.data-collection.user-info=false +sentry.data-collection.http-bodies=incoming-request,outgoing-request +sentry.data-collection.http-headers.request.mode=allow-list +sentry.data-collection.http-headers.request.terms=content-type,x-request-id +sentry.data-collection.url-query-params.mode=off +``` + +### Migrating From `sendDefaultPii` + +Data Collection preserves existing applications until you opt in: + +| Configuration | Result | +| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | +| No Data Collection fields | Existing `sendDefaultPii` behavior is preserved. | +| An empty `DataCollection` | 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 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/). +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`, an empty `DataCollection` opts into the new filtered defaults. Keep `sendDefaultPii=true` only if you also need file paths, unencoded Logback messages, or the legacy OpenTelemetry header behavior. @@ -149,8 +238,7 @@ This parameter controls whether integrations should capture HTTP request bodies. - `medium`: Medium and small requests will be captured (typically 10KB). - `always`: The SDK will always capture the request body as long as Sentry can make sense of it. -For request bodies to be captured, the flag must also be enabled. -Please consult the documentation for to evaluate whether you would want to enable it, making sure to manually remove the data you don't want to send using our features for managing Sensitive Data. +When Data Collection is configured, [`dataCollection.httpBodies`](#dataCollection) controls supported request and response bodies instead. `maxRequestBodySize` remains the size limit for integrations that use it. diff --git a/docs/platforms/java/common/data-management/data-collected.mdx b/docs/platforms/java/common/data-management/data-collected.mdx index 7c5a1d3190d60..165d9ec5aeebe 100644 --- a/docs/platforms/java/common/data-management/data-collected.mdx +++ b/docs/platforms/java/common/data-management/data-collected.mdx @@ -1,81 +1,94 @@ --- title: Data Collected -description: "See what data is collected by the Sentry Java SDK." +description: "See what data is collected by the Sentry Java SDK and how to control automatic collection." 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 Sentry Java SDK collects errors, traces, logs, and debugging context through the integrations you enable. Review this page before production rollout so the SDK's automatic collection matches your privacy requirements. -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 Java SDK collects. +Use Data Collection to control supported categories. The first Data Collection field you configure activates the documented Data Collection defaults for every omitted field. If you don't configure Data Collection, the SDK preserves the existing `sendDefaultPii` behavior. -For many of the categories listed here it is required to enable the sendDefaultPii option. +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 +## Filtering Key-Value Data + +Cookies, HTTP headers, and URL query parameters support three collection modes: -### Outgoing Requests +- `OFF` collects nothing in the category. +- `DENY_LIST` collects values except those matching the built-in sensitive list or your additional terms. +- `ALLOW_LIST` sends plaintext values only for keys matching your terms. The built-in sensitive list still applies. -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. +Matching is partial and case-insensitive. Sensitive values are replaced with `"[Filtered]"` rather than removed. See the Data Collection option for configuration examples. -To send all HTTP headers, set `sendDefaultPii=true`. +## User Information and IP Addresses -### Incoming Requests +`dataCollection.userInfo` controls user information populated automatically by integrations. This includes Spring Security usernames and the `"{{auto}}"` IP address value, which asks Sentry to infer the address from the connection. -By default, the Sentry SDK sends headers for incoming HTTP requests to Sentry but filters out any headers that contain sensitive data. (See the [list of headers](https://github.com/getsentry/sentry-java/blob/main/sentry/src/main/java/io/sentry/util/HttpUtils.java#L21-L34) that are filtered). +The Data Collection default is `true`. Set it to `false` to prevent automatic user enrichment. User information you set explicitly with `Sentry.setUser()` or on a scope isn't removed. + +## HTTP Headers -To send all HTTP headers, set `sendDefaultPii=true`. +`dataCollection.httpHeaders.request` and `dataCollection.httpHeaders.response` control request and response headers independently. With the default `DENY_LIST` mode, integrations collect available headers and replace sensitive values with `"[Filtered]"`. + +Header availability depends on the integration. Servlet and Spring integrations can collect incoming request headers, while OkHttp, Ktor Client, and Apollo can collect request and response headers for captured HTTP client errors. + +Cookie headers are filtered separately through `dataCollection.cookies`. ## Cookies -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. +`dataCollection.cookies` controls cookies collected by supported Spring and HTTP client integrations. The default `DENY_LIST` mode collects cookie names while filtering values with the built-in sensitive list. -If you want to send cookies, set `sendDefaultPii=true`. +Set the mode to `OFF` to omit cookies, or use `ALLOW_LIST` to expose only selected non-sensitive values. -## Information About Logged-in User +## Request URLs and Query Parameters -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 base request URL is sent without its query string or fragment where an integration records an HTTP request. URL fragments may be sent in a separate field and aren't controlled by Data Collection, so avoid placing sensitive values in fragments or scrub them with `beforeSend`. -To start sending logged-in user information, set `sendDefaultPii=true`. +`dataCollection.urlQueryParams` controls query parameters for instrumented incoming and outgoing URLs, including HTTP spans and breadcrumbs created by integrations such as Spring and OpenFeign. The default `DENY_LIST` mode keeps parameter names and non-sensitive values while replacing sensitive values with `"[Filtered]"`. Set the mode to `OFF` to omit the query string. -## Users' IP Addresses +## HTTP Bodies -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. +`dataCollection.httpBodies` controls four body directions independently: -To enable sending the user's IP address, set `sendDefaultPii=true`. +- `INCOMING_REQUEST` +- `OUTGOING_REQUEST` +- `INCOMING_RESPONSE` +- `OUTGOING_RESPONSE` -## Request URL +All four are enabled by the Data Collection defaults, but an integration collects a body only when that body is available. For example, Spring can collect supported incoming request bodies, GraphQL server instrumentation can collect request and response data, and Apollo 3 and 4 can collect GraphQL client request and response bodies. OkHttp and Ktor Client error events collect body sizes, not body content. -The full request URL of outgoing and incoming HTTP requests is **always sent to Sentry**. Depending on your application, this could contain PII data. +For Spring request bodies, `maxRequestBodySize` also limits collection and defaults to `NONE`. Spring collects only supported JSON and form bodies within that size limit. -## Request Query String +Use an empty set to disable all body collection. -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. +## GraphQL Data -## Request Body +`dataCollection.graphql.document` controls GraphQL documents, and `dataCollection.graphql.variables` controls variables. Both default to `true` when Data Collection is active. -The request body of incoming HTTP requests can be sent to Sentry. Whether it's sent or not, depends on the type and size of request body as described below: +These fields apply to supported GraphQL server instrumentation and Apollo 3 and 4. Operation metadata used for tracing and grouping can still be collected when document or variable content is disabled. -- **The type of the request body:** - - JSON and form bodies are sent -- **The size of the request body:** There's a maxRequestBodySize option that's set to `NONE` by default. This means by default no request body is sent to Sentry. +## Database Query Data -## Source Context +The SDK sends SQL statements in parameterized form. For example, it sends `UPDATE app_user SET password=? WHERE id=?` instead of literal values. -Our build tool plugins for Gradle and Maven can upload your source code to Sentry, which can then used to show the lines of code where an error happened in the Issue Details page. +`dataCollection.databaseQueryData` controls additional query data, such as bound parameters, write payloads, or results, where an integration supports it. Sanitized statements and structural database metadata remain available when this option is `false`. -To opt into sending this source context to Sentry, you have to enable the feature as described in the Source Context documentation. +## OpenTelemetry Attributes -## File I/O +Data Collection can't distinguish attributes added automatically by OpenTelemetry instrumentation from attributes your application adds explicitly. Configure the OpenTelemetry instrumentation that produces those attributes, or scrub them with `beforeSendTransaction`. -By default the Sentry SDK does not send the name or path of files when instrumenting File I/O. +Sentry's legacy extraction of OpenTelemetry HTTP header attributes continues to use `sendDefaultPii` and isn't controlled by Data Collection yet. -If you want to send file names and paths, set `sendDefaultPii=true`. +## Source Context -## Log Messages +The Gradle and Maven plugins can upload source code to Sentry so Issue Details can show the lines around an error. This is opt-in and configured separately. See Source Context. -By default the Sentry SDK does not send unencoded Logback messages and parameters if an encoder has been set. It will however send the encoded message. +## File I/O + +File names and paths aren't part of Data Collection yet. File I/O instrumentation omits them unless `sendDefaultPii=true`. -If you want to send the unencoded message and parameters, set `sendDefaultPii=true`. +## Log Messages -## SQL Queries +Data Collection doesn't filter log messages or breadcrumb content. Avoid placing sensitive values in logs, and use `beforeBreadcrumb` or `beforeSend` when you need application-specific filtering. -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. +When a Logback encoder is configured, unencoded messages and parameters continue to use `sendDefaultPii`. The encoded message is still sent. diff --git a/docs/platforms/java/common/data-management/sensitive-data/index.mdx b/docs/platforms/java/common/data-management/sensitive-data/index.mdx index dd1f3937c4be5..8c48c3e1e0a28 100644 --- a/docs/platforms/java/common/data-management/sensitive-data/index.mdx +++ b/docs/platforms/java/common/data-management/sensitive-data/index.mdx @@ -31,11 +31,11 @@ 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/#sendDefaultPii). +Use [`dataCollection`](../../configuration/options/#dataCollection) to control user information, cookies, HTTP headers and bodies, URL query parameters, GraphQL content, and database query data added automatically by integrations. Its built-in filters replace sensitive key-value data with `"[Filtered]"` before the event leaves your application. -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). +Data Collection doesn't remove information you add explicitly. Use the hooks below for application-specific scrubbing, and review [Data Collected](../data-collected/) for categories that remain outside 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/). +The legacy [`sendDefaultPii`](../../configuration/options/#sendDefaultPii) option remains supported. If no Data Collection field is configured, the SDK preserves its existing behavior. ## Scrubbing Data @@ -48,11 +48,11 @@ The SDK provides a hook, which is invo Sensitive data may appear in the following areas: - Stack-locals → Some SDKs (Python, PHP and Node) will pick up variable values within the stack trace. These can be scrubbed, or this behavior can be disabled altogether if necessary. -- Breadcrumbs → Some SDKs (JavaScript and the Java logging integrations, for example) will pick up previously executed log statements. **Do not log PII** if using this feature and including log statements as breadcrumbs in the event. Some backend SDKs will also record database queries, which may need to be scrubbed. Most SDKs will add the HTTP query string and fragment as a data attribute to the breadcrumb, which may need to be scrubbed. -- User context → Automated behavior is controlled via . -- HTTP context → Query strings may be picked up in some frameworks as part of the HTTP request context. +- Breadcrumbs → Java logging integrations can capture previous log statements. **Do not log PII** when including logs as breadcrumbs. Data Collection filters query parameters on supported HTTP breadcrumbs, but application-defined breadcrumb data may still need custom scrubbing. +- User context → Automatic enrichment is controlled by [`dataCollection.userInfo`](../../configuration/options/#dataCollection). Explicitly set user data isn't removed. +- HTTP context → Use Data Collection to control supported cookies, headers, query parameters, and bodies. URL fragments aren't controlled by Data Collection. - Transaction Names → In certain situations, transaction names might contain sensitive data. For example, a browser's pageload transaction might have a raw URL like `/users/1234/details` as its name (where `1234` is a user id, which may be considered PII). In most cases, our SDKs can parameterize URLs and routes successfully, that is, turn `/users/1234/details` into `/users/:userid/details`. However, depending on the framework, your routing configuration, race conditions, and a few other factors, the SDKs might not be able to completely parameterize all of your URLs. -- HTTP Spans → Most SDKs will include the HTTP query string and fragment as a data attribute, which means the HTTP span may need to be scrubbed. +- HTTP spans → Data Collection filters query parameters added by supported integrations. Review URL fragments and span data you add yourself. For more details and data filtering instructions, see Filtering Events. diff --git a/docs/platforms/java/common/enriching-events/identify-user/index.mdx b/docs/platforms/java/common/enriching-events/identify-user/index.mdx index f3fc8162a988b..0ae76790d0559 100644 --- a/docs/platforms/java/common/enriching-events/identify-user/index.mdx +++ b/docs/platforms/java/common/enriching-events/identify-user/index.mdx @@ -22,7 +22,8 @@ An alternative, or addition, to the username. Sentry is aware of email addresses ### `ip_address` The user's IP address. If the user is unauthenticated, Sentry uses the IP address as a unique identifier for the user. -The SDK will attempt to pull the IP address from the HTTP request data on incoming requests (`request.env.REMOTE_ADDR` field in JSON), if available. That requires set to `true` in the SDK options. + +Set [`dataCollection.userInfo`](../../configuration/options/#dataCollection) to `true` to allow supported integrations to populate IP addresses automatically. If Data Collection isn't configured, the SDK preserves the legacy behavior. If the user's `ip_address` is set to `"{{auto}}"`, Sentry will infer the IP address from the connection between your app and Sentry's server. If the field is omitted, the default value is `null`. diff --git a/docs/platforms/java/common/integrations/graphql.mdx b/docs/platforms/java/common/integrations/graphql.mdx index 5e1d2c092326d..b9ae57ef78977 100644 --- a/docs/platforms/java/common/integrations/graphql.mdx +++ b/docs/platforms/java/common/integrations/graphql.mdx @@ -114,6 +114,24 @@ The `SentryDataFetcherExceptionHandler` has been deprecated. Please upgrade to ` +## Control GraphQL Content + +GraphQL documents, variables, and supported request and response bodies can contain sensitive application data. Use Data Collection to control them independently: + +```java +import io.sentry.Sentry; +import java.util.Collections; + +Sentry.init( + options -> { + options.getDataCollection().getGraphql().setDocument(false); + options.getDataCollection().getGraphql().setVariables(false); + options.getDataCollection().setHttpBodies(Collections.emptySet()); + }); +``` + +Configuring any field activates the Data Collection defaults for omitted fields. Operation metadata used for tracing and grouping can still be collected when document or variable content is disabled. + ## Capture Tracing Information To be able to capture transactions, you have to first set up tracing. diff --git a/docs/platforms/java/common/integrations/graphql22.mdx b/docs/platforms/java/common/integrations/graphql22.mdx index 447ad0314441b..787ebec0cf035 100644 --- a/docs/platforms/java/common/integrations/graphql22.mdx +++ b/docs/platforms/java/common/integrations/graphql22.mdx @@ -114,6 +114,24 @@ The `SentryDataFetcherExceptionHandler` has been deprecated. Please upgrade to ` +## Control GraphQL Content + +GraphQL documents, variables, and supported request and response bodies can contain sensitive application data. Use Data Collection to control them independently: + +```java +import io.sentry.Sentry; +import java.util.Collections; + +Sentry.init( + options -> { + options.getDataCollection().getGraphql().setDocument(false); + options.getDataCollection().getGraphql().setVariables(false); + options.getDataCollection().setHttpBodies(Collections.emptySet()); + }); +``` + +Configuring any field activates the Data Collection defaults for omitted fields. Operation metadata used for tracing and grouping can still be collected when document or variable content is disabled. + ## Capture Tracing Information To be able to capture transactions, you have to first set up tracing. diff --git a/docs/platforms/java/common/tracing/instrumentation/apollo3.mdx b/docs/platforms/java/common/tracing/instrumentation/apollo3.mdx index 6140ed32eace5..f9dbaf9dd4ad4 100644 --- a/docs/platforms/java/common/tracing/instrumentation/apollo3.mdx +++ b/docs/platforms/java/common/tracing/instrumentation/apollo3.mdx @@ -216,17 +216,18 @@ val apollo = ApolloClient.builder() .build() ``` -By default, error events won't contain `Headers` or `Cookies`, but you can change this behavior by setting the `sendDefaultPii` option to `true`: +Use Data Collection to control headers, cookies, URL query parameters, request and response bodies, GraphQL documents, and GraphQL variables. For example, disable GraphQL variables and all HTTP body collection: ```kotlin +import io.sentry.Sentry + Sentry.init { options -> - options.isSendDefaultPii = true + options.dataCollection.graphql.variables = false + options.dataCollection.httpBodies = emptySet() } ``` -Error events will contain the raw bodies of GraphQL requests and responses, which may include sensitive data. To avoid this, parameterize your queries using the [variables](https://spec.graphql.org/October2021/#sec-Language.Variables) field. [Relay](/product/relay) will then run [PII Data Scrubbing](/product/relay/#pii-data-scrubbing), automatically transforming values into `[Filtered]`. - -Alternatively, you can customize the event and scrub the data yourself. +Configuring either field activates the Data Collection defaults for omitted fields. GraphQL request and response bodies may contain sensitive data, so review both `graphql` and `httpBodies` before enabling them. You can also customize the event and scrub application-specific data yourself. ### Customize or Drop the Error Event diff --git a/docs/platforms/java/common/tracing/instrumentation/apollo4.mdx b/docs/platforms/java/common/tracing/instrumentation/apollo4.mdx index f379c4588da1f..2bee804c01cdc 100644 --- a/docs/platforms/java/common/tracing/instrumentation/apollo4.mdx +++ b/docs/platforms/java/common/tracing/instrumentation/apollo4.mdx @@ -193,17 +193,18 @@ val apollo = ApolloClient.builder() .build() ``` -By default, error events won't contain `Headers` or `Cookies`, but you can change this behavior by setting the `sendDefaultPii` option to `true`: +Use Data Collection to control headers, cookies, URL query parameters, request and response bodies, GraphQL documents, and GraphQL variables. For example, disable GraphQL variables and all HTTP body collection: ```kotlin +import io.sentry.Sentry + Sentry.init { options -> - options.isSendDefaultPii = true + options.dataCollection.graphql.variables = false + options.dataCollection.httpBodies = emptySet() } ``` -Error events will contain the raw bodies of GraphQL requests and responses, which may include sensitive data. To avoid this, parameterize your queries using the [variables](https://spec.graphql.org/October2021/#sec-Language.Variables) field. [Relay](/product/relay) will then run [PII Data Scrubbing](/product/relay/#pii-data-scrubbing), automatically transforming values into `[Filtered]`. - -Alternatively, you can customize the event and scrub the data yourself. +Configuring either field activates the Data Collection defaults for omitted fields. GraphQL request and response bodies may contain sensitive data, so review both `graphql` and `httpBodies` before enabling them. You can also customize the event and scrub application-specific data yourself. ### Customize or Drop the Error Event diff --git a/docs/platforms/java/common/tracing/instrumentation/ktor-client.mdx b/docs/platforms/java/common/tracing/instrumentation/ktor-client.mdx index fc08b57cac482..ebd8f59bce6e7 100644 --- a/docs/platforms/java/common/tracing/instrumentation/ktor-client.mdx +++ b/docs/platforms/java/common/tracing/instrumentation/ktor-client.mdx @@ -19,6 +19,7 @@ The `sentry-ktor-client` library provides [Ktor Client](https://ktor.io/) suppor On this page, we get you up and running with Sentry's Ktor Client Integration. The integration supports: + - Adding breadcrumbs for each HTTP request. - Capturing spans for each HTTP Request, with support for distributed tracing. The span will be created as a child of the current span bound to the scope (if any). - Capturing certain request failures as errors in Sentry. @@ -26,9 +27,13 @@ The integration supports: The Sentry Ktor Client integration supports Ktor Client version `3.x`. - If you're using Ktor Client with OKHttp as the engine, and you're already using the [Sentry OkHttp integration](/platforms/java/tracing/instrumentation/okhttp/), - you should avoid using this integration, otherwise the SDK will produce duplicate data, instrumenting each HTTP request twice. - Use the [Sentry OkHttp integration](/platforms/java/tracing/instrumentation/okhttp/) instead, as it provides more detailed information about HTTP request. + If you're using Ktor Client with OKHttp as the engine, and you're already + using the [Sentry OkHttp + integration](/platforms/java/tracing/instrumentation/okhttp/), you should + avoid using this integration, otherwise the SDK will produce duplicate data, + instrumenting each HTTP request twice. Use the [Sentry OkHttp + integration](/platforms/java/tracing/instrumentation/okhttp/) instead, as it + provides more detailed information about HTTP request. ## Install @@ -142,14 +147,21 @@ val ktorClient = HttpClient(Java) { } ``` -By default, error events won't contain any PII data, such as `Headers` and `Cookies`, but you can change this behavior by setting the `sendDefaultPii` option to `true`: +Use Data Collection to control the request and response headers, cookies, and URL query parameters attached to error events. For example, allow selected request headers and omit cookies: ```kotlin +import io.sentry.KeyValueCollectionBehavior +import io.sentry.Sentry + Sentry.init { options -> - options.isSendDefaultPii = true + options.dataCollection.httpHeaders.request = + KeyValueCollectionBehavior.allowList("content-type", "x-request-id") + options.dataCollection.cookies = KeyValueCollectionBehavior.off() } ``` +Configuring either field activates the Data Collection defaults for omitted fields. Sensitive values still use the built-in filtering rules. + Those events are searchable and you can set alerts on them if you use the `http.url` and `http.status_code` properties. Learn more in our full [Searchable Properties](/concepts/search/searchable-properties/) documentation. ### Customize or Drop the Error Event diff --git a/docs/platforms/java/common/tracing/instrumentation/okhttp.mdx b/docs/platforms/java/common/tracing/instrumentation/okhttp.mdx index a0b582b457a09..aea6f2b70f048 100644 --- a/docs/platforms/java/common/tracing/instrumentation/okhttp.mdx +++ b/docs/platforms/java/common/tracing/instrumentation/okhttp.mdx @@ -259,14 +259,21 @@ private val client = OkHttpClient.Builder() .build() ``` -By default, error events won't contain any PII data, such as `Headers` and `Cookies`, but you can change this behavior by setting the `sendDefaultPii` option to `true`: +Use Data Collection to control the request and response headers, cookies, and URL query parameters attached to error events. For example, allow selected request headers and omit cookies: ```kotlin +import io.sentry.KeyValueCollectionBehavior +import io.sentry.Sentry + Sentry.init { options -> - options.isSendDefaultPii = true + options.dataCollection.httpHeaders.request = + KeyValueCollectionBehavior.allowList("content-type", "x-request-id") + options.dataCollection.cookies = KeyValueCollectionBehavior.off() } ``` +Configuring either field activates the Data Collection defaults for omitted fields. Sensitive values still use the built-in filtering rules. + HTTP client errors sent to Sentry are searchable and you can set alerts on them if you use the `http.url` and `http.status_code` properties. Learn more in our full [Searchable Properties](/concepts/search/searchable-properties/) documentation. ### Customize or Drop the Error Event diff --git a/docs/platforms/java/common/tracing/instrumentation/open-feign.mdx b/docs/platforms/java/common/tracing/instrumentation/open-feign.mdx index 447d2e0f8735a..546daab159270 100644 --- a/docs/platforms/java/common/tracing/instrumentation/open-feign.mdx +++ b/docs/platforms/java/common/tracing/instrumentation/open-feign.mdx @@ -61,6 +61,23 @@ val api = Feign.builder() .target(YourApi::class.java, "https://your-api-host/") ``` +## Control URL Query Parameters + +OpenFeign adds URLs to HTTP spans and breadcrumbs. Use `dataCollection.urlQueryParams` to filter or omit their query parameters: + +```java +import io.sentry.KeyValueCollectionBehavior; +import io.sentry.Sentry; + +Sentry.init( + options -> + options + .getDataCollection() + .setUrlQueryParams(KeyValueCollectionBehavior.off())); +``` + +Configuring this field activates the Data Collection defaults for omitted fields. The base URL is still sent when query parameter collection is disabled. + ## Modify or Drop Spans Spans created around HTTP requests can be modified or dropped using `SentryFeignClient.BeforeSpanCallback` passed to `SentryCapability`: diff --git a/docs/platforms/java/guides/spring-boot/record-user.mdx b/docs/platforms/java/guides/spring-boot/record-user.mdx index bd59516f8ac09..71c584c9aee7e 100644 --- a/docs/platforms/java/guides/spring-boot/record-user.mdx +++ b/docs/platforms/java/guides/spring-boot/record-user.mdx @@ -13,17 +13,20 @@ Record user information from an HTTP request or by registering a Spring bean for ## Recording User Information From HTTP Request -To record the user's IP address and `Principal#name` as the username, set the personal information flag to `true`. +To record the user's IP address and `Principal#name` as the username, enable automatic user information through Data Collection: ```properties {tabTitle:application.properties} -sentry.send-default-pii=true +sentry.data-collection.user-info=true ``` ```yaml {tabTitle:application.yml} sentry: - send-default-pii: true + data-collection: + user-info: true ``` +Configuring this field activates the Data Collection defaults for omitted fields. + ## Recording Custom User Information To record custom user information, you can register a bean that implements `SentryUserProvider` interface. diff --git a/docs/platforms/java/guides/spring/advanced-usage.mdx b/docs/platforms/java/guides/spring/advanced-usage.mdx index 4dfb686404225..9b0117afbae0f 100644 --- a/docs/platforms/java/guides/spring/advanced-usage.mdx +++ b/docs/platforms/java/guides/spring/advanced-usage.mdx @@ -9,67 +9,15 @@ Record user information from an HTTP request or by registering a Spring bean for ## Recording User Information From HTTP Request -To record the user's IP address and `Principal#name` as the username so you can then view in [trace view](/concepts/key-terms/tracing/trace-view/): +To record the user's IP address and `Principal#name` as the username so you can view it in [Trace View](/concepts/key-terms/tracing/trace-view/): -1. Set the personal information flag on `@EnableSentry` to `true`. +1. Enable automatic user information in `sentry.properties`: - -```Java {tabTitle:Java (Spring 5)} {mdExpandTabs} -import org.springframework.context.annotation.Configuration; -import io.sentry.spring.EnableSentry; - -@EnableSentry(dsn = "___PUBLIC_DSN___", sendDefaultPii = true) -@Configuration -class SentryConfiguration { -} -``` - -```Java {tabTitle:Java (Spring 6)} -import org.springframework.context.annotation.Configuration; -import io.sentry.spring.jakarta.EnableSentry; - -@EnableSentry(dsn = "___PUBLIC_DSN___", sendDefaultPii = true) -@Configuration -class SentryConfiguration { -} -``` - -```Java {tabTitle:Java (Spring 7)} -import org.springframework.context.annotation.Configuration; -import io.sentry.spring7.EnableSentry; - -@EnableSentry(dsn = "___PUBLIC_DSN___", sendDefaultPii = true) -@Configuration -class SentryConfiguration { -} +```properties {filename:sentry.properties} +data-collection.user-info=true ``` -```kotlin {tabTitle:Kotlin (Spring 5)} -import org.springframework.context.annotation.Configuration -import io.sentry.spring.EnableSentry - -@EnableSentry(dsn = "...", sendDefaultPii = true) -@Configuration -class SentryConfiguration -``` - -```kotlin {tabTitle:Kotlin (Spring 6)} -import org.springframework.context.annotation.Configuration -import io.sentry.spring.jakarta.EnableSentry - -@EnableSentry(dsn = "...", sendDefaultPii = true) -@Configuration -class SentryConfiguration -``` - -```kotlin {tabTitle:Kotlin (Spring 7)} -import org.springframework.context.annotation.Configuration -import io.sentry.spring7.EnableSentry - -@EnableSentry(dsn = "...", sendDefaultPii = true) -@Configuration -class SentryConfiguration -``` +Configuring this field activates the Data Collection defaults for omitted fields. The `@EnableSentry` annotation enables external configuration automatically. 2. Register the servlet filter bean `SentryUserFilter`: diff --git a/platform-includes/getting-started-config/java.jul.mdx b/platform-includes/getting-started-config/java.jul.mdx index 40bdc1d56e638..cb390832ebf06 100644 --- a/platform-includes/getting-started-config/java.jul.mdx +++ b/platform-includes/getting-started-config/java.jul.mdx @@ -32,17 +32,17 @@ java -Djava.util.logging.config.file=/path/to/app.properties MyClass Sentry reads the DSN from the system property `sentry.dsn`, environment variable `SENTRY_DSN` or the `dsn` property in `sentry.properties` file. [See the configuration page](/platforms/java/configuration/) for more details on external configuration. - ```properties {tabTitle:sentry.properties} dsn=___PUBLIC_DSN___ -# Add data like request headers and IP for users, -# see https://docs.sentry.io/platforms/java/guides/jul/data-management/data-collected/ for more info -send-default-pii=true +# Use Data Collection defaults but don't collect automatic user information. +# https://docs.sentry.io/platforms/java/guides/jul/data-management/data-collected/ +data-collection.user-info=false # Enable logs logs.enabled=true ``` + ### Minimum Log Level @@ -51,8 +51,11 @@ Two log levels are used to configure this integration: 1. Configure the lowest level required for a log message to become an event (`minimumEventLevel`) sent to Sentry. 2. Configure the lowest level a message has to be to become a breadcrumb (`minimumBreadcrumbLevel`). + + 3. Configure the lowest level a message has to be to be sent as Sentry Log (`minimumLevel`). + diff --git a/platform-includes/getting-started-config/java.log4j2.mdx b/platform-includes/getting-started-config/java.log4j2.mdx index ad63de687fce7..6aa6f0947968c 100644 --- a/platform-includes/getting-started-config/java.log4j2.mdx +++ b/platform-includes/getting-started-config/java.log4j2.mdx @@ -13,19 +13,19 @@ The `ConsoleAppender` is provided only as an example of a non-Sentry appender se - - - - - - - - - - - - - + + + + + + + + + + + + + ``` @@ -36,19 +36,19 @@ The `ConsoleAppender` is provided only as an example of a non-Sentry appender se - - - - - - + + + + + + - - - - - - + + + + + + ``` @@ -68,13 +68,14 @@ Note that **you need to configure your DSN** (client key) only if you wish to in If the DSN is not present in the `log4j2.xml` configuration, Sentry will attempt to read it from the system property `sentry.dsn`, environment variable `SENTRY_DSN` or the `dsn` property in `sentry.properties` file. [See the configuration page](/platforms/java/configuration/) for more details on external configuration. ```properties {tabTitle:sentry.properties} -# Add data like request headers and IP for users, -# see https://docs.sentry.io/platforms/java/guides/log4j2/data-management/data-collected/ for more info -send-default-pii=true +# Use Data Collection defaults but don't collect automatic user information. +# https://docs.sentry.io/platforms/java/guides/log4j2/data-management/data-collected/ +data-collection.user-info=false // ___PRODUCT_OPTION_START___ logs logs.enabled=true // ___PRODUCT_OPTION_END___ logs ``` + ### Minimum Log Level @@ -83,8 +84,11 @@ Two log levels are used to configure this integration, as illustrated below in t 1. Configure the lowest level required for a log message to become an event (`minimumEventLevel`) sent to Sentry. 2. Configure the lowest level a message has to be to become a breadcrumb (`minimumBreadcrumbLevel`) + + 3. Configure the lowest level a message has to be to be sent as Sentry Log (`minimumLevel`). + diff --git a/platform-includes/getting-started-config/java.logback.mdx b/platform-includes/getting-started-config/java.logback.mdx index 1fdfe1b3dc621..51446fd1298e6 100644 --- a/platform-includes/getting-started-config/java.logback.mdx +++ b/platform-includes/getting-started-config/java.logback.mdx @@ -21,10 +21,6 @@ The `ConsoleAppender` is provided only as an example of a non-Sentry appender se - - ___PUBLIC_DSN___ - - true // ___PRODUCT_OPTION_START___ logs true @@ -33,12 +29,12 @@ The `ConsoleAppender` is provided only as an example of a non-Sentry appender se - + + ``` @@ -56,34 +52,30 @@ The `ConsoleAppender` is provided only as an example of a non-Sentry appender se - + + ``` -### DSN Configuration - -Note that **you need to configure your DSN** (client key). +### SDK Configuration +Configure the SDK using a `sentry.properties` file: -```xml - - - - ___PUBLIC_DSN___ - - true - - +```properties {filename:sentry.properties} +dsn=___PUBLIC_DSN___ +# Use Data Collection defaults but don't collect automatic user information. +# https://docs.sentry.io/platforms/java/guides/logback/data-management/data-collected/ +data-collection.user-info=false ``` -If the DSN is not present in the `logback.xml` configuration, Sentry will attempt to read it from the system property `sentry.dsn`, environment variable `SENTRY_DSN` or the `dsn` property in `sentry.properties` file. [See the configuration page](/platforms/java/configuration/) for more details on external configuration. +You can also provide the DSN through the `sentry.dsn` system property or the `SENTRY_DSN` environment variable. [See the configuration page](/platforms/java/configuration/) for more details on external configuration. + ### Minimum Log Level @@ -92,8 +84,11 @@ Two log levels are used to configure this integration: 1. Configure the lowest level required for a log message to become an event (`minimumEventLevel`) sent to Sentry. 2. Configure the lowest level a message has to be to become a breadcrumb (`minimumBreadcrumbLevel`). + + 3. Configure the lowest level a message has to be to be sent as Sentry Log (`minimumLevel`). + @@ -104,16 +99,9 @@ Setting `minimumEventLevel` or `minimumBreadcrumbLevel` in `logback.xml` only af Breadcrumbs are kept in memory (by default the last 100 records) and are sent with events. For example, by default, if you log 100 entries with `logger.info` or `logger.warn`, no event is sent to Sentry. If you then log with `logger.error`, an event is sent to Sentry which includes those 100 `info` or `warn` messages. For this to work, `SentryAppender` needs to receive **all** log entries to decide what to keep as breadcrumb or sent as event. Set the `SentryAppender` log level configuration to a value lower than what is set for the `minimumBreadcrumbLevel` and `minimumEventLevel` so that `SentryAppender` receives these log messages. - ```xml - - - ___PUBLIC_DSN___ - - true - WARN diff --git a/platform-includes/getting-started-config/java.mdx b/platform-includes/getting-started-config/java.mdx index 3ab8bbd95cbed..aa608a199f157 100644 --- a/platform-includes/getting-started-config/java.mdx +++ b/platform-includes/getting-started-config/java.mdx @@ -2,14 +2,17 @@ Configuration should happen as early as possible in your application's lifecycle. ```java {tabTitle: Java} +import io.sentry.DataCollection; import io.sentry.Sentry; Sentry.init(options -> { options.setDsn("___PUBLIC_DSN___"); - // Add data like request headers and IP for users, - // see https://docs.sentry.io/platforms/java/data-management/data-collected/ for more info - options.setSendDefaultPii(true); + // Use Data Collection defaults but don't collect automatic user information. + // https://docs.sentry.io/platforms/java/data-management/data-collected/ + DataCollection dataCollection = new DataCollection(); + dataCollection.setUserInfo(false); + options.setDataCollection(dataCollection); // ___PRODUCT_OPTION_START___ performance // Set traces_sample_rate to 1.0 to capture 100% @@ -32,14 +35,17 @@ Sentry.init(options -> { ``` ```kotlin {tabTitle: Kotlin} +import io.sentry.DataCollection import io.sentry.Sentry Sentry.init { options -> options.dsn = "___PUBLIC_DSN___" - // Add data like request headers and IP for users, - // see https://docs.sentry.io/platforms/java/data-management/data-collected/ for more info - options.isSendDefaultPii = true + // Use Data Collection defaults but don't collect automatic user information. + // https://docs.sentry.io/platforms/java/data-management/data-collected/ + options.dataCollection = DataCollection().apply { + userInfo = false + } // ___PRODUCT_OPTION_START___ performance // Set traces_sample_rate to 1.0 to capture 100% @@ -60,6 +66,7 @@ Sentry.init { options -> // ___PRODUCT_OPTION_END___ logs } ``` + diff --git a/platform-includes/getting-started-config/java.servlet.mdx b/platform-includes/getting-started-config/java.servlet.mdx index d881ae1dcc8e2..b0461d45d2061 100644 --- a/platform-includes/getting-started-config/java.servlet.mdx +++ b/platform-includes/getting-started-config/java.servlet.mdx @@ -3,10 +3,10 @@ Configuration should happen as early as possible in your application's lifecycle The following example configures a `SentryInitializer` servlet container initializer that initializes Sentry on application startup. - ```java package sentry.sample; +import io.sentry.DataCollection; import io.sentry.Sentry; import javax.servlet.ServletContainerInitializer; import javax.servlet.ServletContext; @@ -19,9 +19,11 @@ public final class SentryInitializer implements ServletContainerInitializer { Sentry.init(options -> { options.setDsn("___PUBLIC_DSN___"); - // Add data like request headers and IP for users, - // see https://docs.sentry.io/platforms/java/guides/servlet/data-management/data-collected/ for more info - options.setSendDefaultPii(true); + // Use Data Collection defaults but don't collect automatic user information. + // https://docs.sentry.io/platforms/java/guides/servlet/data-management/data-collected/ + DataCollection dataCollection = new DataCollection(); + dataCollection.setUserInfo(false); + options.setDataCollection(dataCollection); // ___PRODUCT_OPTION_START___ performance // Set traces_sample_rate to 1.0 to capture 100% @@ -48,6 +50,7 @@ public final class SentryInitializer implements ServletContainerInitializer { ```kotlin package sentry.sample; +import io.sentry.DataCollection import javax.servlet.ServletContainerInitializer import javax.servlet.ServletContext import javax.servlet.ServletException @@ -58,10 +61,12 @@ class SentryInitializer : ServletContainerInitializer { Sentry.init { options -> options.dsn = "___PUBLIC_DSN___" - // Add data like request headers and IP for users, - // see https://docs.sentry.io/platforms/java/guides/servlet/data-management/data-collected/ for more info - options.isSendDefaultPii = true - // ___PRODUCT_OPTION_START___ performance + // Use Data Collection defaults but don't collect automatic user information. + // https://docs.sentry.io/platforms/java/guides/servlet/data-management/data-collected/ + options.dataCollection = DataCollection().apply { + userInfo = false + } + // ___PRODUCT_OPTION_START___ performance // Set traces_sample_rate to 1.0 to capture 100% // of transactions for tracing. @@ -83,6 +88,7 @@ class SentryInitializer : ServletContainerInitializer { } } ``` + @@ -96,4 +102,5 @@ Create a file in `src/main/resources/META-INF/services` named `javax.servlet.Ser ```properties sentry.sample.SentryInitializer ``` + diff --git a/platform-includes/getting-started-config/java.spring-boot.mdx b/platform-includes/getting-started-config/java.spring-boot.mdx index bacb025bc1908..7489ca3bda04a 100644 --- a/platform-includes/getting-started-config/java.spring-boot.mdx +++ b/platform-includes/getting-started-config/java.spring-boot.mdx @@ -2,13 +2,12 @@ Sentry's Spring Boot integration auto-configures `sentry.in-app-packages` proper Provide a `sentry.dsn` property using either `application.properties` or `application.yml`: - ```properties {filename:application.properties} sentry.dsn=___PUBLIC_DSN___ -# Add data like request headers and IP for users, -# see https://docs.sentry.io/platforms/java/guides/spring-boot/data-management/data-collected/ for more info -sentry.send-default-pii=true +# Use Data Collection defaults but don't collect automatic user information. +# https://docs.sentry.io/platforms/java/guides/spring-boot/data-management/data-collected/ +sentry.data-collection.user-info=false # ___PRODUCT_OPTION_START___ performance # Set traces_sample_rate to 1.0 to capture 100% @@ -33,9 +32,10 @@ sentry.logs.enabled=true sentry: dsn: ___PUBLIC_DSN___ - # Add data like request headers and IP for users, - # see https://docs.sentry.io/platforms/java/guides/spring-boot/data-management/data-collected/ for more info - send-default-pii: true + # Use Data Collection defaults but don't collect automatic user information. + # https://docs.sentry.io/platforms/java/guides/spring-boot/data-management/data-collected/ + data-collection: + user-info: false # ___PRODUCT_OPTION_START___ performance # Set traces_sample_rate to 1.0 to capture 100% diff --git a/platform-includes/getting-started-config/java.spring.mdx b/platform-includes/getting-started-config/java.spring.mdx index 0e2ef7fd72251..5dc84d7af5621 100644 --- a/platform-includes/getting-started-config/java.spring.mdx +++ b/platform-includes/getting-started-config/java.spring.mdx @@ -2,17 +2,11 @@ Configuration should happen as early as possible in your application's lifecycle The `sentry-spring`, `sentry-spring-jakarta`, and `sentry-spring-7` libraries provide an `@EnableSentry` annotation that registers all required Spring beans. `@EnableSentry` can be placed on any class annotated with [@Configuration](https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/context/annotation/Configuration.html) including the main entry class in Spring Boot applications annotated with [@SpringBootApplication](https://docs.spring.io/spring-boot/docs/current/api/org/springframework/boot/autoconfigure/SpringBootApplication.html). - ```java {tabTitle:Java (Spring 5)} {mdExpandTabs} import io.sentry.spring.EnableSentry; // NOTE: Replace the test DSN below with YOUR OWN DSN to see the events from this app in your Sentry // project/dashboard -@EnableSentry( - dsn = "___PUBLIC_DSN___", - // Add data like request headers and IP for users, - // see https://docs.sentry.io/platforms/java/guides/spring/data-management/data-collected/ for more info - sendDefaultPii = true -) +@EnableSentry(dsn = "___PUBLIC_DSN___") @Configuration class SentryConfiguration { } @@ -22,12 +16,7 @@ class SentryConfiguration { import io.sentry.spring.jakarta.EnableSentry; // NOTE: Replace the test DSN below with YOUR OWN DSN to see the events from this app in your Sentry // project/dashboard -@EnableSentry( - dsn = "___PUBLIC_DSN___", - // Add data like request headers and IP for users, - // see https://docs.sentry.io/platforms/java/guides/spring/data-management/data-collected/ for more info - sendDefaultPii = true -) +@EnableSentry(dsn = "___PUBLIC_DSN___") @Configuration class SentryConfiguration { } @@ -37,12 +26,7 @@ class SentryConfiguration { import io.sentry.spring7.EnableSentry; // NOTE: Replace the test DSN below with YOUR OWN DSN to see the events from this app in your Sentry // project/dashboard -@EnableSentry( - dsn = "___PUBLIC_DSN___", - // Add data like request headers and IP for users, - // see https://docs.sentry.io/platforms/java/guides/spring/data-management/data-collected/ for more info - sendDefaultPii = true -) +@EnableSentry(dsn = "___PUBLIC_DSN___") @Configuration class SentryConfiguration { } @@ -52,12 +36,7 @@ class SentryConfiguration { import io.sentry.spring.EnableSentry // NOTE: Replace the test DSN below with YOUR OWN DSN to see the events from this app in your Sentry // project/dashboard -@EnableSentry( - dsn = "___PUBLIC_DSN___", - // Add data like request headers and IP for users, - // see https://docs.sentry.io/platforms/java/guides/spring/data-management/data-collected/ for more info - sendDefaultPii = true -) +@EnableSentry(dsn = "___PUBLIC_DSN___") @Configuration class SentryConfiguration ``` @@ -66,12 +45,7 @@ class SentryConfiguration import io.sentry.spring.jakarta.EnableSentry // NOTE: Replace the test DSN below with YOUR OWN DSN to see the events from this app in your Sentry // project/dashboard -@EnableSentry( - dsn = "___PUBLIC_DSN___", - // Add data like request headers and IP for users, - // see https://docs.sentry.io/platforms/java/guides/spring/data-management/data-collected/ for more info - sendDefaultPii = true -) +@EnableSentry(dsn = "___PUBLIC_DSN___") @Configuration class SentryConfiguration ``` @@ -80,23 +54,24 @@ class SentryConfiguration import io.sentry.spring7.EnableSentry // NOTE: Replace the test DSN below with YOUR OWN DSN to see the events from this app in your Sentry // project/dashboard -@EnableSentry( - dsn = "___PUBLIC_DSN___", - // Add data like request headers and IP for users, - // see https://docs.sentry.io/platforms/java/guides/spring/data-management/data-collected/ for more info - sendDefaultPii = true -) +@EnableSentry(dsn = "___PUBLIC_DSN___") @Configuration class SentryConfiguration ``` +Configure Data Collection in `sentry.properties`. Setting any Data Collection field applies its defaults to omitted fields: + +```properties {filename:sentry.properties} +# Use Data Collection defaults but don't collect automatic user information. +data-collection.user-info=false +``` + The DSN can be also provided through the system property `sentry.dsn`, environment variable `SENTRY_DSN` or the `dsn` property in `sentry.properties` file. [See the configuration page](/platforms/java/configuration/) for more details on external configuration. Once this integration is configured you can _also_ use Sentry’s static API, [as shown on the usage page](usage/), to record breadcrumbs, set the current user, or manually send events, for example. By default, only unhandled exceptions are sent to Sentry. This behavior can be tuned through configuring the `exceptionResolverOrder` property. For example, setting it to `Ordered#HIGHEST_PRECEDENCE` ensures exceptions that have been handled by exception resolvers with higher order are sent to Sentry - including ones handled by `@ExceptionHandler` annotated methods. - ```java {tabTitle:Java (Spring 5)} {mdExpandTabs} import io.sentry.spring.EnableSentry; import org.springframework.core.Ordered; @@ -104,9 +79,6 @@ import org.springframework.core.Ordered; // project/dashboard @EnableSentry( dsn = "___PUBLIC_DSN___", - // Add data like request headers and IP for users, - // see https://docs.sentry.io/platforms/java/guides/spring/data-management/data-collected/ for more info - sendDefaultPii = true, exceptionResolverOrder = Ordered.LOWEST_PRECEDENCE ) class SentryConfiguration { @@ -120,9 +92,6 @@ import org.springframework.core.Ordered; // project/dashboard @EnableSentry( dsn = "___PUBLIC_DSN___", - // Add data like request headers and IP for users, - // see https://docs.sentry.io/platforms/java/guides/spring/data-management/data-collected/ for more info - sendDefaultPii = true, exceptionResolverOrder = Ordered.LOWEST_PRECEDENCE ) class SentryConfiguration { @@ -136,9 +105,6 @@ import org.springframework.core.Ordered; // project/dashboard @EnableSentry( dsn = "___PUBLIC_DSN___", - // Add data like request headers and IP for users, - // see https://docs.sentry.io/platforms/java/guides/spring/data-management/data-collected/ for more info - sendDefaultPii = true, exceptionResolverOrder = Ordered.LOWEST_PRECEDENCE ) class SentryConfiguration { @@ -152,9 +118,6 @@ import org.springframework.core.Ordered // project/dashboard @EnableSentry( dsn = "___PUBLIC_DSN___", - // Add data like request headers and IP for users, - // see https://docs.sentry.io/platforms/java/guides/spring/data-management/data-collected/ for more info - sendDefaultPii = true, exceptionResolverOrder = Ordered.LOWEST_PRECEDENCE ) class SentryConfiguration @@ -167,9 +130,6 @@ import org.springframework.core.Ordered // project/dashboard @EnableSentry( dsn = "___PUBLIC_DSN___", - // Add data like request headers and IP for users, - // see https://docs.sentry.io/platforms/java/guides/spring/data-management/data-collected/ for more info - sendDefaultPii = true, exceptionResolverOrder = Ordered.LOWEST_PRECEDENCE ) class SentryConfiguration @@ -182,15 +142,11 @@ import org.springframework.core.Ordered // project/dashboard @EnableSentry( dsn = "___PUBLIC_DSN___", - // Add data like request headers and IP for users, - // see https://docs.sentry.io/platforms/java/guides/spring/data-management/data-collected/ for more info - sendDefaultPii = true, exceptionResolverOrder = Ordered.LOWEST_PRECEDENCE ) class SentryConfiguration ``` - The SDK can be configured using a `sentry.properties` file: ```properties {filename:sentry.properties} diff --git a/platform-includes/getting-started-config/opentelemetry/java.mdx b/platform-includes/getting-started-config/opentelemetry/java.mdx index a3d2c434bc21a..f3899267484fc 100644 --- a/platform-includes/getting-started-config/opentelemetry/java.mdx +++ b/platform-includes/getting-started-config/opentelemetry/java.mdx @@ -4,9 +4,9 @@ The SDK can be configured using a `sentry.properties` file: ```properties {filename:sentry.properties} dsn=___PUBLIC_DSN___ -# Add data like request headers and IP for users, -# see https://docs.sentry.io/platforms/java/data-management/data-collected/ for more info -send-default-pii=true +# Use Data Collection defaults but don't collect automatic user information. +# https://docs.sentry.io/platforms/java/data-management/data-collected/ +data-collection.user-info=false # ___PRODUCT_OPTION_START___ performance traces-sample-rate=1.0 # ___PRODUCT_OPTION_END___ performance From 55b6e249e6a1896d88ab5bc6968e82e681986d09 Mon Sep 17 00:00:00 2001 From: Alexander Dinauer Date: Fri, 11 Sep 2026 10:36:01 +0200 Subject: [PATCH 2/8] docs(java): Fix Data Collection file path and Logback guidance Document the default-enabled filePaths control across Java and Android configuration surfaces. Correct migration and File I/O guidance so it matches the cumulative SDK implementation. Prefer Logback's scoped includeUnencodedMessage option instead of retaining the broad legacy PII switch. Co-Authored-By: Claude --- .../android/configuration/options.mdx | 32 +++++++++++-------- .../data-management/data-collected.mdx | 2 +- .../java/common/configuration/options.mdx | 10 ++++-- .../common/data-management/data-collected.mdx | 4 +-- .../logging-frameworks/logback.mdx | 4 +++ .../getting-started-config/java.logback.mdx | 17 ++++++++++ 6 files changed, 49 insertions(+), 20 deletions(-) diff --git a/docs/platforms/android/configuration/options.mdx b/docs/platforms/android/configuration/options.mdx index aa8666f54db56..14f94b5b55a80 100644 --- a/docs/platforms/android/configuration/options.mdx +++ b/docs/platforms/android/configuration/options.mdx @@ -102,8 +102,6 @@ Controls legacy collection of personally identifiable information (PII) by activ 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. -File paths aren't a Data Collection category. They continue to use `sendDefaultPii`. - Read our [frequently asked questions about mobile data privacy](/security-legal-pii/security/mobile-privacy/) when completing Apple App Store or Google Play privacy details. @@ -118,17 +116,18 @@ Controls which categories of data SDK integrations collect automatically. Data C Passing an empty `DataCollection` or configuring any field enables Data Collection. Omitted fields then use these defaults: -| 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` | 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. | -| `databaseQueryData` | `boolean` | `true` | Allows supported integrations to collect associated query data. Sanitized statements and structural metadata aren't affected. | +| 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` | 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. | +| `databaseQueryData` | `boolean` | `true` | Allows supported integrations to collect associated query data. Sanitized statements and structural metadata aren't affected. | +| `filePaths` | `boolean` | `true` | Allows File I/O instrumentation to collect file names and absolute paths. File extensions and byte counts remain available when disabled. | Configure Data Collection in `AndroidManifest.xml`: @@ -149,6 +148,9 @@ Configure Data Collection in `AndroidManifest.xml`: + ``` @@ -163,6 +165,7 @@ Supported manifest keys are: - `io.sentry.data-collection.graphql.document` - `io.sentry.data-collection.graphql.variables` - `io.sentry.data-collection.database-query-data` +- `io.sentry.data-collection.file-paths` The `cookies`, HTTP header, and URL query parameter fields support `off`, `deny_list`, and `allow_list`. Matching terms are comma-separated. Matching is partial and case-insensitive, and the built-in sensitive list always applies. Filtered values are replaced with `"[Filtered]"`. @@ -174,6 +177,7 @@ 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.allowList("content-type", "x-request-id") @@ -190,7 +194,7 @@ Data Collection preserves existing applications until you opt in: | An empty `DataCollection` | 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`, an empty `DataCollection` opts into the new filtered defaults. Keep `sendDefaultPii=true` only if you also need file paths. +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`, an empty `DataCollection` opts into the new filtered defaults. Data Collection doesn't control Session Replay. Configure Replay's URL, header, and body collection separately in the Session Replay options. diff --git a/docs/platforms/android/data-management/data-collected.mdx b/docs/platforms/android/data-management/data-collected.mdx index ec30d069f1a23..b164ed18f4e1e 100644 --- a/docs/platforms/android/data-management/data-collected.mdx +++ b/docs/platforms/android/data-management/data-collected.mdx @@ -86,7 +86,7 @@ The Sentry Gradle plugin can upload source code to Sentry so Issue Details can s ## File I/O -File names and paths aren't part of Data Collection yet. File I/O instrumentation omits them unless `sendDefaultPii=true`. +`dataCollection.filePaths` controls file names and absolute paths added by File I/O instrumentation. The Data Collection default is `true`. Set it to `false` to omit file names and the `file.path` span data; file extensions and byte counts remain available. ## Logs diff --git a/docs/platforms/java/common/configuration/options.mdx b/docs/platforms/java/common/configuration/options.mdx index 55f36c3779e19..b3fb82c79c78e 100644 --- a/docs/platforms/java/common/configuration/options.mdx +++ b/docs/platforms/java/common/configuration/options.mdx @@ -106,7 +106,7 @@ Controls legacy collection of personally identifiable information (PII) by activ 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. -File paths and unencoded Logback messages aren't Data Collection categories. OpenTelemetry-derived HTTP header attributes also aren't controlled by Data Collection yet. These paths continue to use `sendDefaultPii`. +Unencoded Logback messages aren't a Data Collection category. To include original message templates and parameters when an encoder is configured, use the Logback appender's `includeUnencodedMessage` option. The legacy `sendDefaultPii` behavior remains supported for compatibility. OpenTelemetry-derived HTTP header attributes also aren't controlled by Data Collection yet and continue to use `sendDefaultPii`. @@ -127,6 +127,7 @@ Passing an empty `DataCollection` or configuring any field enables Data Collecti | `graphql.document` | `boolean` | `true` | Collects GraphQL documents. | | `graphql.variables` | `boolean` | `true` | Collects GraphQL variables. | | `databaseQueryData` | `boolean` | `true` | Allows supported integrations to collect associated query data, such as bound parameters, write payloads, and results. Sanitized statements and structural metadata aren't affected. | +| `filePaths` | `boolean` | `true` | Allows File I/O instrumentation to collect file names and absolute paths. File extensions and byte counts remain available when disabled. | Configure only the fields that differ from these defaults: @@ -137,6 +138,7 @@ import io.sentry.Sentry; Sentry.init( options -> { options.getDataCollection().setUserInfo(false); + options.getDataCollection().setFilePaths(false); options .getDataCollection() .setUrlQueryParams(KeyValueCollectionBehavior.off()); @@ -171,9 +173,10 @@ data-collection.url-query-params.mode=off data-collection.graphql.document=false data-collection.graphql.variables=false data-collection.database-query-data=false +data-collection.file-paths=false ``` -Environment variables use the same names in uppercase with the `SENTRY_` prefix, for example, `SENTRY_DATA_COLLECTION_USER_INFO` and `SENTRY_DATA_COLLECTION_HTTP_BODIES`. +Environment variables use the same names in uppercase with the `SENTRY_` prefix, for example, `SENTRY_DATA_COLLECTION_USER_INFO`, `SENTRY_DATA_COLLECTION_HTTP_BODIES`, and `SENTRY_DATA_COLLECTION_FILE_PATHS`. Spring Boot uses the `sentry.` prefix and kebab-case enum values: @@ -183,6 +186,7 @@ sentry.data-collection.http-bodies=incoming-request,outgoing-request sentry.data-collection.http-headers.request.mode=allow-list sentry.data-collection.http-headers.request.terms=content-type,x-request-id sentry.data-collection.url-query-params.mode=off +sentry.data-collection.file-paths=false ``` ### Migrating From `sendDefaultPii` @@ -195,7 +199,7 @@ Data Collection preserves existing applications until you opt in: | An empty `DataCollection` | 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`, an empty `DataCollection` opts into the new filtered defaults. Keep `sendDefaultPii=true` only if you also need file paths, unencoded Logback messages, or the legacy OpenTelemetry header behavior. +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`, an empty `DataCollection` opts into the new filtered defaults. For unencoded Logback messages, use `includeUnencodedMessage` as described in the [Logback documentation](/platforms/java/guides/logback/). Keep `sendDefaultPii=true` only if you need the legacy OpenTelemetry header behavior. diff --git a/docs/platforms/java/common/data-management/data-collected.mdx b/docs/platforms/java/common/data-management/data-collected.mdx index 165d9ec5aeebe..84b2bb4291af4 100644 --- a/docs/platforms/java/common/data-management/data-collected.mdx +++ b/docs/platforms/java/common/data-management/data-collected.mdx @@ -85,10 +85,10 @@ The Gradle and Maven plugins can upload source code to Sentry so Issue Details c ## File I/O -File names and paths aren't part of Data Collection yet. File I/O instrumentation omits them unless `sendDefaultPii=true`. +`dataCollection.filePaths` controls file names and absolute paths added by File I/O instrumentation. The Data Collection default is `true`. Set it to `false` to omit file names and the `file.path` span data; file extensions and byte counts remain available. ## Log Messages Data Collection doesn't filter log messages or breadcrumb content. Avoid placing sensitive values in logs, and use `beforeBreadcrumb` or `beforeSend` when you need application-specific filtering. -When a Logback encoder is configured, unencoded messages and parameters continue to use `sendDefaultPii`. The encoded message is still sent. +When a Logback encoder is configured, the encoded message is sent while the original message template and parameters are omitted by default. Set `includeUnencodedMessage=true` on the Sentry appender to include them. The legacy `sendDefaultPii=true` behavior remains supported for compatibility. diff --git a/docs/platforms/java/guides/spring-boot/logging-frameworks/logback.mdx b/docs/platforms/java/guides/spring-boot/logging-frameworks/logback.mdx index cb049a777b902..273979e2b298a 100644 --- a/docs/platforms/java/guides/spring-boot/logging-frameworks/logback.mdx +++ b/docs/platforms/java/guides/spring-boot/logging-frameworks/logback.mdx @@ -88,6 +88,10 @@ However, if errors that may appear during startup should to be sent to Sentry, t +### Encoded Messages + +When a custom `SentryAppender` uses an encoder, Sentry sends the encoded message and omits the original message template and parameters by default. Set `true` directly on the appender to include them without enabling the broader `sendDefaultPii` option. See the [Logback configuration example](/platforms/java/guides/logback/#encoded-messages). + ## Mapped Diagnostic Context (MDC) Starting with Sentry Java SDK version 8.24.0, you can use the `contextTags` option to include specific properties from the Mapped Diagnostic Context (MDC) as attributes on log entries sent to Sentry. diff --git a/platform-includes/getting-started-config/java.logback.mdx b/platform-includes/getting-started-config/java.logback.mdx index 51446fd1298e6..182ed92d70fa0 100644 --- a/platform-includes/getting-started-config/java.logback.mdx +++ b/platform-includes/getting-started-config/java.logback.mdx @@ -128,3 +128,20 @@ Breadcrumbs are kept in memory (by default the last 100 records) and are sent wi ``` + +### Encoded Messages + +A Logback encoder can mask or remove sensitive values before Sentry receives a log entry. When you configure an encoder on `SentryAppender`, Sentry sends the encoded message and omits the original message template and parameters by default. + +Set `includeUnencodedMessage` to `true` when you also need the original template and parameters: + +```xml {filename:logback.xml} + + + %d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n + + true + +``` + +Original templates and parameters can contain sensitive data. Prefer this scoped appender option to `sendDefaultPii`; the legacy `sendDefaultPii=true` behavior remains supported for compatibility. From f5046241505795d9c28b9fc63448411ba091b87f Mon Sep 17 00:00:00 2001 From: Alexander Dinauer Date: Fri, 11 Sep 2026 10:42:14 +0200 Subject: [PATCH 3/8] docs(java): Defer unused database query data option Remove databaseQueryData from the Java and Android documentation while no production integration consumes it. Document the option when an integration can provide concrete configuration behavior. Co-Authored-By: Claude --- .../android/configuration/options.mdx | 2 -- .../data-management/data-collected.mdx | 6 ----- .../java/common/configuration/options.mdx | 24 +++++++++---------- .../common/data-management/data-collected.mdx | 6 ----- 4 files changed, 11 insertions(+), 27 deletions(-) diff --git a/docs/platforms/android/configuration/options.mdx b/docs/platforms/android/configuration/options.mdx index 14f94b5b55a80..3c4b0432eb579 100644 --- a/docs/platforms/android/configuration/options.mdx +++ b/docs/platforms/android/configuration/options.mdx @@ -126,7 +126,6 @@ Passing an empty `DataCollection` or configuring any field enables Data Collecti | `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. | -| `databaseQueryData` | `boolean` | `true` | Allows supported integrations to collect associated query data. Sanitized statements and structural metadata aren't affected. | | `filePaths` | `boolean` | `true` | Allows File I/O instrumentation to collect file names and absolute paths. File extensions and byte counts remain available when disabled. | Configure Data Collection in `AndroidManifest.xml`: @@ -164,7 +163,6 @@ Supported manifest keys are: - `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.database-query-data` - `io.sentry.data-collection.file-paths` The `cookies`, HTTP header, and URL query parameter fields support `off`, `deny_list`, and `allow_list`. Matching terms are comma-separated. Matching is partial and case-insensitive, and the built-in sensitive list always applies. Filtered values are replaced with `"[Filtered]"`. diff --git a/docs/platforms/android/data-management/data-collected.mdx b/docs/platforms/android/data-management/data-collected.mdx index b164ed18f4e1e..09bbb1edec945 100644 --- a/docs/platforms/android/data-management/data-collected.mdx +++ b/docs/platforms/android/data-management/data-collected.mdx @@ -68,12 +68,6 @@ Session Replay's network body collection remains separate. See ` | 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. | -| `databaseQueryData` | `boolean` | `true` | Allows supported integrations to collect associated query data, such as bound parameters, write payloads, and results. Sanitized statements and structural metadata aren't affected. | -| `filePaths` | `boolean` | `true` | Allows File I/O instrumentation to collect file names and absolute paths. File extensions and byte counts remain available when disabled. | +| 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` | 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. | Configure only the fields that differ from these defaults: @@ -172,7 +171,6 @@ data-collection.http-headers.response.mode=off data-collection.url-query-params.mode=off data-collection.graphql.document=false data-collection.graphql.variables=false -data-collection.database-query-data=false data-collection.file-paths=false ``` diff --git a/docs/platforms/java/common/data-management/data-collected.mdx b/docs/platforms/java/common/data-management/data-collected.mdx index 84b2bb4291af4..632163512a448 100644 --- a/docs/platforms/java/common/data-management/data-collected.mdx +++ b/docs/platforms/java/common/data-management/data-collected.mdx @@ -67,12 +67,6 @@ Use an empty set to disable all body collection. These fields apply to supported GraphQL server instrumentation and Apollo 3 and 4. Operation metadata used for tracing and grouping can still be collected when document or variable content is disabled. -## Database Query Data - -The SDK sends SQL statements in parameterized form. For example, it sends `UPDATE app_user SET password=? WHERE id=?` instead of literal values. - -`dataCollection.databaseQueryData` controls additional query data, such as bound parameters, write payloads, or results, where an integration supports it. Sanitized statements and structural database metadata remain available when this option is `false`. - ## OpenTelemetry Attributes Data Collection can't distinguish attributes added automatically by OpenTelemetry instrumentation from attributes your application adds explicitly. Configure the OpenTelemetry instrumentation that produces those attributes, or scrub them with `beforeSendTransaction`. From d5a87392806078d095d1e44958c70e70ba2ab645 Mon Sep 17 00:00:00 2001 From: Alexander Dinauer Date: Fri, 11 Sep 2026 14:49:56 +0200 Subject: [PATCH 4/8] docs: Refine Java and Android data collection guidance Preserve the existing sendDefaultPii descriptions while marking the option as legacy. Align the Data Collected pages with current defaults and filtering behavior. Co-Authored-By: Claude --- .../android/configuration/options.mdx | 16 +++- .../data-management/data-collected.mdx | 82 ++++++++--------- .../java/common/configuration/options.mdx | 16 +++- .../common/data-management/data-collected.mdx | 87 ++++++++----------- 4 files changed, 98 insertions(+), 103 deletions(-) diff --git a/docs/platforms/android/configuration/options.mdx b/docs/platforms/android/configuration/options.mdx index 3c4b0432eb579..d15b0e03cd83d 100644 --- a/docs/platforms/android/configuration/options.mdx +++ b/docs/platforms/android/configuration/options.mdx @@ -98,23 +98,31 @@ AndroidManifest.xml key: `io.sentry.additional-context`. -Controls legacy collection of personally identifiable information (PII) by active integrations. Use [`dataCollection`](#dataCollection) for granular control over automatically collected data. +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. -Read our [frequently asked questions about mobile data privacy](/security-legal-pii/security/mobile-privacy/) when completing Apple App Store or Google Play privacy details. +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. +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/). + -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`. +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`. + + + +Passing an empty `DataCollection` or explicitly configuring any field enables Data Collection. All fields you don't configure use the defaults below, and `sendDefaultPii` no longer controls Data Collection categories. -Passing an empty `DataCollection` or configuring any field enables Data Collection. Omitted fields then use these defaults: + | Field | Type | Default | Behavior | | ---------------------- | ---------------------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | diff --git a/docs/platforms/android/data-management/data-collected.mdx b/docs/platforms/android/data-management/data-collected.mdx index 09bbb1edec945..5b2af21db8cd7 100644 --- a/docs/platforms/android/data-management/data-collected.mdx +++ b/docs/platforms/android/data-management/data-collected.mdx @@ -1,93 +1,81 @@ --- title: Data Collected -description: "See what data is collected by the Sentry Android SDK and how to control automatic collection." +description: "See what data is collected by the Sentry Android SDK." sidebar_order: 1 --- -The Sentry Android SDK collects crashes, errors, traces, logs, and device context through the integrations you enable. Review this page before release so the SDK's automatic collection matches your mobile privacy disclosures and requirements. +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. -Use Data Collection to control supported categories. The first Data Collection field you configure activates the documented Data Collection defaults for every omitted field. If you don't configure Data Collection, the SDK preserves the existing `sendDefaultPii` behavior. +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 to control automatic collection for supported categories. -Data Collection controls only data added automatically by SDK integrations. Data you add through scopes, event processors, `beforeSend`, or other APIs is still sent. +After you configure any Data Collection field or pass an empty `DataCollection`, 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. -Read our [mobile data privacy FAQ](/security-legal-pii/security/mobile-privacy/) when completing Apple App Store or Google Play privacy details. +## HTTP Headers - +Request and response headers use `DENY_LIST` by default. Supported integrations collect header names and non-sensitive values while replacing sensitive values with `"[Filtered]"`. -## Filtering Key-Value Data +Use `dataCollection.httpHeaders.request` and `dataCollection.httpHeaders.response` to control header collection. OkHttp, Ktor Client, and Apollo 3 and 4 can attach available request and response headers to captured HTTP client errors. -Cookies, HTTP headers, and URL query parameters support three collection modes: +Session Replay network details use [separate options](/platforms/android/session-replay/configuration/). -- `OFF` collects nothing in the category. -- `DENY_LIST` collects values except those matching the built-in sensitive list or your additional terms. -- `ALLOW_LIST` sends plaintext values only for keys matching your terms. The built-in sensitive list still applies. +## Cookies -Matching is partial and case-insensitive. Sensitive values are replaced with `"[Filtered]"` rather than removed. See the Data Collection option for manifest and manual-initialization examples. +Cookies use `DENY_LIST` by default. Supported integrations collect cookies while replacing sensitive values with `"[Filtered]"`. Use `dataCollection.cookies` to control cookie collection. -## User Information and IP Addresses +## Information About Logged-in User 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. -`dataCollection.userInfo` controls other user information populated automatically, including the `"{{auto}}"` IP address value that asks Sentry to infer the address from the connection. The Data Collection default is `true`. Set it to `false` to prevent automatic IP enrichment. +`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. -User information you set explicitly with `Sentry.setUser()` or on a scope isn't removed. +## Users' IP Addresses -## HTTP Headers +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. -`dataCollection.httpHeaders.request` and `dataCollection.httpHeaders.response` control request and response headers independently. With the default `DENY_LIST` mode, supported HTTP client integrations collect available headers and replace sensitive values with `"[Filtered]"`. - -This applies to captured errors from OkHttp, Ktor Client, and Apollo 3 and 4. Cookie headers are filtered separately through `dataCollection.cookies`. - -Session Replay network details use separate options. See Session Replay Configuration. - -## Cookies +## Request URL -`dataCollection.cookies` controls cookies collected by supported HTTP client integrations. The default `DENY_LIST` mode collects cookie names while filtering values with the built-in sensitive list. +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. -Set the mode to `OFF` to omit cookies, or use `ALLOW_LIST` to expose only selected non-sensitive values. +## Request Query String -## Request URLs and Query Parameters +Query parameters use `DENY_LIST` by default. Use `dataCollection.urlQueryParams` to filter or disable query string collection for instrumented request URLs. -The base request URL is sent without its query string or fragment where an HTTP client integration records a request. URL fragments may be sent in a separate field and aren't controlled by Data Collection, so avoid placing sensitive values in fragments or scrub them with `beforeSend`. +## Request and Response Bodies -`dataCollection.urlQueryParams` controls query parameters for instrumented outgoing URLs. The default `DENY_LIST` mode keeps parameter names and non-sensitive values while replacing sensitive values with `"[Filtered]"`. Set the mode to `OFF` to omit the query string. +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. -## HTTP Bodies +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/). -`dataCollection.httpBodies` can control incoming and outgoing request and response bodies, but an integration collects a body only when that body is available. - -On Android, Apollo 3 and 4 can collect outgoing GraphQL request bodies and incoming GraphQL response bodies. OkHttp and Ktor Client error events collect body sizes, not body content. Use an empty set to disable all body collection. +## Source Context -Session Replay's network body collection remains separate. See Session Replay Configuration. +Our build tool plugins for Gradle and Maven can upload your source code to Sentry, which can then used to show the lines of code where an error happened in the Issue Details page. -## GraphQL Data +To opt into sending this source context to Sentry, you have to enable the feature as described in the Source Context documentation. -`dataCollection.graphql.document` controls GraphQL documents, and `dataCollection.graphql.variables` controls variables. Both default to `true` when Data Collection is active. +## File I/O -These fields apply to Apollo 3 and 4. Operation metadata used for tracing and grouping can still be collected when document or variable content is disabled. +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 -The SDK automatically collects device and operating-system context. This can include battery level, memory use, storage state, orientation, boot time, emulator status, and connectivity. +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. -Static device context, such as the manufacturer and hardware model, is collected independently of Data Collection. Set `collectAdditionalContext=false` to reduce additional dynamic context. +Set `collectAdditionalContext=false` to reduce additional dynamic context such as battery level, available memory, storage state, and connectivity. -## Source Context +## GraphQL Data -The Sentry Gradle plugin can upload source code to Sentry so Issue Details can show the lines around an error. This is opt-in and configured separately. See Source Context. +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. -## File I/O +## SQL Queries -`dataCollection.filePaths` controls file names and absolute paths added by File I/O instrumentation. The Data Collection default is `true`. Set it to `false` to omit file names and the `file.path` span data; file extensions and byte counts remain available. +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 -Data Collection doesn't filter log messages or breadcrumb content. Avoid placing sensitive values in logs, and use `beforeBreadcrumb` or `beforeSend` when you need application-specific filtering. +Log messages, parameters, and breadcrumb content may contain application data. Data Collection doesn't filter this content. Use `beforeBreadcrumb` or `beforeSend` when you need application-specific filtering. ## Session Replay -Session Replay has separate privacy defaults and configuration. By default, Replay masks text, images, webviews, and user input. Data Collection doesn't change Replay's URL, header, body, masking, or screenshot settings. - -See Session Replay Privacy for details. +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 more details in the Session Replay documentation. diff --git a/docs/platforms/java/common/configuration/options.mdx b/docs/platforms/java/common/configuration/options.mdx index 6949d9ac6b290..2fd102d5e5324 100644 --- a/docs/platforms/java/common/configuration/options.mdx +++ b/docs/platforms/java/common/configuration/options.mdx @@ -102,7 +102,13 @@ Note that enabling this option may increase the payload size of events sent to S -Controls legacy collection of personally identifiable information (PII) by active integrations. Use [`dataCollection`](#dataCollection) for granular control over automatically collected data. +If this flag is enabled, certain personally identifiable information (PII) is added by active integrations. By default, no such data is sent. + +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/). + +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. @@ -112,9 +118,13 @@ Unencoded Logback messages aren't a Data Collection category. To include origina -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`. +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`. + + + +Passing an empty `DataCollection` or explicitly configuring any field enables Data Collection. All fields you don't configure use the defaults below, and `sendDefaultPii` no longer controls Data Collection categories. -Passing an empty `DataCollection` or configuring any field enables Data Collection. Omitted fields then use these defaults: + | Field | Type | Default | Behavior | | ---------------------- | ---------------------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | diff --git a/docs/platforms/java/common/data-management/data-collected.mdx b/docs/platforms/java/common/data-management/data-collected.mdx index 632163512a448..c0c222985ac5c 100644 --- a/docs/platforms/java/common/data-management/data-collected.mdx +++ b/docs/platforms/java/common/data-management/data-collected.mdx @@ -1,88 +1,77 @@ --- title: Data Collected -description: "See what data is collected by the Sentry Java SDK and how to control automatic collection." +description: "See what data is collected by the Sentry Java SDK." sidebar_order: 1 --- -The Sentry Java SDK collects errors, traces, logs, and debugging context through the integrations you enable. Review this page before production rollout so the SDK's automatic collection matches your privacy requirements. +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. -Use Data Collection to control supported categories. The first Data Collection field you configure activates the documented Data Collection defaults for every omitted field. If you don't configure Data Collection, the SDK preserves the existing `sendDefaultPii` behavior. +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 Java SDK collects. Use to control automatic collection for supported categories. -Data Collection controls only data added automatically by SDK integrations. Data you add through scopes, event processors, `beforeSend`, or other APIs is still sent. - -## Filtering Key-Value Data - -Cookies, HTTP headers, and URL query parameters support three collection modes: - -- `OFF` collects nothing in the category. -- `DENY_LIST` collects values except those matching the built-in sensitive list or your additional terms. -- `ALLOW_LIST` sends plaintext values only for keys matching your terms. The built-in sensitive list still applies. - -Matching is partial and case-insensitive. Sensitive values are replaced with `"[Filtered]"` rather than removed. See the Data Collection option for configuration examples. +After you configure any Data Collection field or pass an empty `DataCollection`, unconfigured fields use their documented defaults. -## User Information and IP Addresses +Data Collection controls only data added automatically by SDK integrations. Data you add through scopes, event processors, `beforeSend`, or other APIs is still sent. -`dataCollection.userInfo` controls user information populated automatically by integrations. This includes Spring Security usernames and the `"{{auto}}"` IP address value, which asks Sentry to infer the address from the connection. +## HTTP Headers -The Data Collection default is `true`. Set it to `false` to prevent automatic user enrichment. User information you set explicitly with `Sentry.setUser()` or on a scope isn't removed. +Request and response headers use `DENY_LIST` by default. Supported integrations collect header names and non-sensitive values while replacing sensitive values with `"[Filtered]"`. -## HTTP Headers +Use `dataCollection.httpHeaders.request` and `dataCollection.httpHeaders.response` to control header collection. Servlet and Spring integrations can collect incoming request headers. OkHttp, Ktor Client, and Apollo can attach request and response headers to captured HTTP client errors. -`dataCollection.httpHeaders.request` and `dataCollection.httpHeaders.response` control request and response headers independently. With the default `DENY_LIST` mode, integrations collect available headers and replace sensitive values with `"[Filtered]"`. +## Cookies -Header availability depends on the integration. Servlet and Spring integrations can collect incoming request headers, while OkHttp, Ktor Client, and Apollo can collect request and response headers for captured HTTP client errors. +Cookies use `DENY_LIST` by default. Supported integrations collect cookies while replacing sensitive values with `"[Filtered]"`. Use `dataCollection.cookies` to control cookie collection. -Cookie headers are filtered separately through `dataCollection.cookies`. +## Information About Logged-in User -## Cookies +`dataCollection.userInfo` allows integrations to populate user identity information automatically, including Spring Security usernames and the user's IP address. 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. -`dataCollection.cookies` controls cookies collected by supported Spring and HTTP client integrations. The default `DENY_LIST` mode collects cookie names while filtering values with the built-in sensitive list. +## Users' IP Addresses -Set the mode to `OFF` to omit cookies, or use `ALLOW_LIST` to expose only selected non-sensitive values. +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 URLs and Query Parameters +## Request URL -The base request URL is sent without its query string or fragment where an integration records an HTTP request. URL fragments may be sent in a separate field and aren't controlled by Data Collection, so avoid placing sensitive values in fragments or scrub them with `beforeSend`. +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. -`dataCollection.urlQueryParams` controls query parameters for instrumented incoming and outgoing URLs, including HTTP spans and breadcrumbs created by integrations such as Spring and OpenFeign. The default `DENY_LIST` mode keeps parameter names and non-sensitive values while replacing sensitive values with `"[Filtered]"`. Set the mode to `OFF` to omit the query string. +## Request Query String -## HTTP Bodies +Query parameters use `DENY_LIST` by default. Use `dataCollection.urlQueryParams` to filter or disable query string collection for instrumented incoming and outgoing URLs, including HTTP spans and breadcrumbs created by integrations such as Spring and OpenFeign. -`dataCollection.httpBodies` controls four body directions independently: +## Request Body -- `INCOMING_REQUEST` -- `OUTGOING_REQUEST` -- `INCOMING_RESPONSE` -- `OUTGOING_RESPONSE` +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. -All four are enabled by the Data Collection defaults, but an integration collects a body only when that body is available. For example, Spring can collect supported incoming request bodies, GraphQL server instrumentation can collect request and response data, and Apollo 3 and 4 can collect GraphQL client request and response bodies. OkHttp and Ktor Client error events collect body sizes, not body content. +Use `dataCollection.httpBodies` to choose which directions to collect or an empty set to disable body collection. For incoming HTTP request bodies, the type and size restrictions below also apply: -For Spring request bodies, `maxRequestBodySize` also limits collection and defaults to `NONE`. Spring collects only supported JSON and form bodies within that size limit. +- **The type of the request body:** + - JSON and form bodies are sent +- **The size of the request body:** There's a maxRequestBodySize option that's set to `NONE` by default. This means by default no request body is sent to Sentry. -Use an empty set to disable all body collection. +## Source Context -## GraphQL Data +Our build tool plugins for Gradle and Maven can upload your source code to Sentry, which can then used to show the lines of code where an error happened in the Issue Details page. -`dataCollection.graphql.document` controls GraphQL documents, and `dataCollection.graphql.variables` controls variables. Both default to `true` when Data Collection is active. +To opt into sending this source context to Sentry, you have to enable the feature as described in the Source Context documentation. -These fields apply to supported GraphQL server instrumentation and Apollo 3 and 4. Operation metadata used for tracing and grouping can still be collected when document or variable content is disabled. +## File I/O -## OpenTelemetry Attributes +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. -Data Collection can't distinguish attributes added automatically by OpenTelemetry instrumentation from attributes your application adds explicitly. Configure the OpenTelemetry instrumentation that produces those attributes, or scrub them with `beforeSendTransaction`. +## Log Messages -Sentry's legacy extraction of OpenTelemetry HTTP header attributes continues to use `sendDefaultPii` and isn't controlled by Data Collection yet. +By default the Sentry SDK does not send unencoded Logback messages and parameters if an encoder has been set. It will however send the encoded message. -## Source Context +Set `includeUnencodedMessage=true` on the Sentry appender to include the original message and parameters. Data Collection doesn't filter log messages or breadcrumb content. Use `beforeBreadcrumb` or `beforeSend` when you need application-specific filtering. -The Gradle and Maven plugins can upload source code to Sentry so Issue Details can show the lines around an error. This is opt-in and configured separately. See Source Context. +## GraphQL Data -## File I/O +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. -`dataCollection.filePaths` controls file names and absolute paths added by File I/O instrumentation. The Data Collection default is `true`. Set it to `false` to omit file names and the `file.path` span data; file extensions and byte counts remain available. +## OpenTelemetry Attributes -## Log Messages +Data Collection doesn't filter attributes added by OpenTelemetry instrumentation or your application. Configure the instrumentation that produces them, or scrub them with `beforeSendTransaction`. -Data Collection doesn't filter log messages or breadcrumb content. Avoid placing sensitive values in logs, and use `beforeBreadcrumb` or `beforeSend` when you need application-specific filtering. +## SQL Queries -When a Logback encoder is configured, the encoded message is sent while the original message template and parameters are omitted by default. Set `includeUnencodedMessage=true` on the Sentry appender to include them. The legacy `sendDefaultPii=true` behavior remains supported for compatibility. +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. From a7443766113d87ba5405377643e2fdc547f5ee3a Mon Sep 17 00:00:00 2001 From: Alexander Dinauer Date: Fri, 11 Sep 2026 15:17:12 +0200 Subject: [PATCH 5/8] style(docs): Restore unrelated formatting Restore pre-existing formatting changed during the Data Collection update. Keep quote, wrapping, XML, and snippet changes out of the branch diff. Co-Authored-By: Claude --- docs/platforms/android/index.mdx | 34 ++++-------- .../integrations/ktor-client/index.mdx | 15 ++---- docs/platforms/android/manual-setup/index.mdx | 13 ++--- .../tracing/instrumentation/ktor-client.mdx | 11 ++-- .../getting-started-config/java.jul.mdx | 5 +- .../getting-started-config/java.log4j2.mdx | 54 +++++++++---------- .../getting-started-config/java.logback.mdx | 13 ++--- .../getting-started-config/java.mdx | 1 - .../getting-started-config/java.servlet.mdx | 5 +- .../java.spring-boot.mdx | 1 + .../getting-started-config/java.spring.mdx | 27 +++++++--- 11 files changed, 81 insertions(+), 98 deletions(-) diff --git a/docs/platforms/android/index.mdx b/docs/platforms/android/index.mdx index e9b9711c6f49b..4187676aa4ddf 100644 --- a/docs/platforms/android/index.mdx +++ b/docs/platforms/android/index.mdx @@ -30,24 +30,18 @@ Select which Sentry features you'd like to install in addition to Error Monitori - On Android 15 (API level 35) and higher, profiling uses the Android{" "} - - ProfilingManager - {" "} - to capture Perfetto traces. On older - devices, the SDK automatically falls back to the{" "} - legacy profiler. + On Android 15 (API level 35) and higher, profiling uses the Android ProfilingManager to capture Perfetto traces. On older devices, the SDK automatically falls back to the legacy profiler. @@ -118,6 +112,7 @@ The wizard will prompt you to log in to Sentry. It'll then automatically do the Configuration is done via the application `AndroidManifest.xml`. Here's an example config which should get you started: + ```xml {filename:AndroidManifest.xml} @@ -189,14 +184,7 @@ class MyActivity : AppCompatActivity() { ## Next Steps - Explore [practical guides](/get-started/guides/) on what to monitor, log, track, and investigate after setup -- - Learn about the features of Sentry's Android SDK - -- - Learn how to enhance stack traces of your Sentry errors - -- - Enrich events with additional context to make debugging simpler - -- Diagnose ANRs - with profiling and automatic fingerprinting +- Learn about the features of Sentry's Android SDK +- Learn how to enhance stack traces of your Sentry errors +- Enrich events with additional context to make debugging simpler +- Diagnose ANRs with profiling and automatic fingerprinting diff --git a/docs/platforms/android/integrations/ktor-client/index.mdx b/docs/platforms/android/integrations/ktor-client/index.mdx index 86a865883f260..3b51190bc69f9 100644 --- a/docs/platforms/android/integrations/ktor-client/index.mdx +++ b/docs/platforms/android/integrations/ktor-client/index.mdx @@ -12,7 +12,6 @@ The `sentry-ktor-client` library provides [Ktor Client](https://ktor.io/) suppor On this page, we get you up and running with Sentry's Ktor Client Integration. The integration supports: - - Adding breadcrumbs for each HTTP request. - Capturing spans for each HTTP Request, with support for distributed tracing. The span will be created as a child of the current span bound to the scope (if any). - Capturing certain request failures as errors in Sentry. @@ -20,14 +19,9 @@ The integration supports: The Sentry Ktor Client integration supports Ktor Client version `3.x`. - If you're using Ktor Client with OKHttp as the engine, and you're already - using the [Sentry OkHttp - integration](/platforms/android/integrations/okhttp/), either with manual or - automatic installation (via the Sentry Android Gradle Plugin), you should - avoid using this integration, otherwise the SDK will produce duplicate data, - instrumenting each HTTP request twice. Use the [Sentry OkHttp - integration](/platforms/android/integrations/okhttp/) instead, as it provides - more detailed information about HTTP request. + If you're using Ktor Client with OKHttp as the engine, and you're already using the [Sentry OkHttp integration](/platforms/android/integrations/okhttp/), + either with manual or automatic installation (via the Sentry Android Gradle Plugin), you should avoid using this integration, otherwise the SDK will produce duplicate data, instrumenting each HTTP request twice. + Use the [Sentry OkHttp integration](/platforms/android/integrations/okhttp/) instead, as it provides more detailed information about HTTP request. ## Install @@ -43,6 +37,7 @@ implementation 'io.sentry:sentry-ktor-client:{{@inject packages.version('sentry. Create the Ktor HTTP Client with your preferred engine, and install the Sentry Ktor Client Plugin: + ```kotlin import io.ktor.client.* import io.ktor.client.engine.android.* @@ -81,7 +76,7 @@ suspend fun run(url: String): String? { -Learn more about manually capturing an error or message in our Usage documentation. + Learn more about manually capturing an error or message in our Usage documentation. diff --git a/docs/platforms/android/manual-setup/index.mdx b/docs/platforms/android/manual-setup/index.mdx index 41887b09e97da..0ec254ec43608 100644 --- a/docs/platforms/android/manual-setup/index.mdx +++ b/docs/platforms/android/manual-setup/index.mdx @@ -52,6 +52,7 @@ If you're using multiple Sentry dependencies, you can add a [bill of materials]( Configuration is done via the application `AndroidManifest.xml`. Here's an example config which should get you started: + ```xml {filename:AndroidManifest.xml} @@ -129,12 +130,12 @@ The SDK can catch errors and crashes only after you've initialized it. For that Configuration options will be loaded from the manifest so that you don't need to have the static properties in your code. In the `init` method, you can provide a callback that will modify the configuration and also register new options. ```kotlin -import io.sentry.DataCollection -import io.sentry.ScreenshotStrategyType -import io.sentry.SentryLevel -import io.sentry.ProfileLifecycle -import io.sentry.android.core.SentryAndroid -import android.app.Application +import io.sentry.DataCollection; +import io.sentry.ScreenshotStrategyType; +import io.sentry.SentryLevel; +import io.sentry.ProfileLifecycle; +import io.sentry.android.core.SentryAndroid; +import android.app.Application; import io.sentry.SentryOptions class MyApplication : Application() { diff --git a/docs/platforms/java/common/tracing/instrumentation/ktor-client.mdx b/docs/platforms/java/common/tracing/instrumentation/ktor-client.mdx index ebd8f59bce6e7..d94a852e5d194 100644 --- a/docs/platforms/java/common/tracing/instrumentation/ktor-client.mdx +++ b/docs/platforms/java/common/tracing/instrumentation/ktor-client.mdx @@ -19,7 +19,6 @@ The `sentry-ktor-client` library provides [Ktor Client](https://ktor.io/) suppor On this page, we get you up and running with Sentry's Ktor Client Integration. The integration supports: - - Adding breadcrumbs for each HTTP request. - Capturing spans for each HTTP Request, with support for distributed tracing. The span will be created as a child of the current span bound to the scope (if any). - Capturing certain request failures as errors in Sentry. @@ -27,13 +26,9 @@ The integration supports: The Sentry Ktor Client integration supports Ktor Client version `3.x`. - If you're using Ktor Client with OKHttp as the engine, and you're already - using the [Sentry OkHttp - integration](/platforms/java/tracing/instrumentation/okhttp/), you should - avoid using this integration, otherwise the SDK will produce duplicate data, - instrumenting each HTTP request twice. Use the [Sentry OkHttp - integration](/platforms/java/tracing/instrumentation/okhttp/) instead, as it - provides more detailed information about HTTP request. + If you're using Ktor Client with OKHttp as the engine, and you're already using the [Sentry OkHttp integration](/platforms/java/tracing/instrumentation/okhttp/), + you should avoid using this integration, otherwise the SDK will produce duplicate data, instrumenting each HTTP request twice. + Use the [Sentry OkHttp integration](/platforms/java/tracing/instrumentation/okhttp/) instead, as it provides more detailed information about HTTP request. ## Install diff --git a/platform-includes/getting-started-config/java.jul.mdx b/platform-includes/getting-started-config/java.jul.mdx index cb390832ebf06..b984283bd97e2 100644 --- a/platform-includes/getting-started-config/java.jul.mdx +++ b/platform-includes/getting-started-config/java.jul.mdx @@ -32,6 +32,7 @@ java -Djava.util.logging.config.file=/path/to/app.properties MyClass Sentry reads the DSN from the system property `sentry.dsn`, environment variable `SENTRY_DSN` or the `dsn` property in `sentry.properties` file. [See the configuration page](/platforms/java/configuration/) for more details on external configuration. + ```properties {tabTitle:sentry.properties} dsn=___PUBLIC_DSN___ # Use Data Collection defaults but don't collect automatic user information. @@ -42,7 +43,6 @@ data-collection.user-info=false logs.enabled=true ``` - ### Minimum Log Level @@ -51,11 +51,8 @@ Two log levels are used to configure this integration: 1. Configure the lowest level required for a log message to become an event (`minimumEventLevel`) sent to Sentry. 2. Configure the lowest level a message has to be to become a breadcrumb (`minimumBreadcrumbLevel`). - - 3. Configure the lowest level a message has to be to be sent as Sentry Log (`minimumLevel`). - diff --git a/platform-includes/getting-started-config/java.log4j2.mdx b/platform-includes/getting-started-config/java.log4j2.mdx index 6aa6f0947968c..34658fc595014 100644 --- a/platform-includes/getting-started-config/java.log4j2.mdx +++ b/platform-includes/getting-started-config/java.log4j2.mdx @@ -13,19 +13,19 @@ The `ConsoleAppender` is provided only as an example of a non-Sentry appender se - - - - - - - - - - - - - + + + + + + + + + + + + + ``` @@ -36,19 +36,19 @@ The `ConsoleAppender` is provided only as an example of a non-Sentry appender se - - - - - - + + + + + + - - - - - - + + + + + + ``` @@ -75,7 +75,6 @@ data-collection.user-info=false logs.enabled=true // ___PRODUCT_OPTION_END___ logs ``` - ### Minimum Log Level @@ -84,11 +83,8 @@ Two log levels are used to configure this integration, as illustrated below in t 1. Configure the lowest level required for a log message to become an event (`minimumEventLevel`) sent to Sentry. 2. Configure the lowest level a message has to be to become a breadcrumb (`minimumBreadcrumbLevel`) - - 3. Configure the lowest level a message has to be to be sent as Sentry Log (`minimumLevel`). - diff --git a/platform-includes/getting-started-config/java.logback.mdx b/platform-includes/getting-started-config/java.logback.mdx index 182ed92d70fa0..85733ed6f2eb7 100644 --- a/platform-includes/getting-started-config/java.logback.mdx +++ b/platform-includes/getting-started-config/java.logback.mdx @@ -29,12 +29,12 @@ The `ConsoleAppender` is provided only as an example of a non-Sentry appender se - + - ``` @@ -52,12 +52,12 @@ The `ConsoleAppender` is provided only as an example of a non-Sentry appender se - + - ``` @@ -75,7 +75,6 @@ data-collection.user-info=false ``` You can also provide the DSN through the `sentry.dsn` system property or the `SENTRY_DSN` environment variable. [See the configuration page](/platforms/java/configuration/) for more details on external configuration. - ### Minimum Log Level @@ -84,11 +83,8 @@ Two log levels are used to configure this integration: 1. Configure the lowest level required for a log message to become an event (`minimumEventLevel`) sent to Sentry. 2. Configure the lowest level a message has to be to become a breadcrumb (`minimumBreadcrumbLevel`). - - 3. Configure the lowest level a message has to be to be sent as Sentry Log (`minimumLevel`). - @@ -99,6 +95,7 @@ Setting `minimumEventLevel` or `minimumBreadcrumbLevel` in `logback.xml` only af Breadcrumbs are kept in memory (by default the last 100 records) and are sent with events. For example, by default, if you log 100 entries with `logger.info` or `logger.warn`, no event is sent to Sentry. If you then log with `logger.error`, an event is sent to Sentry which includes those 100 `info` or `warn` messages. For this to work, `SentryAppender` needs to receive **all** log entries to decide what to keep as breadcrumb or sent as event. Set the `SentryAppender` log level configuration to a value lower than what is set for the `minimumBreadcrumbLevel` and `minimumEventLevel` so that `SentryAppender` receives these log messages. + ```xml diff --git a/platform-includes/getting-started-config/java.mdx b/platform-includes/getting-started-config/java.mdx index aa608a199f157..51f9fe073756e 100644 --- a/platform-includes/getting-started-config/java.mdx +++ b/platform-includes/getting-started-config/java.mdx @@ -66,7 +66,6 @@ Sentry.init { options -> // ___PRODUCT_OPTION_END___ logs } ``` - diff --git a/platform-includes/getting-started-config/java.servlet.mdx b/platform-includes/getting-started-config/java.servlet.mdx index b0461d45d2061..f6db2e141416c 100644 --- a/platform-includes/getting-started-config/java.servlet.mdx +++ b/platform-includes/getting-started-config/java.servlet.mdx @@ -3,6 +3,7 @@ Configuration should happen as early as possible in your application's lifecycle The following example configures a `SentryInitializer` servlet container initializer that initializes Sentry on application startup. + ```java package sentry.sample; @@ -66,7 +67,7 @@ class SentryInitializer : ServletContainerInitializer { options.dataCollection = DataCollection().apply { userInfo = false } - // ___PRODUCT_OPTION_START___ performance + // ___PRODUCT_OPTION_START___ performance // Set traces_sample_rate to 1.0 to capture 100% // of transactions for tracing. @@ -88,7 +89,6 @@ class SentryInitializer : ServletContainerInitializer { } } ``` - @@ -102,5 +102,4 @@ Create a file in `src/main/resources/META-INF/services` named `javax.servlet.Ser ```properties sentry.sample.SentryInitializer ``` - diff --git a/platform-includes/getting-started-config/java.spring-boot.mdx b/platform-includes/getting-started-config/java.spring-boot.mdx index 7489ca3bda04a..4c20d31316b9a 100644 --- a/platform-includes/getting-started-config/java.spring-boot.mdx +++ b/platform-includes/getting-started-config/java.spring-boot.mdx @@ -2,6 +2,7 @@ Sentry's Spring Boot integration auto-configures `sentry.in-app-packages` proper Provide a `sentry.dsn` property using either `application.properties` or `application.yml`: + ```properties {filename:application.properties} sentry.dsn=___PUBLIC_DSN___ diff --git a/platform-includes/getting-started-config/java.spring.mdx b/platform-includes/getting-started-config/java.spring.mdx index 5dc84d7af5621..5b4770c2fe384 100644 --- a/platform-includes/getting-started-config/java.spring.mdx +++ b/platform-includes/getting-started-config/java.spring.mdx @@ -2,11 +2,14 @@ Configuration should happen as early as possible in your application's lifecycle The `sentry-spring`, `sentry-spring-jakarta`, and `sentry-spring-7` libraries provide an `@EnableSentry` annotation that registers all required Spring beans. `@EnableSentry` can be placed on any class annotated with [@Configuration](https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/context/annotation/Configuration.html) including the main entry class in Spring Boot applications annotated with [@SpringBootApplication](https://docs.spring.io/spring-boot/docs/current/api/org/springframework/boot/autoconfigure/SpringBootApplication.html). + ```java {tabTitle:Java (Spring 5)} {mdExpandTabs} import io.sentry.spring.EnableSentry; // NOTE: Replace the test DSN below with YOUR OWN DSN to see the events from this app in your Sentry // project/dashboard -@EnableSentry(dsn = "___PUBLIC_DSN___") +@EnableSentry( + dsn = "___PUBLIC_DSN___" +) @Configuration class SentryConfiguration { } @@ -16,7 +19,9 @@ class SentryConfiguration { import io.sentry.spring.jakarta.EnableSentry; // NOTE: Replace the test DSN below with YOUR OWN DSN to see the events from this app in your Sentry // project/dashboard -@EnableSentry(dsn = "___PUBLIC_DSN___") +@EnableSentry( + dsn = "___PUBLIC_DSN___" +) @Configuration class SentryConfiguration { } @@ -26,7 +31,9 @@ class SentryConfiguration { import io.sentry.spring7.EnableSentry; // NOTE: Replace the test DSN below with YOUR OWN DSN to see the events from this app in your Sentry // project/dashboard -@EnableSentry(dsn = "___PUBLIC_DSN___") +@EnableSentry( + dsn = "___PUBLIC_DSN___" +) @Configuration class SentryConfiguration { } @@ -36,7 +43,9 @@ class SentryConfiguration { import io.sentry.spring.EnableSentry // NOTE: Replace the test DSN below with YOUR OWN DSN to see the events from this app in your Sentry // project/dashboard -@EnableSentry(dsn = "___PUBLIC_DSN___") +@EnableSentry( + dsn = "___PUBLIC_DSN___" +) @Configuration class SentryConfiguration ``` @@ -45,7 +54,9 @@ class SentryConfiguration import io.sentry.spring.jakarta.EnableSentry // NOTE: Replace the test DSN below with YOUR OWN DSN to see the events from this app in your Sentry // project/dashboard -@EnableSentry(dsn = "___PUBLIC_DSN___") +@EnableSentry( + dsn = "___PUBLIC_DSN___" +) @Configuration class SentryConfiguration ``` @@ -54,7 +65,9 @@ class SentryConfiguration import io.sentry.spring7.EnableSentry // NOTE: Replace the test DSN below with YOUR OWN DSN to see the events from this app in your Sentry // project/dashboard -@EnableSentry(dsn = "___PUBLIC_DSN___") +@EnableSentry( + dsn = "___PUBLIC_DSN___" +) @Configuration class SentryConfiguration ``` @@ -72,6 +85,7 @@ Once this integration is configured you can _also_ use Sentry’s static API, [a By default, only unhandled exceptions are sent to Sentry. This behavior can be tuned through configuring the `exceptionResolverOrder` property. For example, setting it to `Ordered#HIGHEST_PRECEDENCE` ensures exceptions that have been handled by exception resolvers with higher order are sent to Sentry - including ones handled by `@ExceptionHandler` annotated methods. + ```java {tabTitle:Java (Spring 5)} {mdExpandTabs} import io.sentry.spring.EnableSentry; import org.springframework.core.Ordered; @@ -147,6 +161,7 @@ import org.springframework.core.Ordered class SentryConfiguration ``` + The SDK can be configured using a `sentry.properties` file: ```properties {filename:sentry.properties} From 13e8192004b20fc937c8ef8affa5253db6176374 Mon Sep 17 00:00:00 2001 From: Alexander Dinauer Date: Fri, 11 Sep 2026 15:23:14 +0200 Subject: [PATCH 6/8] docs(java): Hint at additional Data Collection options Add comments after userInfo examples in Java setup snippets. Make it clear that developers can configure other collection categories. Co-Authored-By: Claude --- platform-includes/getting-started-config/java.jul.mdx | 1 + platform-includes/getting-started-config/java.log4j2.mdx | 1 + platform-includes/getting-started-config/java.logback.mdx | 1 + platform-includes/getting-started-config/java.mdx | 2 ++ platform-includes/getting-started-config/java.servlet.mdx | 2 ++ platform-includes/getting-started-config/java.spring-boot.mdx | 2 ++ platform-includes/getting-started-config/java.spring.mdx | 1 + platform-includes/getting-started-config/opentelemetry/java.mdx | 1 + 8 files changed, 11 insertions(+) diff --git a/platform-includes/getting-started-config/java.jul.mdx b/platform-includes/getting-started-config/java.jul.mdx index b984283bd97e2..b9fa7348381f3 100644 --- a/platform-includes/getting-started-config/java.jul.mdx +++ b/platform-includes/getting-started-config/java.jul.mdx @@ -38,6 +38,7 @@ dsn=___PUBLIC_DSN___ # Use Data Collection defaults but don't collect automatic user information. # https://docs.sentry.io/platforms/java/guides/jul/data-management/data-collected/ data-collection.user-info=false +# Configure other data categories here. # Enable logs logs.enabled=true diff --git a/platform-includes/getting-started-config/java.log4j2.mdx b/platform-includes/getting-started-config/java.log4j2.mdx index 34658fc595014..21571683b485f 100644 --- a/platform-includes/getting-started-config/java.log4j2.mdx +++ b/platform-includes/getting-started-config/java.log4j2.mdx @@ -71,6 +71,7 @@ If the DSN is not present in the `log4j2.xml` configuration, Sentry will attempt # Use Data Collection defaults but don't collect automatic user information. # https://docs.sentry.io/platforms/java/guides/log4j2/data-management/data-collected/ data-collection.user-info=false +# Configure other data categories here. // ___PRODUCT_OPTION_START___ logs logs.enabled=true // ___PRODUCT_OPTION_END___ logs diff --git a/platform-includes/getting-started-config/java.logback.mdx b/platform-includes/getting-started-config/java.logback.mdx index 85733ed6f2eb7..c68dff686d876 100644 --- a/platform-includes/getting-started-config/java.logback.mdx +++ b/platform-includes/getting-started-config/java.logback.mdx @@ -72,6 +72,7 @@ dsn=___PUBLIC_DSN___ # Use Data Collection defaults but don't collect automatic user information. # https://docs.sentry.io/platforms/java/guides/logback/data-management/data-collected/ data-collection.user-info=false +# Configure other data categories here. ``` You can also provide the DSN through the `sentry.dsn` system property or the `SENTRY_DSN` environment variable. [See the configuration page](/platforms/java/configuration/) for more details on external configuration. diff --git a/platform-includes/getting-started-config/java.mdx b/platform-includes/getting-started-config/java.mdx index 51f9fe073756e..a1d29626755d0 100644 --- a/platform-includes/getting-started-config/java.mdx +++ b/platform-includes/getting-started-config/java.mdx @@ -12,6 +12,7 @@ Sentry.init(options -> { // https://docs.sentry.io/platforms/java/data-management/data-collected/ DataCollection dataCollection = new DataCollection(); dataCollection.setUserInfo(false); + // Configure other data categories here. options.setDataCollection(dataCollection); // ___PRODUCT_OPTION_START___ performance @@ -45,6 +46,7 @@ Sentry.init { options -> // https://docs.sentry.io/platforms/java/data-management/data-collected/ options.dataCollection = DataCollection().apply { userInfo = false + // Configure other data categories here. } // ___PRODUCT_OPTION_START___ performance diff --git a/platform-includes/getting-started-config/java.servlet.mdx b/platform-includes/getting-started-config/java.servlet.mdx index f6db2e141416c..826e73dfa9232 100644 --- a/platform-includes/getting-started-config/java.servlet.mdx +++ b/platform-includes/getting-started-config/java.servlet.mdx @@ -24,6 +24,7 @@ public final class SentryInitializer implements ServletContainerInitializer { // https://docs.sentry.io/platforms/java/guides/servlet/data-management/data-collected/ DataCollection dataCollection = new DataCollection(); dataCollection.setUserInfo(false); + // Configure other data categories here. options.setDataCollection(dataCollection); // ___PRODUCT_OPTION_START___ performance @@ -66,6 +67,7 @@ class SentryInitializer : ServletContainerInitializer { // https://docs.sentry.io/platforms/java/guides/servlet/data-management/data-collected/ options.dataCollection = DataCollection().apply { userInfo = false + // Configure other data categories here. } // ___PRODUCT_OPTION_START___ performance diff --git a/platform-includes/getting-started-config/java.spring-boot.mdx b/platform-includes/getting-started-config/java.spring-boot.mdx index 4c20d31316b9a..83df69f0e8d54 100644 --- a/platform-includes/getting-started-config/java.spring-boot.mdx +++ b/platform-includes/getting-started-config/java.spring-boot.mdx @@ -9,6 +9,7 @@ sentry.dsn=___PUBLIC_DSN___ # Use Data Collection defaults but don't collect automatic user information. # https://docs.sentry.io/platforms/java/guides/spring-boot/data-management/data-collected/ sentry.data-collection.user-info=false +# Configure other data categories here. # ___PRODUCT_OPTION_START___ performance # Set traces_sample_rate to 1.0 to capture 100% @@ -37,6 +38,7 @@ sentry: # https://docs.sentry.io/platforms/java/guides/spring-boot/data-management/data-collected/ data-collection: user-info: false + # Configure other data categories here. # ___PRODUCT_OPTION_START___ performance # Set traces_sample_rate to 1.0 to capture 100% diff --git a/platform-includes/getting-started-config/java.spring.mdx b/platform-includes/getting-started-config/java.spring.mdx index 5b4770c2fe384..b0682f6a21e83 100644 --- a/platform-includes/getting-started-config/java.spring.mdx +++ b/platform-includes/getting-started-config/java.spring.mdx @@ -77,6 +77,7 @@ Configure Data Collection in `sentry.properties`. Setting any Data Collection fi ```properties {filename:sentry.properties} # Use Data Collection defaults but don't collect automatic user information. data-collection.user-info=false +# Configure other data categories here. ``` The DSN can be also provided through the system property `sentry.dsn`, environment variable `SENTRY_DSN` or the `dsn` property in `sentry.properties` file. [See the configuration page](/platforms/java/configuration/) for more details on external configuration. diff --git a/platform-includes/getting-started-config/opentelemetry/java.mdx b/platform-includes/getting-started-config/opentelemetry/java.mdx index f3899267484fc..083b36ef8c2eb 100644 --- a/platform-includes/getting-started-config/opentelemetry/java.mdx +++ b/platform-includes/getting-started-config/opentelemetry/java.mdx @@ -7,6 +7,7 @@ dsn=___PUBLIC_DSN___ # Use Data Collection defaults but don't collect automatic user information. # https://docs.sentry.io/platforms/java/data-management/data-collected/ data-collection.user-info=false +# Configure other data categories here. # ___PRODUCT_OPTION_START___ performance traces-sample-rate=1.0 # ___PRODUCT_OPTION_END___ performance From d275d8c22abb9793869ac9a0fcd46a9388a64ab7 Mon Sep 17 00:00:00 2001 From: Alexander Dinauer Date: Mon, 14 Sep 2026 09:18:32 +0200 Subject: [PATCH 7/8] docs(java): Update Data Collection release guidance Set Data Collection availability to 8.57.0 and clarify that enabling it ignores the legacy sendDefaultPii option. Co-Authored-By: Claude --- docs/platforms/android/configuration/options.mdx | 4 ++-- docs/platforms/java/common/configuration/options.mdx | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/platforms/android/configuration/options.mdx b/docs/platforms/android/configuration/options.mdx index d15b0e03cd83d..4a34df0127f5e 100644 --- a/docs/platforms/android/configuration/options.mdx +++ b/docs/platforms/android/configuration/options.mdx @@ -114,13 +114,13 @@ If you enable this option, be sure to manually remove what you don't want to sen - + 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`. -Passing an empty `DataCollection` or explicitly configuring any field enables Data Collection. All fields you don't configure use the defaults below, and `sendDefaultPii` no longer controls Data Collection categories. +Passing an empty `DataCollection` or explicitly configuring any field enables Data Collection. All fields you don't configure use the defaults below, and the `sendDefaultPii` option is ignored. diff --git a/docs/platforms/java/common/configuration/options.mdx b/docs/platforms/java/common/configuration/options.mdx index 2fd102d5e5324..a7a40ada6e645 100644 --- a/docs/platforms/java/common/configuration/options.mdx +++ b/docs/platforms/java/common/configuration/options.mdx @@ -116,13 +116,13 @@ Unencoded Logback messages aren't a Data Collection category. To include origina - + 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`. -Passing an empty `DataCollection` or explicitly configuring any field enables Data Collection. All fields you don't configure use the defaults below, and `sendDefaultPii` no longer controls Data Collection categories. +Passing an empty `DataCollection` or explicitly configuring any field enables Data Collection. All fields you don't configure use the defaults below, and the `sendDefaultPii` option is ignored. From 3e30bdbc16d7fa711fa4685963fba05b2f5ae056 Mon Sep 17 00:00:00 2001 From: Alexander Dinauer Date: Mon, 14 Sep 2026 13:02:08 +0200 Subject: [PATCH 8/8] docs(java): Clarify Data Collection configuration Explain how key-value collection behavior maps to code and external settings. Link header controls to option details and limit Spring Boot properties to its guide. Co-Authored-By: Claude --- .../android/configuration/options.mdx | 34 ++++++++------ .../data-management/data-collected.mdx | 2 +- .../java/common/configuration/options.mdx | 44 +++++++++++-------- .../common/data-management/data-collected.mdx | 2 +- 4 files changed, 48 insertions(+), 34 deletions(-) diff --git a/docs/platforms/android/configuration/options.mdx b/docs/platforms/android/configuration/options.mdx index 4a34df0127f5e..e238edb265265 100644 --- a/docs/platforms/android/configuration/options.mdx +++ b/docs/platforms/android/configuration/options.mdx @@ -124,17 +124,27 @@ Passing an empty `DataCollection` or explicitly configuring any field enables Da -| 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` | 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. | +| 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` | 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`: Don't collect the category. +- `DENY_LIST`: Collect values except those matching the built-in sensitive list or additional configured terms. +- `ALLOW_LIST`: 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 list includes terms such as `auth`, `token`, `secret`, `password`, `key`, `session`, and `identity`. Filtered values are replaced with `"[Filtered]"`. Custom deny-list terms extend the built-in list rather than replacing it. Configure Data Collection in `AndroidManifest.xml`: @@ -173,8 +183,6 @@ Supported manifest keys are: - `io.sentry.data-collection.graphql.variables` - `io.sentry.data-collection.file-paths` -The `cookies`, HTTP header, and URL query parameter fields support `off`, `deny_list`, and `allow_list`. Matching terms are comma-separated. Matching is partial and case-insensitive, and the built-in sensitive list always applies. Filtered values are replaced with `"[Filtered]"`. - For manual initialization, use the same Java API as the Java SDK: ```kotlin diff --git a/docs/platforms/android/data-management/data-collected.mdx b/docs/platforms/android/data-management/data-collected.mdx index 5b2af21db8cd7..d4df0cb605eab 100644 --- a/docs/platforms/android/data-management/data-collected.mdx +++ b/docs/platforms/android/data-management/data-collected.mdx @@ -16,7 +16,7 @@ Data Collection controls only data added automatically by SDK integrations. 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]"`. -Use `dataCollection.httpHeaders.request` and `dataCollection.httpHeaders.response` to control header collection. OkHttp, Ktor Client, and Apollo 3 and 4 can attach available request and response headers to captured HTTP client errors. +Configure `dataCollection.httpHeaders.request` and `dataCollection.httpHeaders.response` to control header collection. OkHttp, Ktor Client, and Apollo 3 and 4 can attach available request and response headers to captured HTTP client errors. Session Replay network details use [separate options](/platforms/android/session-replay/configuration/). diff --git a/docs/platforms/java/common/configuration/options.mdx b/docs/platforms/java/common/configuration/options.mdx index a7a40ada6e645..82ac312d2553c 100644 --- a/docs/platforms/java/common/configuration/options.mdx +++ b/docs/platforms/java/common/configuration/options.mdx @@ -126,17 +126,27 @@ Passing an empty `DataCollection` or explicitly configuring any field enables Da -| 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` | 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. | +| 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` | 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 `cookies`, `httpHeaders.request`, `httpHeaders.response`, and `urlQueryParams` fields support three modes: + +- `OFF`: Don't collect the category. +- `DENY_LIST`: Collect values except those matching the built-in sensitive list or additional configured terms. +- `ALLOW_LIST`: 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 list includes terms such as `auth`, `token`, `secret`, `password`, `key`, `session`, and `identity`. Filtered values are replaced with `"[Filtered]"`. Custom deny-list terms extend the built-in list rather than replacing it. Configure only the fields that differ from these defaults: @@ -160,14 +170,6 @@ Sentry.init( }); ``` -The `cookies`, `httpHeaders.request`, `httpHeaders.response`, and `urlQueryParams` fields support three modes: - -- `OFF`: Don't collect the category. -- `DENY_LIST`: Collect values except those matching the built-in sensitive list or additional configured terms. -- `ALLOW_LIST`: Include plaintext values only when their keys match configured terms. The built-in sensitive list still applies. - -Matching is partial and case-insensitive. The built-in list includes terms such as `auth`, `token`, `secret`, `password`, `key`, `session`, and `identity`. Filtered values are replaced with `"[Filtered]"`. Custom deny-list terms extend the built-in list rather than replacing it. - You can also configure Data Collection through external properties: ```properties {filename:sentry.properties} @@ -186,6 +188,8 @@ data-collection.file-paths=false Environment variables use the same names in uppercase with the `SENTRY_` prefix, for example, `SENTRY_DATA_COLLECTION_USER_INFO`, `SENTRY_DATA_COLLECTION_HTTP_BODIES`, and `SENTRY_DATA_COLLECTION_FILE_PATHS`. + + Spring Boot uses the `sentry.` prefix and kebab-case enum values: ```properties {filename:application.properties} @@ -197,6 +201,8 @@ sentry.data-collection.url-query-params.mode=off sentry.data-collection.file-paths=false ``` + + ### Migrating From `sendDefaultPii` Data Collection preserves existing applications until you opt in: diff --git a/docs/platforms/java/common/data-management/data-collected.mdx b/docs/platforms/java/common/data-management/data-collected.mdx index c0c222985ac5c..65016bb99e7ec 100644 --- a/docs/platforms/java/common/data-management/data-collected.mdx +++ b/docs/platforms/java/common/data-management/data-collected.mdx @@ -16,7 +16,7 @@ Data Collection controls only data added automatically by SDK integrations. 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]"`. -Use `dataCollection.httpHeaders.request` and `dataCollection.httpHeaders.response` to control header collection. Servlet and Spring integrations can collect incoming request headers. OkHttp, Ktor Client, and Apollo can attach request and response headers to captured HTTP client errors. +Configure `dataCollection.httpHeaders.request` and `dataCollection.httpHeaders.response` to control header collection. Servlet and Spring integrations can collect incoming request headers. OkHttp, Ktor Client, and Apollo can attach request and response headers to captured HTTP client errors. ## Cookies