chore(tracing): deprecate ddtrace.settings (#13057)

XG-xin · mabdinur · emmettbutler · web-flow · commit 3cf3342a005c · 2025-07-30T16:24:45.000Z
Mark objects in ddtrace.settings as deprecated. This is related to APMAPI-1245. ## 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) --------- Co-authored-by: Munir Abdinur <munir.abdinur@datadoghq.com> Co-authored-by: Emmett Butler <723615+emmettbutler@users.noreply.github.com>
diff --git a/ddtrace/contrib/internal/trace_utils.py b/ddtrace/contrib/internal/trace_utils.py
@@ -42,7 +42,7 @@
 
 
 if TYPE_CHECKING:  # pragma: no cover
-    from ddtrace.settings import IntegrationConfig  # noqa:F401
+    from ddtrace.settings.integration import IntegrationConfig  # noqa:F401
     from ddtrace.trace import Span  # noqa:F401
     from ddtrace.trace import Tracer  # noqa:F401
 
diff --git a/ddtrace/contrib/internal/trace_utils_base.py b/ddtrace/contrib/internal/trace_utils_base.py
@@ -12,9 +12,9 @@
 from ddtrace.internal.utils.http import normalize_header_name
 from ddtrace.internal.utils.http import redact_url
 from ddtrace.internal.utils.http import strip_query_string
-from ddtrace.settings import IntegrationConfig
 from ddtrace.settings._config import config
 from ddtrace.settings.asm import config as asm_config
+from ddtrace.settings.integration import IntegrationConfig
 
 
 log = get_logger(__name__)
diff --git a/ddtrace/internal/ci_visibility/recorder.py b/ddtrace/internal/ci_visibility/recorder.py
@@ -69,8 +69,8 @@
 from ddtrace.internal.test_visibility._atr_mixins import AutoTestRetriesSettings
 from ddtrace.internal.test_visibility._library_capabilities import LibraryCapabilities
 from ddtrace.internal.utils.formats import asbool
-from ddtrace.settings import IntegrationConfig
 from ddtrace.settings._agent import config as agent_config
+from ddtrace.settings.integration import IntegrationConfig
 from ddtrace.trace import Tracer
 
 
diff --git a/ddtrace/llmobs/_integrations/base.py b/ddtrace/llmobs/_integrations/base.py
@@ -13,7 +13,7 @@
 from ddtrace.llmobs._constants import INTEGRATION
 from ddtrace.llmobs._constants import PROXY_REQUEST
 from ddtrace.llmobs._llmobs import LLMObs
-from ddtrace.settings import IntegrationConfig
+from ddtrace.settings.integration import IntegrationConfig
 from ddtrace.trace import Pin
 from ddtrace.trace import Span
 
diff --git a/ddtrace/opentracer/tracer.py b/ddtrace/opentracer/tracer.py
@@ -16,7 +16,7 @@
 from ddtrace.internal.constants import SPAN_API_OPENTRACING
 from ddtrace.internal.utils.config import get_application_name
 from ddtrace.internal.writer import AgentWriterInterface
-from ddtrace.settings import ConfigException
+from ddtrace.settings.exceptions import ConfigException
 from ddtrace.trace import Context as DatadogContext  # noqa:F401
 from ddtrace.trace import Span as DatadogSpan
 from ddtrace.trace import Tracer as DatadogTracer
diff --git a/ddtrace/settings/__init__.py b/ddtrace/settings/__init__.py
@@ -1,12 +1,36 @@
-from .._hooks import Hooks
-from .exceptions import ConfigException
-from .http import HttpConfig
-from .integration import IntegrationConfig
-
-
-__all__ = [
-    "ConfigException",
-    "HttpConfig",
-    "Hooks",
-    "IntegrationConfig",
-]
+from ddtrace.internal.utils.deprecations import DDTraceDeprecationWarning
+
+from ..vendor.debtcollector import deprecate
+
+
+def __getattr__(name):
+    if name in set(
+        [
+            "ConfigException",
+            "HttpConfig",
+            "Hooks",
+            "IntegrationConfig",
+        ]
+    ):
+        deprecate(
+            ("%s.%s is deprecated" % (__name__, name)),
+            removal_version="4.0.0",  # TODO: update this to the correct version
+            category=DDTraceDeprecationWarning,
+        )
+        if name == "ConfigException":
+            from ddtrace.settings.exceptions import ConfigException
+
+            return ConfigException
+        elif name == "HttpConfig":
+            from .http import HttpConfig
+
+            return HttpConfig
+        elif name == "Hooks":
+            from .._hooks import Hooks
+
+            return Hooks
+        elif name == "IntegrationConfig":
+            from .integration import IntegrationConfig
+
+            return IntegrationConfig
+    raise AttributeError("'%s' has no attribute '%s'" % (__name__, name))
diff --git a/releasenotes/notes/deprecate-import-ddtrace-settings-208007d3b71de8a8.yaml b/releasenotes/notes/deprecate-import-ddtrace-settings-208007d3b71de8a8.yaml
@@ -0,0 +1,4 @@
+---
+deprecations:
+  - |
+    tracing: ``ddtrace.settings.__init__`` imports are deprecated and will be removed in version 4.0.0.
diff --git a/tests/contrib/httplib/test_httplib.py b/tests/contrib/httplib/test_httplib.py
@@ -396,7 +396,7 @@ def test_httplib_request_and_response_headers(self):
 
         # Enabled when configured
         with self.override_config("httplib", {}):
-            from ddtrace.settings import IntegrationConfig  # noqa:F401
+            from ddtrace.settings.integration import IntegrationConfig  # noqa:F401
 
             integration_config = config.httplib  # type: IntegrationConfig
             integration_config.http.trace_headers(["my-header", "access-control-allow-origin"])
diff --git a/tests/opentracer/core/test_tracer.py b/tests/opentracer/core/test_tracer.py
@@ -14,7 +14,7 @@
 from ddtrace.opentracer import set_global_tracer
 from ddtrace.opentracer.span_context import SpanContext
 from ddtrace.propagation.http import HTTP_HEADER_TRACE_ID
-from ddtrace.settings import ConfigException
+from ddtrace.settings.exceptions import ConfigException
 
 
 class TestTracerConfig(object):
diff --git a/tests/tracer/test_global_config.py b/tests/tracer/test_global_config.py
@@ -4,8 +4,8 @@
 import pytest
 
 from ddtrace import config as global_config
-from ddtrace.settings import IntegrationConfig
 from ddtrace.settings._config import Config
+from ddtrace.settings.integration import IntegrationConfig
 
 from ..utils import DummyTracer
 from ..utils import override_env
diff --git a/tests/tracer/test_instance_config.py b/tests/tracer/test_instance_config.py
@@ -1,7 +1,7 @@
 from unittest import TestCase
 
 from ddtrace import config
-from ddtrace.settings import IntegrationConfig
+from ddtrace.settings.integration import IntegrationConfig
 from ddtrace.trace import Pin
 
 
diff --git a/tests/tracer/test_settings.py b/tests/tracer/test_settings.py
@@ -2,9 +2,9 @@
 
 import pytest
 
-from ddtrace.settings import HttpConfig
-from ddtrace.settings import IntegrationConfig
 from ddtrace.settings._config import Config
+from ddtrace.settings.http import HttpConfig
+from ddtrace.settings.integration import IntegrationConfig
 from tests.utils import BaseTestCase
 from tests.utils import override_env
 
@@ -243,3 +243,68 @@ def test_x_datadog_tags(env, expected):
     with override_env(env):
         _ = Config()
         assert expected == (_._x_datadog_tags_max_length, _._x_datadog_tags_enabled)
+
+
+@pytest.mark.subprocess()
+def test_config_exception_deprecation():
+    import warnings
+
+    with warnings.catch_warnings(record=True) as warns:
+        warnings.simplefilter("default")
+
+        from ddtrace.settings import ConfigException  # noqa: F401
+
+        assert len(warns) == 1
+        warn = warns[0]
+
+        assert issubclass(warn.category, DeprecationWarning)
+        assert "ddtrace.settings.ConfigException is deprecated" in str(warn.message)
+        assert "4.0.0" in str(warn.message)  # TODO: update the version
+
+
+@pytest.mark.subprocess()
+def test_http_config_deprecation():
+    import warnings
+
+    with warnings.catch_warnings(record=True) as warns:
+        warnings.simplefilter("default")
+
+        from ddtrace.settings import HttpConfig  # noqa: F401
+
+        assert len(warns) == 1
+        warn = warns[0]
+        assert issubclass(warn.category, DeprecationWarning)
+        assert "ddtrace.settings.HttpConfig is deprecated" in str(warn.message)
+        assert "4.0.0" in str(warn.message)  # TODO: update the version
+
+
+@pytest.mark.subprocess()
+def test_hooks_deprecation():
+    import warnings
+
+    with warnings.catch_warnings(record=True) as warns:
+        warnings.simplefilter("default")
+
+        from ddtrace.settings import Hooks  # noqa: F401
+
+        assert len(warns) == 1
+        warn = warns[0]
+        assert issubclass(warn.category, DeprecationWarning)
+        assert "ddtrace.settings.Hooks is deprecated" in str(warn.message)
+        assert "4.0.0" in str(warn.message)  # TODO: update the version
+
+
+@pytest.mark.subprocess()
+def test_integration_config_deprecation():
+    import warnings
+
+    with warnings.catch_warnings(record=True) as warns:
+        warnings.simplefilter("default")
+
+        from ddtrace.settings import IntegrationConfig  # noqa: F401
+
+        assert len(warns) == 1
+        warn = warns[0]
+        assert issubclass(warn.category, DeprecationWarning)
+        assert "ddtrace.settings.IntegrationConfig is deprecated" in str(warn.message)
+        assert "4.0.0" in str(warn.message)  # TODO: update the version
diff --git a/tests/tracer/test_trace_utils.py b/tests/tracer/test_trace_utils.py
@@ -23,8 +23,8 @@
 from ddtrace.propagation.http import HTTP_HEADER_PARENT_ID
 from ddtrace.propagation.http import HTTP_HEADER_TRACE_ID
 from ddtrace.propagation.http import HTTPPropagator
-from ddtrace.settings import IntegrationConfig
 from ddtrace.settings._config import Config
+from ddtrace.settings.integration import IntegrationConfig
 from ddtrace.trace import Context
 from ddtrace.trace import Pin
 from ddtrace.trace import Span

-Original file line number
+Diff line change
@@ @@ -0,0 +1,4 @@ @@
 +---
 +deprecations:
 +  - |
 +    tracing: ``ddtrace.settings.__init__`` imports are deprecated and will be removed in version 4.0.0.