Feature: Add support for DD_TRACE_PROPAGATION_BEHAVIOR_EXTRACT by MilanGarnier · Pull Request #5844 · DataDog/dd-trace-rb

MilanGarnier · 2026-06-01T15:11:25Z

What does this PR do?

Implements DD_TRACE_PROPAGATION_BEHAVIOR_EXTRACT for dd-trace-rb.

Three modes:

continue (default): existing behavior -- incoming trace context is used as the local trace context. Baggage is propagated.
restart: starts a new trace with a fresh trace ID and sampling decision. The incoming context is referenced via a span link with reason=propagation_behavior_extract. Baggage is propagated.
ignore: discards the entire incoming trace context. Returns nil, nil from Extract() so callers produce a fresh root span with no parent, no span links, and no baggage.

Motivation:

RFC on Trace Context Propagation Extraction Modes
System-tests PR: DataDog/system-tests#6757

Change log entry

Yes. Tracing: Adds support for the DD_TRACE_PROPAGATION_BEHAVIOR_EXTRACT configuration key. The default value is continue (preserving previous behavior), but the new restart/ignore values allow new traces to be started, either keeping or discarding baggage and trace context.

Additional Notes:

If there needs to be more testing implemented let me know, this is my first PR here so I am still unsure about the amount of testing that needs to be done

How to test the change?

System-tests PR: feat(ruby) : enable DD_TRACE_PROPAGATION_BEHAVIOR_EXTRACT system-tests#7076
Add testing propagation_spec.rb for ignore and restart
OTel logic needed to be slightly modified to account for a nil trace_id being passed as an argument, a unit test has been added to check that a new id was being created. test

dd-octo-sts · 2026-06-01T15:11:44Z

Thank you for updating Change log entry section 👏

^{Visited at: 2026-06-05 13:04:49 UTC}

datadog-prod-us1-5 · 2026-06-01T15:15:31Z

Tests

🎉 All green!

🧪 All tests passed
❄️ No new flaky tests detected

🎯 Code Coverage (details)
• Patch Coverage: 96.62%
• Overall Coverage: 89.90% (+0.04%)

_{This comment will be updated automatically if new data arrives.

🔗 Commit SHA: 42d832d | Docs | Datadog PR Page | Give us feedback!}

dd-octo-sts · 2026-06-02T07:58:22Z

Typing analysis

Note: Ignored files are excluded from the next sections.

Untyped methods

This PR introduces 1 partially typed method, and clears 1 untyped method.

Untyped methods (+0-1)

✅ Cleared:

sig/datadog/tracing/trace_digest.rbs:26
└── def initialize: (?span_id: untyped?, ?span_name: untyped?, ?span_resource: untyped?, ?span_service: untyped?, ?span_type: untyped?, ?trace_distributed_tags: untyped?, ?trace_hostname: untyped?, ?trace_id: untyped?, ?trace_name: untyped?, ?trace_origin: untyped?, ?trace_process_id: untyped?, ?trace_resource: untyped?, ?trace_runtime_id: untyped?, ?trace_sampling_priority: untyped?, ?trace_service: untyped?, ?trace_distributed_id: untyped?, ?trace_flags: untyped?, ?trace_state: untyped?, ?trace_state_unknown_fields: untyped?, ?span_remote: untyped?, ?baggage: untyped?) -> void

Partially typed methods (+1-0)

❌ Introduced:

sig/datadog/tracing/trace_digest.rbs:27
└── def initialize: (?span_id: untyped?, ?span_name: untyped?, ?span_resource: untyped?, ?span_service: untyped?, ?span_type: untyped?, ?span_links: ::Array[SpanLink]?, ?trace_distributed_tags: untyped?, ?trace_hostname: untyped?, ?trace_id: untyped?, ?trace_name: untyped?, ?trace_origin: untyped?, ?trace_process_id: untyped?, ?trace_resource: untyped?, ?trace_runtime_id: untyped?, ?trace_sampling_priority: untyped?, ?trace_service: untyped?, ?trace_distributed_id: untyped?, ?trace_flags: untyped?, ?trace_state: untyped?, ?trace_state_unknown_fields: untyped?, ?span_remote: untyped?, ?baggage: untyped?) -> void

Untyped other declarations

This PR introduces 16 untyped other declarations, and clears 16 untyped other declarations. It increases the percentage of typed other declarations from 82.62% to 82.63% (+0.01%).

Untyped other declarations (+16-16)

❌ Introduced:

