Add spec for tracePropagationTargets SDK Option

src/docs/sdk/performance/dynamic-sampling-context.mdx

@@ -59,6 +59,8 @@ Baggage is a standard HTTP header with URI encoded key-value pairs.
 For the propagation of DSC, SDKs first read the DSC from the baggage header of incoming requests/messages.
 To propagate DSC to downstream SDKs/services, we create a baggage header (or modify an existing one) through HTTP request instrumentation.
 
+The `baggage` header should only be attached to an outgoing request if the request's URL matches at least one entry of the [`tracePropagationTargets`](/sdk/performance/#tracepropagationtargets) SDK option.
+
 <Alert level="info">
 
 Other vendors might also be using the `baggage` header.

src/docs/sdk/performance/index.mdx

@@ -16,6 +16,8 @@ Reference implementations:
 
 ## SDK Configuration
 
+This section describes the options SDKs should expose to configure tracing and performance monitoring.
+
 Tracing is enabled by setting either one of two new SDK config options, `tracesSampleRate` and `tracesSampler`. If not set, both default to `undefined`, making tracing opt-in.
 
 ### `tracesSampleRate`
@@ -32,6 +34,34 @@ Optionally, the `tracesSampler` callback can also return a boolean to force a sa
 
 See more about how sampling should be performed below.
 
+### `tracePropagationTargets`
+
+Sentry SDKs propagate trace information to downstream SDKs via headers on outgoing HTTP requests. The `tracePropagationTargets` option gives users a mechanism of controlling to which outgoing HTTP requests these headers should be attached. For example, users can specify this property to keep trace propagation within their infrastructure, thereby preventing data within the headers from being sent to third party services.
+
+This option takes an array of strings and/or regular expressions, and SDKs should only add trace headers to an outgoing request if the request's URL matches (or, in the case of string literals, contains) at least one of the items from the array.
+
+SDKs may choose a default value which makes sense for their use case. Most SDKs default to the regex `/.*/` (meaning they attach headers to all outgoing requests), but deviation is allowed if necessary. For example, because of CORS, browser-based SDKs default to only adding headers to domain-internal requests.
+
+See [`sentry-trace`](#header-sentry-trace) and [`baggage`](/sdk/performance/dynamic-sampling-context/#baggage) for more details on the individual headers which are attached to outgoing requests.
+
+#### Example
+
+The following example shows which URLs of outgoing requests would (not) match a given `tracePropagationTargets` array:
+
+```JS
+// Entries can be strings or regex
+tracePropagationTargets: ['localhost', /^\// ,/myApi.com\/v[2-4]/]
+
+URLs matching: 'localhost:8443/api/users', '/api/envelopes', 'myApi.com/v2/projects'
+URLs not matching: 'someHost.com/data', 'myApi.com/v1/projects'
+```
+
+<Alert level="info" title="Deprecation of tracingOrigins">
+
+This Option replaces the non-standardized `tracingOrigins` option which was previously used in some SDKs. SDKs that support `tracingOrigins` are encouraged to deprecate and and eventually remove `tracingOrigins` in favour `tracePropagationTargets`. In case both options are specified by users, SDKs should only rely on the `tracePropagationTargets` array.
+
+</Alert>
+
 ### `maxSpans`
 
 Because transaction payloads have a maximum size enforced on the ingestion side, SDKs should limit the number of spans that are attached to a transaction. This is similar to how breadcrumbs and other arbitrarily sized lists are limited to prevent accidental misuse. If new spans are added once the maximum is reached, the SDK should drop the spans and ideally use the internal logging to help debugging.
@@ -160,6 +190,8 @@ To offer a minimal compatibility with the [W3C `traceparent` header](https://www
 To avoid confusion with the W3C `traceparent` header (to which our header is similar but not identical), we call it simply `sentry-trace`.
 No version is being defined in the header.
 
+The `sentry-trace` header should only be attached to an outgoing request if the request's URL matches at least one entry of the [`tracePropagationTargets`](#tracepropagationtargets) SDK option.
+
 ### The `sampled` Value
 
 To simplify processing, the value consists of a single (optional) character. The possible values are: