feat(tracing): add DD_TRACE_PROPAGATION_BEHAVIOR_EXTRACT by MilanGarnier · Pull Request #3997 · DataDog/dd-trace-php

MilanGarnier · 2026-06-17T10:09:25Z

Summary

Implements DD_TRACE_PROPAGATION_BEHAVIOR_EXTRACT (APMAPI-1941, feature-parity #353) for the PHP tracer, matching behavior already present in .NET, Python, Node, Java, Ruby, and Rust.

Three values:

continue (default): inherit upstream trace context unchanged — no behavior change
restart: start a fresh trace; the upstream context is captured as a span link with reason=propagation_behavior_extract
ignore: drop all extracted context including baggage and sampling priority

Design:

Single chokepoint: all extraction funnels through ddtrace_apply_distributed_tracing_result in distributed_tracing_headers.c, covering both request-init and consume_distributed_tracing_headers userland calls
restart path: when the root span doesn't yet exist at request-init time, the span link is queued in DDTRACE_G(pending_upstream_span_link) and consumed in ddtrace_open_span when the root span is created
Extracted ddtrace_build_span_link_from_result() from SpanLink::fromHeaders for reuse

Test plan

tests/ext/distributed_tracing/propagation_behavior_extract_continue.phpt — verifies trace_id inherited, no span link, baggage preserved
tests/ext/distributed_tracing/propagation_behavior_extract_restart.phpt — verifies fresh trace_id, span link with correct upstream ids and reason, baggage preserved, _dd.p.* not in link attributes
tests/ext/distributed_tracing/propagation_behavior_extract_ignore.phpt — verifies fresh trace_id, no span link, baggage dropped, sampling priority dropped
tests/ext/distributed_tracing/propagation_behavior_extract_config.phpt — verifies case-insensitive parsing, invalid value falls back to continue
CI phpt suite

⚠️ Warnings

🚦 19 Pipeline jobs failed

DataDog/apm-reliability/dd-trace-php | ASAN test_c with multiple observers: [8.3]

DataDog/apm-reliability/dd-trace-php | ASAN test_c with multiple observers: [8.5]

DataDog/apm-reliability/dd-trace-php | ASAN test_c: [7.4, amd64]

View all 19 failed jobs.

❄️ 1 New flaky test detected

tmp/build_extension/tests/ext/distributed_tracing/propagation_behavior_extract_restart.phpt (DD_TRACE_PROPAGATION_BEHAVIOR_EXTRACT=restart starts fresh trace with span link) from PHP.tmp.build_extension.tests.ext.distributed_tracing
010&#43; 
010- foo_in_tags: no
011&#43; Fatal error: Uncaught Error: Call to undefined function str_contains() in tmp/build_extension/tests/ext/distributed_tracing/propagation_behavior_extract_restart.php:41
012&#43; Stack trace:
013&#43; #0 {main}
014&#43;   thrown in tmp/build_extension/tests/ext/distributed_tracing/propagation_behavior_extract_restart.php on line 41
New test introduced in this PR is flaky.
View in Flaky Test Management

ℹ️ Info

No other issues found (see more)

🧪 All tests passed

🎯 Code Coverage (details)
• Patch Coverage: 100.00%
• Overall Coverage: 54.11% (-0.00%)

Useful? React with 👍 / 👎

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

🔗 Commit SHA: 19c7daf | Docs | Datadog PR Page | Give us feedback!}

Adds the new `DD_TRACE_PROPAGATION_BEHAVIOR_EXTRACT` config key (values: continue, restart, ignore) with a CUSTOM(INT) parser, the corresponding C enum, and the supported-configurations.json entry. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Adds three behaviors at the single extraction chokepoint (ddtrace_apply_distributed_tracing_result): - continue (default): inherit upstream trace context unchanged - restart: start a fresh trace; upstream captured as a span link with reason=propagation_behavior_extract. When the root span doesn't exist yet at request-init time, the link is queued in DDTRACE_G(pending_upstream_span_link) and attached in ddtrace_open_span. - ignore: drop all extracted context including baggage and sampling priority Also extracts ddtrace_build_span_link_from_result() from the SpanLink fromHeaders method so it can be reused by the restart path. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Covers the three behaviors (continue, restart, ignore) and config parsing (case-insensitive values, invalid value falls back to default). Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Co-authored-by: Bob Weinand <bob.weinand@datadoghq.com>

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 19c7dafd9f

