feat(propagation): add DD_TRACE_PROPAGATION_BEHAVIOR_EXTRACT to handle x-org propagation

[ZStriker19]

Configuration: DD_TRACE_PROPAGATION_BEHAVIOR_EXTRACT
Values:

• continue (default): The tracing library continues the trace from the incoming headers, if present. Also, incoming baggage is propagated.
• restart: The tracing library always starts a new trace with a new trace-id. If there are distributed tracing headers, a span link will be added to reference the trace context. Also, incoming baggage is propagated.
• ignore: The tracing library always starts a new trace with a new trace-id without creating any span links. Also, incoming baggage is dropped.
  Note: We do not need to implement this at the moment because the workaround we have in place DD_TRACE_PROPAGATION_STYLE_EXTRACT=none performs this exact function of completely ignoring incoming trace context headers and baggage headers. If we receive feedback, we can add this new option that we maintain.

Result
✅ Head services: Customers can configure these services with the restart configuration so that they are always the root span, regardless of incoming distributed tracing headers.
✅ Internal services: By default, internal services will remain unchanged and continue to report complete traces to Datadog. If a user has configured an internal service with the restart configuration, this will lead to partial traces. Thankfully with Span Links we can easily direct the customer to the upstream trace (if it was sampled).
❌ Sometimes-head services: This solution does not solve for services that are sometimes head services and sometimes not. The best solution for these services is to set the restart configuration so that a new trace can begin and sampling priority can be recalculated, and in the case that this was not a head service then the upstream service can be found with a span link.
❌ Reentrant systems: This solution does not improve this scenario no matter how the reentrant service is configured. Under the continue configuration, the reentrant service is part of the same trace as the original root span but it is orphaned. Under the restart configuration, a new trace will be started and the span will be decorated with a span link containing the original trace-id but the contained span-id would not point to a span tracked in their Datadog organization.

Note: This contains a fix, allowing only baggage to be propagated.

Checklist

• PR author has checked that all the criteria below are met
• The PR description includes an overview of the change
• The PR description articulates the motivation for the change
• The change includes tests OR the PR description describes a testing strategy
• The PR description notes risks associated with the change, if any
• Newly-added code is easy to change
• The change follows the library release note guidelines
• The change includes or references documentation updates if necessary
• Backport labels are set (if applicable)

Reviewer Checklist

• Reviewer has checked that all the criteria below are met
• Title is accurate
• All changes are related to the pull request's stated goal
• Avoids breaking API changes
• Testing strategy adequately addresses listed risks
• Newly-added code is easy to change
• Release note makes sense to a user of the library
• If necessary, author has acknowledged and discussed the performance implications of this PR as reported in the benchmarks PR comment
• Backport labels are set in a manner that is consistent with the release branch maintenance policy

[github-actions]

CODEOWNERS have been resolved as:

releasenotes/notes/propagation_behavior_extract-3d16765cfd07485b.yaml   @DataDog/apm-python
ddtrace/_trace/tracer.py                                                @DataDog/apm-sdk-api-python
ddtrace/contrib/trace_utils.py                                          @DataDog/apm-core-python @DataDog/apm-idm-python
ddtrace/internal/constants.py                                           @DataDog/apm-core-python
ddtrace/propagation/http.py                                             @DataDog/apm-sdk-api-python
ddtrace/settings/config.py                                              @DataDog/python-guild @DataDog/apm-sdk-api-python
docs/configuration.rst                                                  @DataDog/python-guild
tests/telemetry/test_writer.py                                          @DataDog/apm-python
tests/tracer/test_propagation.py                                        @DataDog/apm-sdk-api-python
tests/utils.py                                                          @DataDog/python-guild

[pr-commenter]

Benchmarks

Benchmark execution time: 2025-01-14 23:25:34

Comparing candidate commit a9de823 in PR branch zachg/handle_cross_org_propagation with baseline commit fce6d75 in branch main.

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

[datadog-dd-trace-py-rkomorn]

Datadog Report

Branch report: zachg/handle_cross_org_propagation
Commit report: a9de823
Test service: dd-trace-py

✅ 0 Failed, 130 Passed, 1468 Skipped, 4m 15.92s Total duration (29m 18.79s time saved)

[erikayasuda]

Some questions for my own clarity. Otherwise LGTM from LP side

[mabdinur]

Overall looks good to me. We need to confirm with @zacharycmontoya that the distributed tracing edge cases uncovered in this PR are documented somewhere. We should align one implementation across all tracers.

[rachelyangdog]

In terms of baggage, I think it looks good!