sig/datadog/tracing/trace_digest.rbs:10
└── attr_reader trace_distributed_tags: untyped
sig/datadog/tracing/trace_digest.rbs:11
└── attr_reader trace_hostname: untyped
sig/datadog/tracing/trace_digest.rbs:12
└── attr_reader trace_id: untyped
sig/datadog/tracing/trace_digest.rbs:13
└── attr_reader trace_name: untyped
sig/datadog/tracing/trace_digest.rbs:14
└── attr_reader trace_origin: untyped
sig/datadog/tracing/trace_digest.rbs:15
└── attr_reader trace_process_id: untyped
sig/datadog/tracing/trace_digest.rbs:16
└── attr_reader trace_resource: untyped
sig/datadog/tracing/trace_digest.rbs:17
└── attr_reader trace_runtime_id: untyped
sig/datadog/tracing/trace_digest.rbs:18
└── attr_reader trace_sampling_priority: untyped
sig/datadog/tracing/trace_digest.rbs:19
└── attr_reader trace_service: untyped
sig/datadog/tracing/trace_digest.rbs:20
└── attr_reader trace_distributed_id: untyped
sig/datadog/tracing/trace_digest.rbs:21
└── attr_reader trace_flags: untyped
sig/datadog/tracing/trace_digest.rbs:22
└── attr_reader trace_state: untyped
sig/datadog/tracing/trace_digest.rbs:23
└── attr_reader trace_state_unknown_fields: untyped
sig/datadog/tracing/trace_digest.rbs:24
└── attr_reader span_remote: untyped
sig/datadog/tracing/trace_digest.rbs:25
└── attr_reader baggage: untyped

✅ Cleared:

sig/datadog/tracing/trace_digest.rbs:9
└── attr_reader trace_distributed_tags: untyped
sig/datadog/tracing/trace_digest.rbs:10
└── attr_reader trace_hostname: untyped
sig/datadog/tracing/trace_digest.rbs:11
└── attr_reader trace_id: untyped
sig/datadog/tracing/trace_digest.rbs:12
└── attr_reader trace_name: untyped
sig/datadog/tracing/trace_digest.rbs:13
└── attr_reader trace_origin: untyped
sig/datadog/tracing/trace_digest.rbs:14
└── attr_reader trace_process_id: untyped
sig/datadog/tracing/trace_digest.rbs:15
└── attr_reader trace_resource: untyped
sig/datadog/tracing/trace_digest.rbs:16
└── attr_reader trace_runtime_id: untyped
sig/datadog/tracing/trace_digest.rbs:17
└── attr_reader trace_sampling_priority: untyped
sig/datadog/tracing/trace_digest.rbs:18
└── attr_reader trace_service: untyped
sig/datadog/tracing/trace_digest.rbs:19
└── attr_reader trace_distributed_id: untyped
sig/datadog/tracing/trace_digest.rbs:20
└── attr_reader trace_flags: untyped
sig/datadog/tracing/trace_digest.rbs:21
└── attr_reader trace_state: untyped
sig/datadog/tracing/trace_digest.rbs:22
└── attr_reader trace_state_unknown_fields: untyped
sig/datadog/tracing/trace_digest.rbs:23
└── attr_reader span_remote: untyped
sig/datadog/tracing/trace_digest.rbs:24
└── attr_reader baggage: untyped

If you believe a method or an attribute is rightfully untyped or partially typed, you can add # untyped:accept on the line before the definition to remove it from the stats.

pr-commenter · 2026-06-02T10:49:05Z

Benchmarks

Benchmark execution time: 2026-06-19 08:41:26

Comparing candidate commit 42d832d in PR branch milangarnier-feature_DD_TRACE_PROPAGATION_BEHAVIOR_EXTRACT with baseline commit f5d5c42 in branch master.

Found 0 performance improvements and 1 performance regressions! Performance is the same for 47 metrics, 1 unstable metrics.

Explanation

This is an A/B test comparing a candidate commit's performance against that of a baseline commit. Performance changes are noted in the tables below as:

🟩 = significantly better candidate vs. baseline
🟥 = significantly worse candidate vs. baseline

We compute a confidence interval (CI) over the relative difference of means between metrics from the candidate and baseline commits, considering the baseline as the reference.

If the CI is entirely outside the configured SIGNIFICANT_IMPACT_THRESHOLD (or the deprecated UNCONFIDENCE_THRESHOLD), the change is considered significant.

