refactor: break cycles involving ddtrace.internal.debug (#19298)

This change refactors `ddtrace.internal.debug` to avoid the creation of import cycles with `ddtrace._trace` and `ddtrace.config`. The core approach is to encapsulate the tracer facts needed by the debug module in a class that can be imported by both the tracer and the debug module. This new class is used in `collect` and `pretty_collect` to avoid inline imports in those functions.

Co-authored-by: emmett.butler <emmett.butler@datadoghq.com>

Author: emmettbutler

ddtrace/_trace/tracer.py

@@ -60,6 +60,7 @@
 from ddtrace.internal.utils import _get_metas_to_propagate
 from ddtrace.internal.utils.deprecations import DDTraceDeprecationWarning
 from ddtrace.internal.utils.formats import format_trace_id
+from ddtrace.internal.utils.tracer_debug_info import TracerDebugInfo
 from ddtrace.internal.writer import AgentWriterInterface
 from ddtrace.internal.writer import HTTPWriter
 from ddtrace.vendor.debtcollector import deprecate
@@ -389,7 +390,14 @@ def configure(
     def _generate_diagnostic_logs(self):
         if config._debug_mode or config._startup_logs_enabled:
             try:
-                info = debug.collect()
+                tracer_debug_info = TracerDebugInfo(
+                    writer=self._span_aggregator.writer,
+                    sampling_rules=self._sampler.rules,
+                    tags=self._tags,
+                    partial_flush_enabled=self._span_aggregator.partial_flush_enabled,
+                    partial_flush_min_spans=self._span_aggregator.partial_flush_min_spans,
+                )
+                info = debug.collect(tracer_debug_info)
             except Exception as e:
                 msg = "Failed to collect start-up logs: %s" % e
                 self._log_compat(logging.WARNING, "- DATADOG TRACER DIAGNOSTIC - %s" % msg)

ddtrace/commands/ddtrace_run.py

@@ -89,8 +89,9 @@ def _prepare_env(parser: argparse.ArgumentParser):
     if args.info:
         # Inline imports for performance.
         from ddtrace.internal.debug import pretty_collect
+        from ddtrace.trace import tracer
 
-        print(pretty_collect(color=not args.colorless))
+        print(pretty_collect(tracer, color=not args.colorless))
         sys.exit(0)
 
     root_dir = os.path.dirname(ddtrace.__file__)

ddtrace/internal/debug.py

@@ -2,17 +2,18 @@
 import logging
 import platform
 import sys
-from typing import TYPE_CHECKING  # noqa:F401
 from typing import Any  # noqa:F401
 from typing import Union  # noqa:F401
 
-import ddtrace
+from ddtrace import _monkey
 from ddtrace.internal import agent
 from ddtrace.internal.packages import get_distributions
 from ddtrace.internal.settings import env
 from ddtrace.internal.settings._agent import config as agent_config
+from ddtrace.internal.settings._config import config
 from ddtrace.internal.settings.asm import config as asm_config
 from ddtrace.internal.utils.cache import callonce
+from ddtrace.internal.utils.tracer_debug_info import TracerDebugInfo
 from ddtrace.internal.writer import AgentWriterInterface
 from ddtrace.internal.writer import LogWriter
 from ddtrace.version import __version__
@@ -42,38 +43,37 @@ def tags_to_str(tags: dict[str, Any]) -> str:
     return ",".join(["%s:%s" % (k, v) for k, v in tags.items()])
 
 
-def collect() -> dict[str, Any]:
+def collect(tracer_info: TracerDebugInfo) -> dict[str, Any]:
     """Collect system and library information into a serializable dict."""
 
     # Inline expensive imports to avoid unnecessary overhead on startup.
     from ddtrace.internal import gitmetadata
     from ddtrace.internal.runtime.runtime_metrics import RuntimeWorker
     from ddtrace.internal.settings.crashtracker import config as crashtracker_config
-    from ddtrace.trace import tracer
 
-    if isinstance(tracer._span_aggregator.writer, LogWriter):
+    if isinstance(tracer_info.writer, LogWriter):
         agent_url = "AGENTLESS"
         agent_error = None
-    elif isinstance(tracer._span_aggregator.writer, AgentWriterInterface):
-        writer = tracer._span_aggregator.writer
+    elif isinstance(tracer_info.writer, AgentWriterInterface):
+        writer = tracer_info.writer
         agent_url = writer.intake_url
         reachable = agent.is_reachable(agent_url)  # type: ignore[no-untyped-call]
         agent_error = None if reachable else "Agent not reachable at %s" % agent_url
     else:
         agent_url = "CUSTOM"
         agent_error = None
 
-    sampling_rules = [str(rule) for rule in tracer._sampler.rules]
+    sampling_rules = [str(rule) for rule in tracer_info.sampling_rules]
 
     is_venv = in_venv()
 
     packages_available = {name: version for (name, version) in get_distributions().items()}
     integration_configs: dict[str, Union[dict[str, Any], str]] = {}
-    for module, enabled in ddtrace._monkey.PATCH_MODULES.items():
+    for module, enabled in _monkey.PATCH_MODULES.items():
         # TODO: this check doesn't work in all cases... we need a mapping
         #       between the module and the library name.
         module_available = module in packages_available
-        module_instrumented = module in ddtrace._monkey._PATCHED_MODULES
+        module_instrumented = module in _monkey._PATCHED_MODULES
         module_imported = module in sys.modules
 
         if enabled:
@@ -83,17 +83,17 @@ def collect() -> dict[str, Any]:
             # This also doesn't load work in all cases since we don't always
             # name the configuration entry the same as the integration module
             # name :/
-            config = ddtrace.config._config.get(module, "N/A")
+            module_config = config._config.get(module, "N/A")
         else:
-            config = None
+            module_config = None
 
         if module_available:
             integration_configs[module] = dict(
                 enabled=enabled,
                 instrumented=module_instrumented,
                 module_version=packages_available[module],
                 module_imported=module_imported,
-                config=config,
+                config=module_config,
             )
 
     pip_version = packages_available.get("pip", "N/A")
@@ -117,26 +117,26 @@ def collect() -> dict[str, Any]:
         agent_url=agent_url,
         agent_error=agent_error,
         statsd_url=agent_config.dogstatsd_url,
-        env=ddtrace.config.env or "",
-        ddtrace_enabled=ddtrace.config._tracing_enabled,
+        env=config.env or "",
+        ddtrace_enabled=config._tracing_enabled,
         sampling_rules=sampling_rules,
-        service=ddtrace.config.service or "",
+        service=config.service or "",
         debug=logger.isEnabledFor(logging.DEBUG),
         enabled_cli="ddtrace" in env.get("PYTHONPATH", ""),
-        log_injection_enabled=ddtrace.config._logs_injection,
-        health_metrics_enabled=ddtrace.config._health_metrics_enabled,
+        log_injection_enabled=config._logs_injection,
+        health_metrics_enabled=config._health_metrics_enabled,
         runtime_metrics_enabled=RuntimeWorker.enabled,
-        dd_version=ddtrace.config.version or "",
-        global_tags=tags_to_str(ddtrace.config.tags),
-        tracer_tags=tags_to_str(tracer._tags),
+        dd_version=config.version or "",
+        global_tags=tags_to_str(config.tags),
+        tracer_tags=tags_to_str(tracer_info.tags),
         integrations=integration_configs,
-        partial_flush_enabled=tracer._span_aggregator.partial_flush_enabled,
-        partial_flush_min_spans=tracer._span_aggregator.partial_flush_min_spans,
+        partial_flush_enabled=tracer_info.partial_flush_enabled,
+        partial_flush_min_spans=tracer_info.partial_flush_min_spans,
         asm_enabled=asm_config._asm_enabled,
         iast_enabled=asm_config._iast_enabled,
         waf_timeout=asm_config._waf_timeout,
-        remote_config_enabled=ddtrace.config._remote_config_enabled,
-        config_endpoint=ddtrace.config._from_endpoint,
+        remote_config_enabled=config._remote_config_enabled,
+        config_endpoint=config._from_endpoint,
         crashtracking_enabled=crashtracker_config.enabled,
         gitmetadata_enabled=gitmetadata.config.enabled,
         git_repository_url=git_repository_url,
@@ -146,7 +146,7 @@ def collect() -> dict[str, Any]:
     )
 
 
-def pretty_collect(color=True):
+def pretty_collect(tracer: Any, color=True):
     class bcolors:
         HEADER = "\033[95m"
         OKBLUE = "\033[94m"
@@ -167,7 +167,7 @@ class bcolors:
         bcolors.ENDC = ""
         bcolors.BOLD = ""
 
-    info = collect()
+    info = collect(TracerDebugInfo.from_tracer(tracer))
 
     info_pretty = """{blue}{bold}Tracer Configurations:{end}
     Tracer enabled: {tracer_enabled}

ddtrace/internal/utils/tracer_debug_info.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass
+class TracerDebugInfo:
+    """Tracer state consumed by ddtrace.internal.debug.collect()."""
+
+    writer: Any
+    sampling_rules: list[Any]
+    tags: dict[str, Any]
+    partial_flush_enabled: bool
+    partial_flush_min_spans: int
+
+    @classmethod
+    def from_tracer(cls, tracer: Any) -> TracerDebugInfo:
+        return cls(
+            writer=tracer._span_aggregator.writer,
+            sampling_rules=tracer._sampler.rules,
+            tags=tracer._tags,
+            partial_flush_enabled=tracer._span_aggregator.partial_flush_enabled,
+            partial_flush_min_spans=tracer._span_aggregator.partial_flush_min_spans,
+        )

tests/integration/test_debug.py

@@ -32,8 +32,10 @@ def test_standard_tags():
     from datetime import datetime
 
     from ddtrace.internal import debug
+    from ddtrace.internal.utils.tracer_debug_info import TracerDebugInfo
+    from ddtrace.trace import tracer
 
-    f = debug.collect()
+    f = debug.collect(TracerDebugInfo.from_tracer(tracer))
 
     date = f.get("date")
     assert isinstance(date, str)
@@ -97,8 +99,10 @@ def test_debug_post_configure_uds():
     import re
 
     from ddtrace.internal import debug
+    from ddtrace.internal.utils.tracer_debug_info import TracerDebugInfo
+    from ddtrace.trace import tracer
 
-    f = debug.collect()
+    f = debug.collect(TracerDebugInfo.from_tracer(tracer))
 
     agent_url = f.get("agent_url")
     assert agent_url == "unix:///file.sock"
@@ -121,7 +125,10 @@ class TestGlobalConfig(SubprocessTestCase):
         )
     )
     def test_env_config(self):
-        f = debug.collect()
+        from ddtrace.internal.utils.tracer_debug_info import TracerDebugInfo
+        from ddtrace.trace import tracer
+
+        f = debug.collect(TracerDebugInfo.from_tracer(tracer))
         assert f.get("agent_url") == "http://0.0.0.0:4321"
         assert f.get("health_metrics_enabled") is True
         assert f.get("log_injection_enabled") is True
@@ -141,7 +148,10 @@ def test_env_config(self):
         )
     )
     def test_trace_agent_url(self):
-        f = debug.collect()
+        from ddtrace.internal.utils.tracer_debug_info import TracerDebugInfo
+        from ddtrace.trace import tracer
+
+        f = debug.collect(TracerDebugInfo.from_tracer(tracer))
         assert f.get("agent_url") == "http://0.0.0.0:1234"
 
     @run_in_subprocess(
@@ -211,17 +221,19 @@ def test_tracer_info_level_log(self):
 @pytest.mark.subprocess(ddtrace_run=True, err=None)
 def test_runtime_metrics_enabled_via_manual_start():
     from ddtrace.internal import debug
+    from ddtrace.internal.utils.tracer_debug_info import TracerDebugInfo
     from ddtrace.runtime import RuntimeMetrics
+    from ddtrace.trace import tracer
 
-    f = debug.collect()
+    f = debug.collect(TracerDebugInfo.from_tracer(tracer))
     assert f.get("runtime_metrics_enabled") is False
 
     RuntimeMetrics.enable()
-    f = debug.collect()
+    f = debug.collect(TracerDebugInfo.from_tracer(tracer))
     assert f.get("runtime_metrics_enabled") is True
 
     RuntimeMetrics.disable()
-    f = debug.collect()
+    f = debug.collect(TracerDebugInfo.from_tracer(tracer))
     assert f.get("runtime_metrics_enabled") is False
 
 
@@ -231,24 +243,31 @@ def test_runtime_metrics_enabled_via_env_var_start():
 
     from ddtrace.internal import debug
     from ddtrace.internal.utils.formats import asbool
+    from ddtrace.internal.utils.tracer_debug_info import TracerDebugInfo
+    from ddtrace.trace import tracer
 
-    f = debug.collect()
+    f = debug.collect(TracerDebugInfo.from_tracer(tracer))
     assert f.get("runtime_metrics_enabled") is asbool(os.getenv("DD_RUNTIME_METRICS_ENABLED")), (
         f.get("runtime_metrics_enabled"),
         asbool(os.getenv("DD_RUNTIME_METRICS_ENABLED")),
     )
 
 
 def test_to_json():
-    info = debug.collect()
+    from ddtrace.internal.utils.tracer_debug_info import TracerDebugInfo
+    from ddtrace.trace import tracer
+
+    info = debug.collect(TracerDebugInfo.from_tracer(tracer))
     json.dumps(info)
 
 
 @pytest.mark.subprocess(env={"AWS_LAMBDA_FUNCTION_NAME": "something"})
 def test_agentless(monkeypatch):
     from ddtrace.internal import debug
+    from ddtrace.internal.utils.tracer_debug_info import TracerDebugInfo
+    from ddtrace.trace import tracer
 
-    info = debug.collect()
+    info = debug.collect(TracerDebugInfo.from_tracer(tracer))
     assert info.get("agent_url") == "AGENTLESS"
 
 
@@ -257,6 +276,7 @@ def test_custom_writer():
     from typing import Optional
 
     from ddtrace.internal import debug
+    from ddtrace.internal.utils.tracer_debug_info import TracerDebugInfo
     from ddtrace.internal.writer import TraceWriter
     from ddtrace.trace import Span
     from ddtrace.trace import tracer
@@ -275,16 +295,18 @@ def flush_queue(self) -> None:
             pass
 
     tracer._span_aggregator.writer = CustomWriter()
-    info = debug.collect()
+    info = debug.collect(TracerDebugInfo.from_tracer(tracer))
 
     assert info.get("agent_url") == "CUSTOM"
 
 
 @pytest.mark.subprocess(env={"DD_TRACE_SAMPLING_RULES": '[{"sample_rate":1.0}]'})
 def test_startup_logs_sampling_rules():
     from ddtrace.internal import debug
+    from ddtrace.internal.utils.tracer_debug_info import TracerDebugInfo
+    from ddtrace.trace import tracer
 
-    f = debug.collect()
+    f = debug.collect(TracerDebugInfo.from_tracer(tracer))
 
     assert f.get("sampling_rules") == [
         "SamplingRule(sample_rate=1.0, service=None, name=None, resource=None, tags={}, provenance=default)"
@@ -294,17 +316,21 @@ def test_startup_logs_sampling_rules():
 @pytest.mark.subprocess()
 def test_startup_logs_log_level_override_default():
     from ddtrace.internal import debug
+    from ddtrace.internal.utils.tracer_debug_info import TracerDebugInfo
+    from ddtrace.trace import tracer
 
-    f = debug.collect()
+    f = debug.collect(TracerDebugInfo.from_tracer(tracer))
 
     assert f.get("log_level_override") is None
 
 
 @pytest.mark.subprocess(env={"DD_TRACE_LOG_LEVEL": "WARNING"})
 def test_startup_logs_log_level_override_set():
     from ddtrace.internal import debug
+    from ddtrace.internal.utils.tracer_debug_info import TracerDebugInfo
+    from ddtrace.trace import tracer
 
-    f = debug.collect()
+    f = debug.collect(TracerDebugInfo.from_tracer(tracer))
 
     assert f.get("log_level_override") == "WARNING"
 
@@ -379,8 +405,10 @@ def test_debug_span_log():
 )
 def test_partial_flush_log():
     from ddtrace.internal import debug
+    from ddtrace.internal.utils.tracer_debug_info import TracerDebugInfo
+    from ddtrace.trace import tracer
 
-    f = debug.collect()
+    f = debug.collect(TracerDebugInfo.from_tracer(tracer))
 
     partial_flush_enabled = f.get("partial_flush_enabled")
     partial_flush_min_spans = f.get("partial_flush_min_spans")