diff --git a/develop-docs/sdk/foundations/trace-propagation/index.mdx b/develop-docs/sdk/foundations/trace-propagation/index.mdx index 29935c3ee890f..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 @@ -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 Sampling Rate Propagation section - version: 1.9.0 date: 2026-02-24 summary: Consolidated into foundations/trace-propagation @@ -248,6 +251,22 @@ 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. + +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. + + + ### Default Propagation (No Tracing Config)