Feel free to reach out to #apm-benchmarking-platform on Slack if you have any questions.

More details about the CI and significant changes

You can imagine this CI as a range of values that is likely to contain the true difference of means between the candidate and baseline commits.

CIs of the difference of means are often centered around 0%, because often changes are not that big:

---------------------------------(------|---^--------)-------------------------------->
                              -0.6%    0%  0.3%     +1.2%
                                 |          |        |
         lower bound of the CI --'          |        |
sample mean (center of the CI) -------------'        |
         upper bound of the CI ----------------------'

As described above, a change is considered significant if the CI is entirely outside the configured SIGNIFICANT_IMPACT_THRESHOLD (or the deprecated UNCONFIDENCE_THRESHOLD).

For instance, for an execution time metric, this confidence interval indicates a significantly worse performance:

----------------------------------------|---------|---(---------^---------)---------->
                                       0%        1%  1.3%      2.2%      3.1%
                                                  |   |         |         |
       significant impact threshold --------------'   |         |         |
                      lower bound of CI --------------'         |         |
       sample mean (center of the CI) --------------------------'         |
                      upper bound of CI ----------------------------------'

scenario:tracing - Propagation - Trace Context

🟥 throughput [-1865.534op/s; -1802.935op/s] or [-5.259%; -5.082%]

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 77458c41aa

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

Strech · 2026-06-04T11:17:41Z

@MilanGarnier I have converted PR into Draft, please use draft pr's for unfinished work, thanks!

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: f0f897e3f9

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

Strech · 2026-06-05T11:35:09Z

@MilanGarnier Please disclose – was this PR AI generated and if yes, you suppose to write about it in description and we will put a tag on it.

⚠️ In addition, I would like to ask you to respect PR template and fill it accordingly

Per Strech's review on #5844 (which targets the same helper as #5867): the prior name implied a normalization the method does not perform. The method re-tags the input via String#force_encoding(UTF-8) and returns nil when the bytes are not a valid UTF-8 sequence. The new name reads off the underlying operation without overpromising success. Also collapses the body: the previous `if value.encoding == UTF_8` early-return branch merges into a single conditional re-encode followed by one `valid_encoding?` check at the end. Behavior unchanged: already-UTF-8 input is returned by object identity (no dup), input is never mutated, frozen input is handled via the dup in the non-UTF-8 branch — all covered by helpers_spec. Updates the helper, the RBS signature, both call sites (TraceContext#extract_tracestate, OTel SpanProcessor span-link path), and the helpers spec describe/subject.

…BEHAVIOR_EXTRACT

bm1549

Reviewing on behalf of apm-sdk-capabilities-ruby - I have no expertise in the Ruby tracer, but am looking from the perspective of feature parity

First off, nice work for a first PR here!

When reviewed this against .NET and Java, the core HTTP propagation path matches: config, the three modes, span-link attrs (reason / context_headers), per-mode baggage, and dropping _dd.p.* on restart all line up. The system-tests (Test_ExtractBehavior_Restart and friends) hit /make_distant_call, so they only cover that HTTP path - they should all pass.

The OTel-API extraction path is where Ruby diverges, and the system tests don't cover it. Under restart, propagator.rb bails early when digest.trace_id is nil (before continue_trace!), so the span link to the upstream context gets dropped. .NET and Java attach it no matter which API starts the trace

It's worth adding a system test in DataDog/system-tests#7076 that runs restart through the OTel extraction API and asserts the same span link (reason / context_headers) the HTTP cases check, so the gap gets caught across every tracer

…BEHAVIOR_EXTRACT

…langarnier-feature_DD_TRACE_PROPAGATION_BEHAVIOR_EXTRACT

MilanGarnier · 2026-06-16T10:33:17Z

Reviewing on behalf of apm-sdk-capabilities-ruby - I have no expertise in the Ruby tracer, but am looking from the perspective of feature parity

First off, nice work for a first PR here!

When reviewed this against .NET and Java, the core HTTP propagation path matches: config, the three modes, span-link attrs (reason / context_headers), per-mode baggage, and dropping _dd.p.* on restart all line up. The system-tests (Test_ExtractBehavior_Restart and friends) hit /make_distant_call, so they only cover that HTTP path - they should all pass.

The OTel-API extraction path is where Ruby diverges, and the system tests don't cover it. Under restart, propagator.rb bails early when digest.trace_id is nil (before continue_trace!), so the span link to the upstream context gets dropped. .NET and Java attach it no matter which API starts the trace

