[BUG]: ddtrace documentation references trace_headers

[Cardds]

Tracer Version(s)

2.20.1+

Python Version(s)

3.12.8

Pip Version(s)

25.0.1

Bug Report

The latest ddtrace documentation references config.trace_headers https://ddtrace.readthedocs.io/en/stable/advanced_usage.html#headers-tracing as a valid method in which to configure storing request & response headers in tags on the trace.

However, it appears this functionality was deprecated in 2.20.1 and removed in 3.0.0+. No alternative for the functionality appears to have been documented as part of the 3.0.0 upgrade.

Ref:

• https://github.com/DataDog/dd-trace-py/releases/tag/v2.20.1
• chore(configs): make rc and http configs internal [3.0] [backport 2.20] #12086

Reproduction Code

from ddtrace import config

config.trace_headers(["Cache-Control"])

Error Logs

Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/.venv/lib/python3.12/site-packages/ddtrace/settings/_config.py", line 697, in __getattr__
    raise AttributeError(f"{type(self)} object has no attribute {name}, {name} is not a valid configuration")
AttributeError: <class 'ddtrace.settings._config.Config'> object has no attribute trace_headers, trace_headers is not a valid configuration

Libraries in Use

ddtrace = "3.16.2"

Operating System

No response

[wantsui]

Thanks for flagging this @Cardds ! Someone from my team is working fixing the docs.

In the meantime, do you have a use case where you might need access to this functionality that the environment variable DD_TRACE_HEADER_TAGS does not cover?

[Cardds]

@wantsui From a purely technical implementation perspective, DD_TRACE_HEADER_TAGS can be used. From a procedural perspective, only allowing configuration definitions here reduces the functionality of the behavior that existed previously and introduces additional concerns when tackling some of the problems that were solved with the static, immutable trace header definitions.

Specifically, configuration is behavior is likely to change between deploys of a service, and there are several cases where either the definition of headers to track as part of the traces should not be changing between deploys of a service, or should be changing immediately alongside the service change. For example, if a service defined its own custom headers, and always wanted to log those custom headers as part of the trace information, there should be an avenue to define that in the service, rather than only as a mutable configuration option. This way, the configuration does not imply knowledge about the internal operations of the service.

An immutable definition of the traced headers in the service also means that the configuration option doesn't need to be operated on independently of the service if/when the implementation of the service changes. For example, in the current configuration-only methodology, the changing a custom header name in-service necessitates a corresponding configuration change in concert with the service deployment. With a static definition in the service, a change to said header can be tied directly to the definition to monitor said configuration, obviating the need for additional changes.

[wantsui]

@Cardds - Thanks for the explanation!

With the current implementation of DD_TRACE_HEADER_TAGS, if you know that a service can potentially receive headers A, B, C, but in practice only C is received, you can still set DD_TRACE_HEADER_TAGS to a, b, and c even though only "c" is received.

From your description, does that mean sometimes a service does not know ahead of time the names of the headers it'll receive? (If this is the case, then we don't have a good way to tackle this and I'll loop in someone else to review this Github issue).