From 21c7c02234c5fe94735030422946b94254fc4eda Mon Sep 17 00:00:00 2001 From: Lukas Stracke Date: Mon, 18 Jul 2022 15:19:07 +0200 Subject: [PATCH 1/6] Add spec for tracePropagationTargets SDK Option --- .../performance/dynamic-sampling-context.mdx | 2 + src/docs/sdk/performance/index.mdx | 39 +++++++++++++++++++ 2 files changed, 41 insertions(+) diff --git a/src/docs/sdk/performance/dynamic-sampling-context.mdx b/src/docs/sdk/performance/dynamic-sampling-context.mdx index 2873e3b219..2c57716475 100644 --- a/src/docs/sdk/performance/dynamic-sampling-context.mdx +++ b/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`](#tracepropagationtargets) SDK option (or its fallback default behaviour). + Other vendors might also be using the `baggage` header. diff --git a/src/docs/sdk/performance/index.mdx b/src/docs/sdk/performance/index.mdx index ddd531921c..46a5fe3f03 100644 --- a/src/docs/sdk/performance/index.mdx +++ b/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,41 @@ 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 via headers of outgoing Http requests to downstream SDKs (see [`sentry-trace`](#header-sentry-trace) and [`baggage`](/sdk/performance/dynamic-sampling-context/#baggage) for more details). +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 stopping it from being sent to third party services. + +This option takes an array of strings or regular expressions to match against the URLs of outgoing requests. +If this option is specified by users, SDKs may only add the trace headers to a request if the the request's URL matches (contains) at least one of the items from the array. + +#### Example + +```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' +``` + +#### Default Behaviour + +If the `tracePropagationTargets` option is not specified by users, SDKs should fall back to their default behaviour for trace propagation. +This default behaviour is not standardized and can vary across SDKs. +For instance, Server-side SDKs may propagate trace headers to all outgoing requests by default while client-side SDKs (e.g. Javascript) can fall back to a default array of allowed domains (e.g. `localhost` and `/^\//` in JavaScript). +Choosing a sensible default behaviour is up to the SDK maintainers, however, special limitations, such as CORS issues for frontend web SDKs must be considered. +SDKs that previously supported the `tracingOrigins` property (see deprecation notice below) can continue using the already established default behaviour for `tracePropagationTargets` + + + +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. + + + ### `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 +197,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 (or its fallback default behaviour). + ### The `sampled` Value To simplify processing, the value consists of a single (optional) character. The possible values are: From a9e5d8af49ace746d9497ccd2668f04420e2bbb7 Mon Sep 17 00:00:00 2001 From: Lukas Stracke Date: Mon, 18 Jul 2022 15:34:50 +0200 Subject: [PATCH 2/6] fix broken link --- src/docs/sdk/performance/dynamic-sampling-context.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/docs/sdk/performance/dynamic-sampling-context.mdx b/src/docs/sdk/performance/dynamic-sampling-context.mdx index 2c57716475..f9bdc74dd2 100644 --- a/src/docs/sdk/performance/dynamic-sampling-context.mdx +++ b/src/docs/sdk/performance/dynamic-sampling-context.mdx @@ -59,7 +59,7 @@ 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`](#tracepropagationtargets) SDK option (or its fallback default behaviour). +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 (or its fallback default behaviour). From 44a023bbcdf934a1a3527d8faaa08207feca1653 Mon Sep 17 00:00:00 2001 From: Lukas Stracke Date: Tue, 19 Jul 2022 10:04:33 +0200 Subject: [PATCH 3/6] Remove fallback behaviour phrases Co-authored-by: Katie Byers --- src/docs/sdk/performance/dynamic-sampling-context.mdx | 2 +- src/docs/sdk/performance/index.mdx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/src/docs/sdk/performance/dynamic-sampling-context.mdx b/src/docs/sdk/performance/dynamic-sampling-context.mdx index f9bdc74dd2..f67cca35ea 100644 --- a/src/docs/sdk/performance/dynamic-sampling-context.mdx +++ b/src/docs/sdk/performance/dynamic-sampling-context.mdx @@ -59,7 +59,7 @@ 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 (or its fallback default behaviour). +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. diff --git a/src/docs/sdk/performance/index.mdx b/src/docs/sdk/performance/index.mdx index 46a5fe3f03..b55765455d 100644 --- a/src/docs/sdk/performance/index.mdx +++ b/src/docs/sdk/performance/index.mdx @@ -197,7 +197,7 @@ 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 (or its fallback default behaviour). +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 From 0c98f1c4446f7f3aa8292a36f2754e9d2240a262 Mon Sep 17 00:00:00 2001 From: Lukas Stracke Date: Tue, 19 Jul 2022 10:37:10 +0200 Subject: [PATCH 4/6] adjust intro paragraph arrangement --- src/docs/sdk/performance/index.mdx | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/src/docs/sdk/performance/index.mdx b/src/docs/sdk/performance/index.mdx index b55765455d..ffb020427b 100644 --- a/src/docs/sdk/performance/index.mdx +++ b/src/docs/sdk/performance/index.mdx @@ -36,12 +36,13 @@ See more about how sampling should be performed below. ### `tracePropagationTargets` -Sentry SDKs propagate trace information via headers of outgoing Http requests to downstream SDKs (see [`sentry-trace`](#header-sentry-trace) and [`baggage`](/sdk/performance/dynamic-sampling-context/#baggage) for more details). -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 stopping it from being sent to third party services. +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 or regular expressions to match against the URLs of outgoing requests. -If this option is specified by users, SDKs may only add the trace headers to a request if the the request's URL matches (contains) at least one of the items from the array. +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. + +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 From 37d7a3364105ef19b7b3031949fce62e10f1422a Mon Sep 17 00:00:00 2001 From: Lukas Stracke Date: Tue, 19 Jul 2022 10:57:11 +0200 Subject: [PATCH 5/6] replace default paragraph section wit with default value paragraph --- src/docs/sdk/performance/index.mdx | 16 +++++++--------- 1 file changed, 7 insertions(+), 9 deletions(-) diff --git a/src/docs/sdk/performance/index.mdx b/src/docs/sdk/performance/index.mdx index ffb020427b..ce0704b911 100644 --- a/src/docs/sdk/performance/index.mdx +++ b/src/docs/sdk/performance/index.mdx @@ -42,26 +42,24 @@ For example, users can specify this property to keep trace propagation within th 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 +// 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' ``` -#### Default Behaviour - -If the `tracePropagationTargets` option is not specified by users, SDKs should fall back to their default behaviour for trace propagation. -This default behaviour is not standardized and can vary across SDKs. -For instance, Server-side SDKs may propagate trace headers to all outgoing requests by default while client-side SDKs (e.g. Javascript) can fall back to a default array of allowed domains (e.g. `localhost` and `/^\//` in JavaScript). -Choosing a sensible default behaviour is up to the SDK maintainers, however, special limitations, such as CORS issues for frontend web SDKs must be considered. -SDKs that previously supported the `tracingOrigins` property (see deprecation notice below) can continue using the already established default behaviour for `tracePropagationTargets` - This Option replaces the non-standardized `tracingOrigins` option which was previously used in some SDKs. From bd4a295e5f155d08c19f09aecd9ff18d2f82a6e3 Mon Sep 17 00:00:00 2001 From: Lukas Stracke Date: Wed, 20 Jul 2022 10:08:10 +0200 Subject: [PATCH 6/6] remove newlines after each sentence --- src/docs/sdk/performance/index.mdx | 14 ++++---------- 1 file changed, 4 insertions(+), 10 deletions(-) diff --git a/src/docs/sdk/performance/index.mdx b/src/docs/sdk/performance/index.mdx index ce0704b911..e1817c48e8 100644 --- a/src/docs/sdk/performance/index.mdx +++ b/src/docs/sdk/performance/index.mdx @@ -36,21 +36,17 @@ 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. +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. +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. +The following example shows which URLs of outgoing requests would (not) match a given `tracePropagationTargets` array: ```JS // Entries can be strings or regex @@ -62,9 +58,7 @@ URLs not matching: 'someHost.com/data', 'myApi.com/v1/projects' -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. +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.