It's worth adding a system test in DataDog/system-tests#7076 that runs restart through the OTel extraction API and asserts the same span link (reason / context_headers) the HTTP cases check, so the gap gets caught across every tracer

@bm1549 This was indeed something I missed and it wasn't covered by the tests. I have added a new system-test in DataDog/system-tests#7076 (passing on dotnet and Java), which only passes with this change.

…BEHAVIOR_EXTRACT

bm1549

Great work Milan!!

…BEHAVIOR_EXTRACT

Drowze · 2026-07-08T12:27:07Z

Hey! I just saw this new feature and I'm really excited about it! Thanks for the work on it @MilanGarnier

What we're interested on is changing the context propagation behaviour only in traces from a particular integration (WaterDrop / Karafka distributed tracing). Would that be possible?

MilanGarnier · 2026-07-09T12:10:59Z

Hey, thanks for the kind words and for raising this!

What we're interested on is changing the context propagation behaviour only in traces from a particular integration (WaterDrop / Karafka distributed tracing). Would that be possible?
@Drowze

That's a good feature request. Right now the setting applies globally, so scoping it to a specific integration isn't supported yet. Technically it's not far off, the question is what it should look like.
How are you imagining this working from a config perspective? If you're interested and have a vision on how this should look, a PR would be very welcome. We'll also look into it internally and come back to you once we've thought it through.

dd-octo-sts Bot added core Involves Datadog core libraries integrations Involves tracing integrations tracing labels Jun 1, 2026

MilanGarnier force-pushed the milangarnier-feature_DD_TRACE_PROPAGATION_BEHAVIOR_EXTRACT branch from db2c892 to f4655b6 Compare June 2, 2026 10:23

MilanGarnier force-pushed the milangarnier-feature_DD_TRACE_PROPAGATION_BEHAVIOR_EXTRACT branch from 09af49d to 806c966 Compare June 2, 2026 12:26

MilanGarnier changed the title ~~feat: trace context propagation behavior (WIP)~~ Feature: trace context propagation behavior DD_TRACE_PROPAGATION_BEHAVIOR_EXTRACT (WIP) Jun 2, 2026

MilanGarnier changed the title ~~Feature: trace context propagation behavior DD_TRACE_PROPAGATION_BEHAVIOR_EXTRACT (WIP)~~ Feature: Add support for DD_TRACE_PROPAGATION_BEHAVIOR_EXTRACT (WIP) Jun 2, 2026

MilanGarnier mentioned this pull request Jun 3, 2026

feat(ruby) : enable DD_TRACE_PROPAGATION_BEHAVIOR_EXTRACT DataDog/system-tests#7076

Merged

5 tasks

MilanGarnier marked this pull request as ready for review June 3, 2026 13:46

MilanGarnier requested review from a team as code owners June 3, 2026 13:46

MilanGarnier requested review from mabdinur and marcotc June 3, 2026 13:46

chatgpt-codex-connector Bot reviewed Jun 3, 2026

View reviewed changes

Comment thread lib/datadog/tracing/distributed/propagation.rb Outdated

Comment thread lib/datadog/tracing/span_link.rb Outdated

DataDog deleted a comment from datadog-official Bot Jun 4, 2026

Strech marked this pull request as draft June 4, 2026 11:17

MilanGarnier changed the title ~~Feature: Add support for DD_TRACE_PROPAGATION_BEHAVIOR_EXTRACT (WIP)~~ Feature: Add support for DD_TRACE_PROPAGATION_BEHAVIOR_EXTRACT Jun 4, 2026

MilanGarnier marked this pull request as ready for review June 4, 2026 14:50

MilanGarnier marked this pull request as draft June 4, 2026 15:34

MilanGarnier marked this pull request as ready for review June 4, 2026 17:19

chatgpt-codex-connector Bot reviewed Jun 4, 2026

View reviewed changes

Comment thread lib/datadog/tracing/distributed/propagation.rb Outdated

p-datadog reviewed Jun 4, 2026

View reviewed changes

Comment thread lib/datadog/tracing/distributed/propagation.rb Outdated

Comment thread lib/datadog/tracing/span_link.rb Outdated

Comment thread lib/datadog/tracing/trace_operation.rb

Comment thread sig/datadog/tracing/distributed/propagation.rbs Outdated

dd-octo-sts Bot added the otel OpenTelemetry-related changes label Jun 5, 2026

