From 543c15a9adfc668c8aacc29ea899f6285f63068e Mon Sep 17 00:00:00 2001 From: Lukas Stracke Date: Thu, 30 Jun 2022 11:09:14 +0200 Subject: [PATCH 1/4] ref(DSC): Only include user_id if send-default-pii option is enabled --- src/docs/sdk/performance/dynamic-sampling-context.mdx | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/src/docs/sdk/performance/dynamic-sampling-context.mdx b/src/docs/sdk/performance/dynamic-sampling-context.mdx index 83cd8cc207..2d71d170d3 100644 --- a/src/docs/sdk/performance/dynamic-sampling-context.mdx +++ b/src/docs/sdk/performance/dynamic-sampling-context.mdx @@ -106,6 +106,10 @@ 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. + +The **only exception** is the `user_id` field. +To avoid sensitive data being leaked to third parties, `user_id` should only be included, if the `send-default-pii` option was enabled in the init options. + 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 +122,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` 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 +137,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` is enabled** - `sentry-user_segment` - `sentry-transaction` From efbc5a15b8f55e8ad150fdd9c0171d0bf832b030 Mon Sep 17 00:00:00 2001 From: Lukas Stracke Date: Fri, 1 Jul 2022 10:50:14 +0200 Subject: [PATCH 2/4] Address user_id handling in head vs. downstream SDKs --- src/docs/sdk/performance/dynamic-sampling-context.mdx | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/src/docs/sdk/performance/dynamic-sampling-context.mdx b/src/docs/sdk/performance/dynamic-sampling-context.mdx index 2d71d170d3..d22e2d5e0d 100644 --- a/src/docs/sdk/performance/dynamic-sampling-context.mdx +++ b/src/docs/sdk/performance/dynamic-sampling-context.mdx @@ -108,7 +108,10 @@ Dynamic Sampling Context is sent to Sentry via the `trace` envelope header and i 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. The **only exception** is the `user_id` field. -To avoid sensitive data being leaked to third parties, `user_id` should only be included, if the `send-default-pii` option was enabled in the init options. +To avoid sensitive data 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. In any case, `trace_id`, `public_key`, and `sample_rate` should always be known to an SDK, so these values are strictly required. From 8679a0d0612b97e66309da2010e3a60ea48d745b Mon Sep 17 00:00:00 2001 From: Lukas Stracke Date: Fri, 1 Jul 2022 10:54:25 +0200 Subject: [PATCH 3/4] rename send-default-pii to send_default_pii --- src/docs/sdk/performance/dynamic-sampling-context.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/docs/sdk/performance/dynamic-sampling-context.mdx b/src/docs/sdk/performance/dynamic-sampling-context.mdx index d22e2d5e0d..a3524fbf96 100644 --- a/src/docs/sdk/performance/dynamic-sampling-context.mdx +++ b/src/docs/sdk/performance/dynamic-sampling-context.mdx @@ -108,7 +108,7 @@ Dynamic Sampling Context is sent to Sentry via the `trace` envelope header and i 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. The **only exception** is the `user_id` field. -To avoid sensitive data 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. +To avoid sensitive data 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. @@ -125,7 +125,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`. **Only included, if `send-default-pii` is enabled** +- `user_id` (string) - User ID as set by the user with `scope.set_user`. **Only included, if `send_default_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. @@ -140,7 +140,7 @@ SDKs may use the following keys to set entries on `baggage` HTTP headers: - `sentry-sample_rate` - `sentry-release` - `sentry-environment` -- `sentry-user_id` - **Only included, if `send-default-pii` is enabled** +- `sentry-user_id` - **Only included, if `send_default_pii` is enabled** - `sentry-user_segment` - `sentry-transaction` From e8180943ba578bdf314298a03513d886778309f7 Mon Sep 17 00:00:00 2001 From: Lukas Stracke Date: Fri, 1 Jul 2022 14:19:40 +0200 Subject: [PATCH 4/4] change structure and add alert with subject to change notice --- .../performance/dynamic-sampling-context.mdx | 27 ++++++++++++++----- 1 file changed, 21 insertions(+), 6 deletions(-) diff --git a/src/docs/sdk/performance/dynamic-sampling-context.mdx b/src/docs/sdk/performance/dynamic-sampling-context.mdx index a3524fbf96..7f388a36ea 100644 --- a/src/docs/sdk/performance/dynamic-sampling-context.mdx +++ b/src/docs/sdk/performance/dynamic-sampling-context.mdx @@ -107,11 +107,26 @@ Dynamic Sampling Context is sent to Sentry via the `trace` envelope header and i 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. -The **only exception** is the `user_id` field. -To avoid sensitive data 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. +### 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. +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. @@ -125,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`. **Only included, if `send_default_pii` is enabled** +- `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. @@ -140,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` - **Only included, if `send_default_pii` is enabled** +- `sentry-user_id` - **Only included, if [`send_default_pii`](#handling-sensitive-data-and-pii) is enabled.** - `sentry-user_segment` - `sentry-transaction`