diff --git a/src/docs/sdk/performance/dynamic-sampling-context.mdx b/src/docs/sdk/performance/dynamic-sampling-context.mdx index 83cd8cc207..7f388a36ea 100644 --- a/src/docs/sdk/performance/dynamic-sampling-context.mdx +++ b/src/docs/sdk/performance/dynamic-sampling-context.mdx @@ -106,6 +106,28 @@ After the DSC of a particular trace has been frozen, API calls like `set_user` o Dynamic Sampling Context is sent to Sentry via the `trace` envelope header and is propagated to downstream SDKs via a baggage header. All of the values in the payloads below are required (non-optional) in a sense, that when they are known to an SDK at the time a transaction envelope is sent to Sentry, or at the time a baggage header is propagated, they must also be included in said envelope or baggage. + +### Handling Sensitive Data and PII + + + +The currently specified solution is subject to change and will be revisited, once all SDKs implemented a mechanism of controlling where DSC and tracing data should be propagated to. +This mechanism is still up for discussion and implementation but it will be similar to the `tracingOrigins` property that is already used in some SDKs right now. +In the meantime, the solution below should be adopted from all SDKs to handle PII concerns. + + + +It should be noted that DSC holds potentially sensitive data, such as PII, which needs to be handled carefully. + +Therefore, the **only exception** to the rule that all available DSC values must be collected at DSC +population time, is the `user_id` field. +To avoid this sensitive information being leaked to third parties, `user_id` should only be added to the DSC, if the `send_default_pii` option was enabled in the SDK's init options. +Note that this only applies for the head-of-trace SDK that populates the DSC content. +In case downstream SDKs receive a `user_id` in incoming DSC, they should continue to propagate it. +The rationale behind this is that incoming DSC [must be frozen](#freezing-dynamic-sampling-context) and users must make DS rules based on the head SDK's DSC data anyway. + +#### Strictly required values + In any case, `trace_id`, `public_key`, and `sample_rate` should always be known to an SDK, so these values are strictly required. ### Envelope Header @@ -118,7 +140,7 @@ The value of this envelope header is a JSON object with the following fields: - `sample_rate` (string) - The sample rate as defined by the user on the SDK. This string should always be a number between (and including) 0 and 1 in basic float notation (`0.04242`) - no funky business like exponents or anything similar. If a `tracesSampler` callback was used for the sampling decision, its result should be used for `sample_rate` instead of the `tracesSampleRate` from `SentryOptions`. In case `tracesSampler` returns `True` it should be sent as `1.0`, `False` should be sent as `0.0`. - `release` (string) - The release name as specified in client options`. - `environment` (string) - The environment name as specified in client options. -- `user_id` (string) - User ID as set by the user with `scope.set_user`. +- `user_id` (string) - User ID as set by the user with `scope.set_user`. **Only included, if [`send_default_pii`](#handling-sensitive-data-and-pii) is enabled.** - `user_segment` (string) - User segment as set by the user with `scope.set_user`. - `transaction` (string) - The transaction name set on the scope. @@ -133,7 +155,7 @@ SDKs may use the following keys to set entries on `baggage` HTTP headers: - `sentry-sample_rate` - `sentry-release` - `sentry-environment` -- `sentry-user_id` +- `sentry-user_id` - **Only included, if [`send_default_pii`](#handling-sensitive-data-and-pii) is enabled.** - `sentry-user_segment` - `sentry-transaction`