MilanGarnier force-pushed the milangarnier-feature_DD_TRACE_PROPAGATION_BEHAVIOR_EXTRACT branch from f2126d3 to c5eec1c Compare June 8, 2026 16:15

p-ddsign and others added 2 commits June 8, 2026 15:12

Merge branch 'master' into milangarnier-feature_DD_TRACE_PROPAGATION_…

1992fdf

…BEHAVIOR_EXTRACT

gh-worker-ownership-write-b05516 Bot removed request for a team June 11, 2026 13:42

bm1549 reviewed Jun 15, 2026

View reviewed changes

MilanGarnier and others added 3 commits June 16, 2026 11:03

Merge branch 'master' into milangarnier-feature_DD_TRACE_PROPAGATION_…

55ed1c2

…BEHAVIOR_EXTRACT

Merge branch 'fix/tracestate-encoding-at-propagator-boundary' into mi…

9df2c8c

…langarnier-feature_DD_TRACE_PROPAGATION_BEHAVIOR_EXTRACT

Fix Otel path when BEHAVIOR_EXTRACT is restart

788a885

p-datadog approved these changes Jun 16, 2026

View reviewed changes

marcotc added 4 commits June 16, 2026 15:37

Use existing UTF-8 encoding

709afd8

Shorten implementation comment

79c6dba

Improve comments and RBS

0204091

Merge branch 'master' into milangarnier-feature_DD_TRACE_PROPAGATION_…

12b645c

…BEHAVIOR_EXTRACT

marcotc approved these changes Jun 17, 2026

View reviewed changes

MilanGarnier requested a review from bm1549 June 17, 2026 08:06

bm1549 approved these changes Jun 17, 2026

View reviewed changes

Merge branch 'master' into milangarnier-feature_DD_TRACE_PROPAGATION_…

766966f

…BEHAVIOR_EXTRACT

MilanGarnier enabled auto-merge (squash) June 17, 2026 13:29

MilanGarnier added 5 commits June 17, 2026 17:37

Merge branch 'master' into milangarnier-feature_DD_TRACE_PROPAGATION_…

491ddd6

…BEHAVIOR_EXTRACT

Merge branch 'master' into milangarnier-feature_DD_TRACE_PROPAGATION_…

deec3a9

…BEHAVIOR_EXTRACT

Merge branch 'master' into milangarnier-feature_DD_TRACE_PROPAGATION_…

de5dca1

…BEHAVIOR_EXTRACT

Merge branch 'master' into milangarnier-feature_DD_TRACE_PROPAGATION_…

f96d702

…BEHAVIOR_EXTRACT

Merge branch 'master' into milangarnier-feature_DD_TRACE_PROPAGATION_…

42d832d

…BEHAVIOR_EXTRACT

MilanGarnier merged commit a3413c5 into master Jun 19, 2026
589 checks passed

MilanGarnier deleted the milangarnier-feature_DD_TRACE_PROPAGATION_BEHAVIOR_EXTRACT branch June 19, 2026 08:59

dd-octo-sts Bot added this to the 2.36.0 milestone Jun 19, 2026

Uh oh!

Conversation

MilanGarnier commented Jun 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

dd-octo-sts Bot commented Jun 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

datadog-prod-us1-5 Bot commented Jun 1, 2026 • edited by datadog-datadog-prod-us1 Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

dd-octo-sts Bot commented Jun 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Typing analysis

Untyped methods

Untyped other declarations

Uh oh!

pr-commenter Bot commented Jun 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Benchmarks

Explanation

More details about the CI and significant changes

scenario:tracing - Propagation - Trace Context

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

Uh oh!

Strech commented Jun 4, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Strech commented Jun 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

bm1549 left a comment

Choose a reason for hiding this comment

Uh oh!

MilanGarnier commented Jun 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

bm1549 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Drowze commented Jul 8, 2026

Uh oh!

MilanGarnier commented Jul 9, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

8 participants

MilanGarnier commented Jun 1, 2026 •

edited

Loading

dd-octo-sts Bot commented Jun 1, 2026 •

edited

Loading

datadog-prod-us1-5 Bot commented Jun 1, 2026 •

edited by datadog-datadog-prod-us1 Bot

Loading

dd-octo-sts Bot commented Jun 2, 2026 •

edited

Loading

pr-commenter Bot commented Jun 2, 2026 •

edited

Loading

Strech commented Jun 5, 2026 •

edited

Loading

MilanGarnier commented Jun 16, 2026 •

edited

Loading