feat(tracing): add support for DD_TRACE_PROPAGATION_BEHAVIOR_EXTRACT

[MilanGarnier]

Description

Add support for DD_TRACE_PROPAGATION_BEHAVIOR_EXTRACT, controlling how the
tracer handles incoming distributed-trace context on extraction:

• continue (default): existing behavior — propagate the extracted context
  as-is.
• restart: start a brand-new trace (fresh sampling decision, no parent)
  and attach a span link back to the extracted context, carrying the
  extracted W3C tracestate for later reference.
• ignore: discard the incoming context entirely; extract_span returns
  Error::NO_SPAN_TO_EXTRACT and baggage extraction is skipped as well.

Changes:

• New PropagationBehaviorExtract enum + parser
  (propagation_behavior_extract.h/.cpp), following the same
  parse/to_string_view pattern as PropagationStyle.
• Wired into TracerConfig / FinalizedTracerConfig, ConfigName,
  telemetry config reporting, and supported-configurations.json.
• New env var DD_TRACE_PROPAGATION_BEHAVIOR_EXTRACT (default "continue").
• Tracer::extract_span branches on the configured behavior:
  short-circuits for ignore, builds a fresh span + span link for
  restart, otherwise behaves as before.
• ExtractedData gains tracestate_full (the raw, un-parsed W3C
  tracestate string) so it can be attached to the span link created by
  restart.
• Minor refactor of Span::add_link to build the SpanLink in one shot
  instead of mutating fields after default-construction.

This branch is stacked on milan.garnier/span-links-support, which
introduced span-link support end-to-end (required by restart); this PR's
diff is scoped to the propagation-behavior-extract feature itself.

Motivation

Matches the behavior already available in other Datadog tracers
(dd-trace-go/py/rb/java) for controlling context propagation on extraction,
letting services opt out of continuing an untrusted/foreign trace context
while still linking back to it for correlation.

Additional Notes

• The restart link's flags field is not yet populated (see // TODO: flags in tracer.cpp) — sampling flags for the link should be derived
  once available.
• link_attributes["context_headers"] is currently a placeholder
  ("todo") and should be filled in with the actual extracted headers
  before merge.

Jira ticket: APMAPI-1941

[datadog-prod-us1-6]

✨ Fix all issues with BitsAI

⚠️ Warnings

🚦 3 Pipeline jobs failed

DataDog/apm-reliability/dd-trace-cpp | check-big-regressions     

Development | build-windows-cmake (amd64)     

Development | build-windows-cmake (arm64)     

ℹ️ Info

🎯 Code Coverage (details)
• Patch Coverage: 71.15%
• Overall Coverage: 91.51% (-0.24%)

Useful? React with 👍 / 👎

_{This comment will be updated automatically if new data arrives.
🔗 Commit SHA: aed025f | Docs | Datadog PR Page | Give us feedback!}

[pr-commenter]

Benchmarks

Benchmark execution time: 2026-07-08 16:19:56

Comparing candidate commit aed025f in PR branch milan.garnier/propagation-behavior-extract with baseline commit f033eef in branch milan.garnier/span-links-support.

Found 2 performance improvements and 5 performance regressions! Performance is the same for 1 metrics, 0 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:BM_HexPadded_uint64/NoPadding

• 🟩 execution_time [-1.896ns; -1.670ns] or [-3.480%; -3.064%]

scenario:BM_HexPadded_uint64/WorstCasePadding

• 🟩 execution_time [-2.082ns; -1.901ns] or [-4.204%; -3.838%]

scenario:BM_TraceID_HexPadded/NoPadding

• 🟥 execution_time [+4.877ns; +5.017ns] or [+2.473%; +2.544%]

scenario:BM_TraceID_HexPadded/WithPadding

• 🟥 execution_time [+5.246ns; +5.428ns] or [+3.972%; +4.110%]

scenario:BM_TraceID_ParseHex/128bit

• 🟥 execution_time [+12.810ns; +12.887ns] or [+10.365%; +10.428%]

scenario:BM_TraceID_ParseHex/64bit

• 🟥 execution_time [+5.197ns; +5.249ns] or [+7.446%; +7.520%]

scenario:BM_TraceTinyCCSource

• 🟥 execution_time [+2.031ms; +2.206ms] or [+2.531%; +2.749%]