ℹ️ 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".

chatgpt-codex-connector · 2026-06-23T12:19:56Z

+            zend_hash_clean(&result->meta_tags);
+            zend_hash_clean(&result->propagated_tags);


Drop upstream tracestate on restart

When DD_TRACE_PROPAGATION_BEHAVIOR_EXTRACT=restart receives headers that include x-datadog-origin or W3C tracestate, this path only clears trace id/parent/sampling and _dd.p.*; the code below still moves result->origin, result->tracestate, and tracestate_unknown_dd_keys onto the new root/global context, and outbound injection later re-emits them. In that scenario the restarted trace continues propagating upstream trace context instead of preserving only baggage plus the span link.

Useful? React with 👍 / 👎.

MilanGarnier added the AI Generated Largely based on code generated by an AI or LLM. This label is the same across all dd-trace-* repos label Jun 17, 2026

MilanGarnier and others added 5 commits June 17, 2026 17:11

test: add phpt tests for DD_TRACE_PROPAGATION_BEHAVIOR_EXTRACT

6914d02

Covers the three behaviors (continue, restart, ignore) and config parsing (case-insensitive values, invalid value falls back to default). Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

fix: set implementation to B for DD_TRACE_PROPAGATION_BEHAVIOR_EXTRACT

68ddc93

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Remove breaking include

3ca8428

MilanGarnier force-pushed the MilanGarnier/propagation-behavior-extract branch from 6b7e259 to 3ca8428 Compare June 17, 2026 15:33

MilanGarnier added 2 commits June 18, 2026 11:18

Fix: prevent sampling to propagate in restart mode

f5db737

Own references to property attributes when creating attributes

6374dad

bwoebi reviewed Jun 18, 2026

View reviewed changes

Comment thread tracer/distributed_tracing_headers.c Outdated

bwoebi reviewed Jun 18, 2026

View reviewed changes

Comment thread tracer/distributed_tracing_headers.c Outdated

bwoebi reviewed Jun 18, 2026

View reviewed changes

Comment thread tracer/distributed_tracing_headers.c Outdated

bwoebi reviewed Jun 18, 2026

View reviewed changes

Comment thread tracer/functions.c

MilanGarnier and others added 9 commits June 18, 2026 12:58

Apply suggestion from @bwoebi

602e2be

Co-authored-by: Bob Weinand <bob.weinand@datadoghq.com>

emalloc instead of statically sizer array for deleting tags

a39e0a4

add check for trace id

cb5cc57

clean meta tags in one iteration

c7674bd

Also pass exctraction style, refactor bextract behavior logic

fa54461

update test to match behavior

5d0fc77

Fix parent id check, sampling cannot be tested here

ea4bf80

sampling priority cannot be tested here

5832c73

Split config check test for different scenarios

19c7daf

MilanGarnier marked this pull request as ready for review June 23, 2026 12:15

MilanGarnier requested a review from a team as a code owner June 23, 2026 12:15

chatgpt-codex-connector Bot reviewed Jun 23, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(tracing): add DD_TRACE_PROPAGATION_BEHAVIOR_EXTRACT#3997

feat(tracing): add DD_TRACE_PROPAGATION_BEHAVIOR_EXTRACT#3997
MilanGarnier wants to merge 16 commits into
masterfrom
MilanGarnier/propagation-behavior-extract

MilanGarnier commented Jun 17, 2026

Uh oh!

datadog-official Bot commented Jun 17, 2026 •

edited by datadog-prod-us1-5 Bot

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

chatgpt-codex-connector Bot left a comment

Uh oh!

chatgpt-codex-connector Bot Jun 23, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		zend_hash_clean(&result->meta_tags);
		zend_hash_clean(&result->propagated_tags);

Conversation

MilanGarnier commented Jun 17, 2026

Summary

Test plan

Related

Uh oh!

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

Uh oh!

⚠️ Warnings

ℹ️ Info

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector Bot Jun 23, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

datadog-official Bot commented Jun 17, 2026 •

edited by datadog-prod-us1-5 Bot

Loading