From 956cd038675a3a764c9cc4e82c93918c4eece492 Mon Sep 17 00:00:00 2001 From: Ivana Kellyer Date: Mon, 6 Jul 2026 13:10:15 +0200 Subject: [PATCH 1/6] feat(devdocs): Add guidance wrt to updating `sample_rate` At some point last year, we implemented sample rate updating under specific conditions in most SDKs. This is missing from the spec. Original implementation ticket: https://github.com/getsentry/team-sdks/issues/117 --- .../sdk/foundations/trace-propagation/index.mdx | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/develop-docs/sdk/foundations/trace-propagation/index.mdx b/develop-docs/sdk/foundations/trace-propagation/index.mdx index 29935c3ee890f..643d32141a4f1 100644 --- a/develop-docs/sdk/foundations/trace-propagation/index.mdx +++ b/develop-docs/sdk/foundations/trace-propagation/index.mdx @@ -10,6 +10,9 @@ spec_depends_on: - id: sdk/foundations/state-management/scopes version: ">=1.0.0" spec_changelog: + - version: 1.10.0 + date: 2026-07-06 + summary: Added sample_rate updating in baggage - version: 1.9.0 date: 2026-02-24 summary: Consolidated into foundations/trace-propagation @@ -248,6 +251,20 @@ A transaction's sampling decision **MUST** be passed to all of its children, inc + + +### Sampling Rate Propagation + +If there is an incoming `sample_rate`, it SHOULD be updated in the baggage if: +- an explicit sampling decision is forced, e.g. `startTransaction(sampled: true)` +- the `tracesSampler` is invoked +- the `tracesSampleRate` is used +- the SDK downsamples due to backpressure + +In other words, whenever the SDK's effective sampling rate overrides the incoming `sample_rate`, it needs to be updated, even if the baggage is considered immutable. + + + ### Default Propagation (No Tracing Config) From e32bf5671fea10417f02e30143063b35aad0ff02 Mon Sep 17 00:00:00 2001 From: Ivana Kellyer Date: Mon, 6 Jul 2026 13:15:42 +0200 Subject: [PATCH 2/6] fixes --- develop-docs/sdk/foundations/trace-propagation/index.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/develop-docs/sdk/foundations/trace-propagation/index.mdx b/develop-docs/sdk/foundations/trace-propagation/index.mdx index 643d32141a4f1..7fc6759dfc273 100644 --- a/develop-docs/sdk/foundations/trace-propagation/index.mdx +++ b/develop-docs/sdk/foundations/trace-propagation/index.mdx @@ -12,7 +12,7 @@ spec_depends_on: spec_changelog: - version: 1.10.0 date: 2026-07-06 - summary: Added sample_rate updating in baggage + summary: Added Sampling Rate Propagation section - version: 1.9.0 date: 2026-02-24 summary: Consolidated into foundations/trace-propagation @@ -251,11 +251,11 @@ A transaction's sampling decision **MUST** be passed to all of its children, inc - + ### Sampling Rate Propagation -If there is an incoming `sample_rate`, it SHOULD be updated in the baggage if: +If there is an incoming `sample_rate`, it **SHOULD** be updated in the baggage if: - an explicit sampling decision is forced, e.g. `startTransaction(sampled: true)` - the `tracesSampler` is invoked - the `tracesSampleRate` is used From ba6fe2f4b284db28d1435b6f4261ca919ae0d62a Mon Sep 17 00:00:00 2001 From: Ivana Kellyer Date: Mon, 6 Jul 2026 13:16:45 +0200 Subject: [PATCH 3/6] fix section id --- develop-docs/sdk/foundations/trace-propagation/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/develop-docs/sdk/foundations/trace-propagation/index.mdx b/develop-docs/sdk/foundations/trace-propagation/index.mdx index 7fc6759dfc273..19f189fbd40c3 100644 --- a/develop-docs/sdk/foundations/trace-propagation/index.mdx +++ b/develop-docs/sdk/foundations/trace-propagation/index.mdx @@ -251,7 +251,7 @@ A transaction's sampling decision **MUST** be passed to all of its children, inc - + ### Sampling Rate Propagation From e9801c12629e8ce99aba4f2e88b2d2ef09547fb3 Mon Sep 17 00:00:00 2001 From: Ivana Kellyer Date: Mon, 6 Jul 2026 13:25:42 +0200 Subject: [PATCH 4/6] clarification --- develop-docs/sdk/foundations/trace-propagation/index.mdx | 2 ++ 1 file changed, 2 insertions(+) diff --git a/develop-docs/sdk/foundations/trace-propagation/index.mdx b/develop-docs/sdk/foundations/trace-propagation/index.mdx index 19f189fbd40c3..4ae30a204bed7 100644 --- a/develop-docs/sdk/foundations/trace-propagation/index.mdx +++ b/develop-docs/sdk/foundations/trace-propagation/index.mdx @@ -263,6 +263,8 @@ If there is an incoming `sample_rate`, it **SHOULD** be updated in the baggage i In other words, whenever the SDK's effective sampling rate overrides the incoming `sample_rate`, it needs to be updated, even if the baggage is considered immutable. +Note that this rule only takes into account the effective sampling rate. If there is a `tracesSampleRate` defined, and there's an incoming sampling decision, the local `tracesSampleRate` is not the effective sampling rate -- it's ignored as the parent sampling decision takes precedence. In that case, the incoming `sample_rate` MUST NOT be updated. + From 57709528f8c32115b2a8821de1e2417fcb3a0629 Mon Sep 17 00:00:00 2001 From: Ivana Kellyer Date: Mon, 6 Jul 2026 13:27:23 +0200 Subject: [PATCH 5/6] . --- develop-docs/sdk/foundations/trace-propagation/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/develop-docs/sdk/foundations/trace-propagation/index.mdx b/develop-docs/sdk/foundations/trace-propagation/index.mdx index 4ae30a204bed7..c45d34faf7eec 100644 --- a/develop-docs/sdk/foundations/trace-propagation/index.mdx +++ b/develop-docs/sdk/foundations/trace-propagation/index.mdx @@ -263,7 +263,7 @@ If there is an incoming `sample_rate`, it **SHOULD** be updated in the baggage i In other words, whenever the SDK's effective sampling rate overrides the incoming `sample_rate`, it needs to be updated, even if the baggage is considered immutable. -Note that this rule only takes into account the effective sampling rate. If there is a `tracesSampleRate` defined, and there's an incoming sampling decision, the local `tracesSampleRate` is not the effective sampling rate -- it's ignored as the parent sampling decision takes precedence. In that case, the incoming `sample_rate` MUST NOT be updated. +Note that this rule only takes into account the effective sampling rate, i.e., the sampling rate that was actually used to make the sampling decision. If there is a `tracesSampleRate` defined, and there's an incoming sampling decision, the local `tracesSampleRate` is not the effective sampling rate -- it's ignored as the parent sampling decision takes precedence. In that case, the incoming `sample_rate` MUST NOT be updated. From c746f62a624b7beabaa98f23ead6ff52de9ce595 Mon Sep 17 00:00:00 2001 From: Ivana Kellyer Date: Mon, 6 Jul 2026 13:27:48 +0200 Subject: [PATCH 6/6] update version --- develop-docs/sdk/foundations/trace-propagation/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/develop-docs/sdk/foundations/trace-propagation/index.mdx b/develop-docs/sdk/foundations/trace-propagation/index.mdx index c45d34faf7eec..da7f27f298227 100644 --- a/develop-docs/sdk/foundations/trace-propagation/index.mdx +++ b/develop-docs/sdk/foundations/trace-propagation/index.mdx @@ -2,7 +2,7 @@ title: Trace Propagation description: How SDKs propagate trace context between services via headers, metadata, and environment variables. spec_id: sdk/foundations/trace-propagation -spec_version: 1.9.0 +spec_version: 1.10.0 spec_status: stable spec_depends_on: - id: sdk/foundations/transport/envelopes