feat(baggage): auto-adding baggage to span tags (#13200)

Automatically adding baggage key-value pairs to span tags with the
'baggage.' prefix. Introducing DD_TRACE_BAGGAGE_TAG_KEYS config.
[RFC](https://docs.google.com/document/d/1ZsgAcQHKjaBxDmhHup0zqFz07WYiOrbBksHPoXJe6u4/edit?tab=t.0#heading=h.q69qzmye8dfb)

## Checklist
- [x] 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](https://ddtrace.readthedocs.io/en/stable/releasenotes.html)
- The change includes or references documentation updates if necessary
- Backport labels are set (if
[applicable](https://ddtrace.readthedocs.io/en/latest/contributing.html#backporting))

## Reviewer Checklist
- [x] 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](https://ddtrace.readthedocs.io/en/stable/versioning.html#interfaces)
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](https://ddtrace.readthedocs.io/en/latest/contributing.html#backporting)

Author: rachelyangdog

ddtrace/internal/constants.py

@@ -85,6 +85,7 @@
 # baggage
 DD_TRACE_BAGGAGE_MAX_ITEMS = 64
 DD_TRACE_BAGGAGE_MAX_BYTES = 8192
+BAGGAGE_TAG_PREFIX = "baggage."
 
 
 class SamplingMechanism(object):

ddtrace/propagation/http.py

@@ -35,6 +35,7 @@
 from ..internal.constants import _PROPAGATION_BEHAVIOR_RESTART
 from ..internal.constants import _PROPAGATION_STYLE_BAGGAGE
 from ..internal.constants import _PROPAGATION_STYLE_W3C_TRACECONTEXT
+from ..internal.constants import BAGGAGE_TAG_PREFIX
 from ..internal.constants import DD_TRACE_BAGGAGE_MAX_BYTES
 from ..internal.constants import DD_TRACE_BAGGAGE_MAX_ITEMS
 from ..internal.constants import HIGHER_ORDER_TRACE_ID_BITS as _HIGHER_ORDER_TRACE_ID_BITS
@@ -1153,6 +1154,21 @@ def my_controller(url, headers):
                         context._baggage = baggage_context.get_all_baggage_items()
                     else:
                         context = baggage_context
+
+                    if config._baggage_tag_keys:
+                        raw_keys = [k.strip() for k in config._baggage_tag_keys if k.strip()]
+                        # wildcard: tag all baggage keys
+                        if "*" in raw_keys:
+                            tag_keys = baggage_context.get_all_baggage_items().keys()
+                        else:
+                            tag_keys = raw_keys
+
+                        for stripped_key in tag_keys:
+                            if (value := baggage_context.get_baggage_item(stripped_key)) is not None:
+                                prefixed_key = BAGGAGE_TAG_PREFIX + stripped_key
+                                if prefixed_key not in context._meta:
+                                    context._meta[prefixed_key] = value
+
             if config._propagation_behavior_extract == _PROPAGATION_BEHAVIOR_RESTART:
                 link = HTTPPropagator._context_to_span_link(context, style, "propagation_behavior_extract")
                 context = Context(baggage=context.get_all_baggage_items(), span_links=[link] if link else [])

ddtrace/settings/_config.py

@@ -579,6 +579,9 @@ def __init__(self):
         )
 
         self._propagation_extract_first = _get_config("DD_TRACE_PROPAGATION_EXTRACT_FIRST", False, asbool)
+        self._baggage_tag_keys = _get_config(
+            "DD_TRACE_BAGGAGE_TAG_KEYS", ["user.id", "account.id", "session.id"], lambda x: x.strip().split(",")
+        )
 
         # Datadog tracer tags propagation
         x_datadog_tags_max_length = _get_config("DD_TRACE_X_DATADOG_TAGS_MAX_LENGTH", 512, int)

docs/configuration.rst

@@ -914,6 +914,20 @@ Other
       version_added:
          v1.15.0:
 
+   DD_TRACE_BAGGAGE_TAG_KEYS:
+      type: String
+      default: "user.id,account.id,session.id"
+
+      description: |
+         A comma-separated list of baggage keys to be automatically attached as tags on spans.
+         For each key specified, if a corresponding baggage key is present and has a non-empty value,
+         the key-value pair will be added to the span's metadata using the key name formatted as ``baggage.<key>``.
+         If you want to turn off this feature, set the configuration value to an empty string.
+         When set to `*`, **all** baggage keys will be converted into span tags. Use with caution: this may unintentionally expose sensitive or internal data if not used intentionally.
+
+      version_added: 
+         v3.6.0:
+
 .. _Unified Service Tagging: https://docs.datadoghq.com/getting_started/tagging/unified_service_tagging/
 
 .. _Configure the Datadog Tracing Library: https://docs.datadoghq.com/tracing/trace_collection/library_config/

releasenotes/notes/auto-adding-baggage-to-span-tags-0ec127de76ca97bf.yaml

@@ -0,0 +1,6 @@
+---
+features:
+  - |
+    baggage: Adds support for automatically adding baggage key-value pairs to span tags. Baggage items from incoming HTTP headers are attached to spans as tags with a `baggage.` prefix
+    The `DD_TRACE_BAGGAGE_TAG_KEYS` configuration allows users to specify a comma-separated list of baggage keys for span tagging, by default the value is set to `user.id,account.id,session.id`.
+    When set to `*`, all baggage keys will be converted into span tags. Setting it to an empty value disables baggage tagging.

tests/contrib/fastapi/test_fastapi.py

@@ -736,3 +736,57 @@ def test_inferred_spans_api_gateway(client, tracer, test_spans, test, inferred_p
 
             if test_headers["type"] == "distributed":
                 assert web_span.trace_id == 1
+
+
+def test_baggage_span_tagging_default(client, tracer, test_spans):
+    response = client.get("/", headers={"baggage": "user.id=123,account.id=456,region=us-west"})
+
+    assert response.status_code == 200
+
+    spans = test_spans.pop_traces()
+    # Assume the request span is the first span in the first trace.
+    request_span = spans[0][0]
+
+    assert request_span.get_tag("baggage.user.id") == "123"
+    assert request_span.get_tag("baggage.account.id") == "456"
+    # Since "region" is not in the default list, its baggage tag should not be present.
+    assert request_span.get_tag("baggage.region") is None
+
+
+def test_baggage_span_tagging_no_headers(client, tracer, test_spans):
+    response = client.get("/", headers={})
+    assert response.status_code == 200
+
+    spans = test_spans.pop_traces()
+    request_span = spans[0][0]
+
+    # None of the baggage tags should be present.
+    assert request_span.get_tag("baggage.user.id") is None
+    assert request_span.get_tag("baggage.account.id") is None
+    assert request_span.get_tag("baggage.session.id") is None
+
+
+def test_baggage_span_tagging_empty_baggage(client, tracer, test_spans):
+    response = client.get("/", headers={"baggage": ""})
+    assert response.status_code == 200
+
+    spans = test_spans.pop_traces()
+    request_span = spans[0][0]
+
+    # None of the baggage tags should be present.
+    assert request_span.get_tag("baggage.user.id") is None
+    assert request_span.get_tag("baggage.account.id") is None
+    assert request_span.get_tag("baggage.session.id") is None
+
+
+def test_baggage_span_tagging_baggage_api(client, tracer, test_spans):
+    response = client.get("/", headers={"baggage": ""})
+    assert response.status_code == 200
+
+    spans = test_spans.pop_traces()
+    request_span = spans[0][0]
+    request_span.context.set_baggage_item("user.id", "123")
+    # None of the baggage tags should be present since we only tag baggage during extraction from headers
+    assert request_span.get_tag("baggage.account.id") is None
+    assert request_span.get_tag("baggage.user.id") is None
+    assert request_span.get_tag("baggage.session.id") is None

tests/telemetry/test_writer.py

@@ -466,6 +466,7 @@ def test_app_started_event_configuration_override(test_agent_session, run_python
         {"name": "DD_TRACE_AGENT_PORT", "origin": "default", "value": None},
         {"name": "DD_TRACE_AGENT_TIMEOUT_SECONDS", "origin": "default", "value": 2.0},
         {"name": "DD_TRACE_API_VERSION", "origin": "env_var", "value": "v0.5"},
+        {"name": "DD_TRACE_BAGGAGE_TAG_KEYS", "origin": "default", "value": "user.id,account.id,session.id"},
         {"name": "DD_TRACE_CLIENT_IP_ENABLED", "origin": "env_var", "value": True},
         {"name": "DD_TRACE_CLIENT_IP_HEADER", "origin": "default", "value": None},
         {"name": "DD_TRACE_COMPUTE_STATS", "origin": "env_var", "value": True},

tests/tracer/test_propagation.py

@@ -3538,3 +3538,67 @@ def test_opentracer_propagator_baggage_extract():
     }
     context = HTTPPropagator.extract(headers)
     assert context._baggage == {"key1": "value1"}
+
+
+def test_baggage_span_tags_default():
+    headers = {"baggage": "user.id=123,correlation_id=abc,region=us-east"}
+    context = HTTPPropagator.extract(headers)
+    # Only "user.id" is in allowed_keys; expect its value to be tagged under the prefixed key.
+    assert context._meta.get("baggage.user.id") == "123"
+    # Other keys are not tagged.
+    assert "baggage.correlation_id" not in context._meta
+    assert "baggage.region" not in context._meta
+
+
+@pytest.mark.subprocess(
+    env=dict(DD_TRACE_BAGGAGE_TAG_KEYS=""),
+)
+def test_baggage_span_tags_empty():
+    from ddtrace.propagation.http import HTTPPropagator
+
+    headers = {"baggage": "user.id=123,correlation_id=abc,region=us-east"}
+    context = HTTPPropagator.extract(headers)
+    assert "baggage.user.id" not in context._meta
+    assert "baggage.correlation_id" not in context._meta
+    assert "baggage.region" not in context._meta
+
+
+@pytest.mark.subprocess(
+    env=dict(DD_TRACE_BAGGAGE_TAG_KEYS="user.id"),
+)
+def test_baggage_span_tags_specific_keys():
+    from ddtrace.propagation.http import HTTPPropagator
+
+    headers = {"baggage": "user.id=123,correlation_id=abc,region=us-east"}
+    context = HTTPPropagator.extract(headers)
+    assert context._meta.get("baggage.user.id") == "123"
+    assert "baggage.account.id" not in context._meta
+    assert "baggage.session.id" not in context._meta
+
+
+@pytest.mark.subprocess(
+    env=dict(DD_TRACE_BAGGAGE_TAG_KEYS="user.id,ACCOUNT.ID"),
+)
+def test_baggage_span_tags_case_sensitive():
+    from ddtrace.propagation.http import HTTPPropagator
+
+    headers = {"baggage": "user.id=123,correlation_id=abc,region=us-east"}
+    context = HTTPPropagator.extract(headers)
+    assert context._meta.get("baggage.user.id") == "123"
+    assert context._meta.get("baggage.ACCOUNT.ID") is None
+    assert "baggage.account.id" not in context._meta
+
+
+@pytest.mark.subprocess(
+    env=dict(DD_TRACE_BAGGAGE_TAG_KEYS="*"),
+)
+def test_baggage_span_tags_wildcard():
+    from ddtrace.propagation.http import HTTPPropagator
+
+    headers = {"baggage": "user.id=foo,correlation_id=car,color=blue,serverNode=DF 28"}
+    context = HTTPPropagator.extract(headers)
+    assert context._meta.get("baggage.user.id") == "foo"
+    assert context._meta.get("baggage.correlation_id") == "car"
+    assert context._meta.get("baggage.color") == "blue"
+    assert context._meta.get("baggage.serverNode") == "DF 28"
+    assert "baggage.session.id" not in context._meta