chore(trace_utils): move implementation details to internal [3.0] (#1…

…2002)

## Motivation

- Create a unified public interface for all contrib utils. We will
deprecate and redesign this interface in v3.0.
- Ensure the `ddtrace.contrib.internal` package is self contained and
does rely on `ddtrace.contrib` public interfaces.

## Changes

- Deprecates `ddtrace.contrib.redis_utils` module. Expose all public
redis_utils in `ddtrace.contrib.trace_utils` (for now).
- Deprecates `ddtrace.contrib.trace_utils_async` module. Expose all
public async utils to `ddtrace.contrib.trace_utils`.
- Deprecates `trace_handlers`, `func_name`, `module_name`, and
`require_modules` functions exposed in `ddtrace.contrib.__init__`. These
functions are internal to ddtrace.
- Moves the implementation details of `trace_utils`,
`trace_utils_async`, and `redis_utils` to
`ddtrace.contrib.internal.trace_util`.
 

## 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](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
- [ ] 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)

ddtrace/_trace/trace_handlers.py

@@ -22,7 +22,7 @@
 from ddtrace.constants import SPAN_MEASURED_KEY
 from ddtrace.contrib import trace_utils
 from ddtrace.contrib.internal.botocore.constants import BOTOCORE_STEPFUNCTIONS_INPUT_KEY
-from ddtrace.contrib.trace_utils import _set_url_tag
+from ddtrace.contrib.internal.trace_utils import _set_url_tag
 from ddtrace.ext import SpanKind
 from ddtrace.ext import db
 from ddtrace.ext import http

ddtrace/_trace/utils_redis.py

@@ -10,7 +10,7 @@
 from ddtrace.constants import SPAN_KIND
 from ddtrace.constants import SPAN_MEASURED_KEY
 from ddtrace.contrib import trace_utils
-from ddtrace.contrib.redis_utils import _extract_conn_tags
+from ddtrace.contrib.internal.redis_utils import _extract_conn_tags
 from ddtrace.ext import SpanKind
 from ddtrace.ext import SpanTypes
 from ddtrace.ext import db

ddtrace/appsec/_handlers.py

@@ -6,8 +6,8 @@
 from ddtrace.appsec._asm_request_context import get_blocked
 from ddtrace.appsec._constants import SPAN_DATA_NAMES
 from ddtrace.contrib import trace_utils
-from ddtrace.contrib.trace_utils import _get_request_header_user_agent
-from ddtrace.contrib.trace_utils import _set_url_tag
+from ddtrace.contrib.internal.trace_utils import _get_request_header_user_agent
+from ddtrace.contrib.internal.trace_utils import _set_url_tag
 from ddtrace.ext import SpanTypes
 from ddtrace.ext import http
 from ddtrace.internal import core

ddtrace/appsec/_processor.py

@@ -101,7 +101,7 @@ def get_rules() -> str:
 
 
 def _set_headers(span: Span, headers: Any, kind: str, only_asm_enabled: bool = False) -> None:
-    from ddtrace.contrib.trace_utils import _normalize_tag_name
+    from ddtrace.contrib.internal.trace_utils import _normalize_tag_name
 
     for k in headers:
         if isinstance(k, tuple):
@@ -218,7 +218,7 @@ def rasp_sqli_enabled(self) -> bool:
         return WAF_DATA_NAMES.SQLI_ADDRESS in self._addresses_to_keep
 
     def on_span_start(self, span: Span) -> None:
-        from ddtrace.contrib import trace_utils
+        from ddtrace.contrib.internal import trace_utils
 
         if not hasattr(self, "_ddwaf"):
             self.delayed_init()

ddtrace/appsec/_trace_utils.py

@@ -11,7 +11,7 @@
 from ddtrace.appsec._constants import LOGIN_EVENTS_MODE
 from ddtrace.appsec._constants import WAF_ACTIONS
 from ddtrace.appsec._utils import _hash_user_id
-from ddtrace.contrib.trace_utils import set_user
+from ddtrace.contrib.internal.trace_utils import set_user
 from ddtrace.ext import SpanTypes
 from ddtrace.ext import user
 from ddtrace.internal import core

ddtrace/appsec/_utils.py

@@ -22,7 +22,7 @@ def parse_response_body(raw_body):
 
     from ddtrace.appsec import _asm_request_context
     from ddtrace.appsec._constants import SPAN_DATA_NAMES
-    from ddtrace.contrib.trace_utils import _get_header_value_case_insensitive
+    from ddtrace.contrib.internal.trace_utils import _get_header_value_case_insensitive
 
     if not raw_body:
         return

ddtrace/contrib/__init__.py

@@ -1,4 +1,19 @@
 from ddtrace._trace import trace_handlers  # noqa:F401
+from ddtrace.internal.utils.deprecations import DDTraceDeprecationWarning
 from ddtrace.internal.utils.importlib import func_name  # noqa:F401
 from ddtrace.internal.utils.importlib import module_name  # noqa:F401
 from ddtrace.internal.utils.importlib import require_modules  # noqa:F401
+from ddtrace.vendor.debtcollector import deprecate
+
+
+def __getattr__(name):
+    if name in ("trace_handlers", "func_name", "module_name", "require_modules"):
+        deprecate(
+            ("%s.%s is deprecated" % (__name__, name)),
+            category=DDTraceDeprecationWarning,
+            removal_version="3.0.0",
+        )
+
+    if name in globals():
+        return globals()[name]
+    raise AttributeError("%s has no attribute %s", __name__, name)

ddtrace/contrib/dbapi/__init__.py

@@ -21,8 +21,8 @@
 from ...ext import db
 from ...ext import sql
 from ...trace import Pin
-from ..trace_utils import ext_service
-from ..trace_utils import iswrapped
+from ..internal.trace_utils import ext_service
+from ..internal.trace_utils import iswrapped
 
 
 log = get_logger(__name__)

ddtrace/contrib/dbapi_async/__init__.py

@@ -16,8 +16,8 @@
 from ...trace import Pin
 from ..dbapi import TracedConnection
 from ..dbapi import TracedCursor
-from ..trace_utils import ext_service
-from ..trace_utils import iswrapped
+from ..internal.trace_utils import ext_service
+from ..internal.trace_utils import iswrapped
 
 
 log = get_logger(__name__)

ddtrace/contrib/internal/aiobotocore/patch.py

@@ -7,8 +7,8 @@
 from ddtrace.constants import _ANALYTICS_SAMPLE_RATE_KEY
 from ddtrace.constants import SPAN_KIND
 from ddtrace.constants import SPAN_MEASURED_KEY
-from ddtrace.contrib.trace_utils import ext_service
-from ddtrace.contrib.trace_utils import unwrap
+from ddtrace.contrib.internal.trace_utils import ext_service
+from ddtrace.contrib.internal.trace_utils import unwrap
 from ddtrace.ext import SpanKind
 from ddtrace.ext import SpanTypes
 from ddtrace.ext import aws

ddtrace/contrib/internal/aiohttp/patch.py

@@ -6,13 +6,13 @@
 
 from ddtrace import config
 from ddtrace.constants import SPAN_KIND
-from ddtrace.contrib.trace_utils import ext_service
-from ddtrace.contrib.trace_utils import extract_netloc_and_query_info_from_url
-from ddtrace.contrib.trace_utils import set_http_meta
-from ddtrace.contrib.trace_utils import unwrap
-from ddtrace.contrib.trace_utils import with_traced_module as with_traced_module_sync
-from ddtrace.contrib.trace_utils import wrap
-from ddtrace.contrib.trace_utils_async import with_traced_module
+from ddtrace.contrib.internal.trace_utils import ext_service
+from ddtrace.contrib.internal.trace_utils import extract_netloc_and_query_info_from_url
+from ddtrace.contrib.internal.trace_utils import set_http_meta
+from ddtrace.contrib.internal.trace_utils import unwrap
+from ddtrace.contrib.internal.trace_utils import with_traced_module as with_traced_module_sync
+from ddtrace.contrib.internal.trace_utils import wrap
+from ddtrace.contrib.internal.trace_utils_async import with_traced_module
 from ddtrace.ext import SpanKind
 from ddtrace.ext import SpanTypes
 from ddtrace.internal.constants import COMPONENT

ddtrace/contrib/internal/aiohttp_jinja2/patch.py

@@ -1,9 +1,9 @@
 import aiohttp_jinja2
 
 from ddtrace import config
-from ddtrace.contrib.trace_utils import unwrap
-from ddtrace.contrib.trace_utils import with_traced_module
-from ddtrace.contrib.trace_utils import wrap
+from ddtrace.contrib.internal.trace_utils import unwrap
+from ddtrace.contrib.internal.trace_utils import with_traced_module
+from ddtrace.contrib.internal.trace_utils import wrap
 from ddtrace.ext import SpanTypes
 from ddtrace.internal.constants import COMPONENT
 from ddtrace.internal.utils import get_argument_value

ddtrace/contrib/internal/aiomysql/patch.py

@@ -7,6 +7,7 @@
 from ddtrace.constants import SPAN_MEASURED_KEY
 from ddtrace.contrib import dbapi
 from ddtrace.contrib import trace_utils
+from ddtrace.contrib.internal.trace_utils import _convert_to_string
 from ddtrace.ext import SpanKind
 from ddtrace.ext import SpanTypes
 from ddtrace.ext import db
@@ -48,7 +49,7 @@ async def patched_connect(connect_func, _, args, kwargs):
     tags = {}
     for tag, attr in CONN_ATTR_BY_TAG.items():
         if hasattr(conn, attr):
-            tags[tag] = trace_utils._convert_to_string(getattr(conn, attr, None))
+            tags[tag] = _convert_to_string(getattr(conn, attr, None))
     tags[db.SYSTEM] = "mysql"
 
     c = AIOTracedConnection(conn)

ddtrace/contrib/internal/aioredis/patch.py

@@ -12,8 +12,8 @@
 from ddtrace.constants import SPAN_KIND
 from ddtrace.constants import SPAN_MEASURED_KEY
 from ddtrace.contrib import trace_utils
+from ddtrace.contrib.internal.redis_utils import _run_redis_command_async
 from ddtrace.contrib.redis_utils import ROW_RETURNING_COMMANDS
-from ddtrace.contrib.redis_utils import _run_redis_command_async
 from ddtrace.contrib.redis_utils import determine_row_count
 from ddtrace.ext import SpanKind
 from ddtrace.ext import SpanTypes

ddtrace/contrib/internal/anthropic/patch.py

@@ -11,9 +11,9 @@
 from ddtrace.contrib.internal.anthropic.utils import tag_params_on_span
 from ddtrace.contrib.internal.anthropic.utils import tag_tool_result_input_on_span
 from ddtrace.contrib.internal.anthropic.utils import tag_tool_use_input_on_span
-from ddtrace.contrib.trace_utils import unwrap
-from ddtrace.contrib.trace_utils import with_traced_module
-from ddtrace.contrib.trace_utils import wrap
+from ddtrace.contrib.internal.trace_utils import unwrap
+from ddtrace.contrib.internal.trace_utils import with_traced_module
+from ddtrace.contrib.internal.trace_utils import wrap
 from ddtrace.internal.logger import get_logger
 from ddtrace.internal.utils import get_argument_value
 from ddtrace.llmobs._integrations import AnthropicIntegration

ddtrace/contrib/internal/aredis/patch.py

@@ -6,7 +6,7 @@
 from ddtrace import config
 from ddtrace._trace.utils_redis import _instrument_redis_cmd
 from ddtrace._trace.utils_redis import _instrument_redis_execute_pipeline
-from ddtrace.contrib.redis_utils import _run_redis_command_async
+from ddtrace.contrib.internal.redis_utils import _run_redis_command_async
 from ddtrace.internal.schema import schematize_service_name
 from ddtrace.internal.utils.formats import CMD_MAX_LEN
 from ddtrace.internal.utils.formats import asbool

ddtrace/contrib/internal/asyncpg/patch.py

@@ -19,10 +19,10 @@
 from ddtrace.internal.schema import schematize_service_name
 from ddtrace.internal.utils import get_argument_value
 from ddtrace.propagation._database_monitoring import _DBM_Propagator
-from ddtrace.contrib.trace_utils import ext_service
-from ddtrace.contrib.trace_utils import unwrap
-from ddtrace.contrib.trace_utils import wrap
-from ddtrace.contrib.trace_utils_async import with_traced_module
+from ddtrace.contrib.internal.trace_utils import ext_service
+from ddtrace.contrib.internal.trace_utils import unwrap
+from ddtrace.contrib.internal.trace_utils import wrap
+from ddtrace.contrib.internal.trace_utils_async import with_traced_module
 
 
 if TYPE_CHECKING:  # pragma: no cover

ddtrace/contrib/internal/azure_functions/patch.py

@@ -2,8 +2,8 @@
 from wrapt import wrap_function_wrapper as _w
 
 from ddtrace import config
-from ddtrace.contrib.trace_utils import int_service
-from ddtrace.contrib.trace_utils import unwrap as _u
+from ddtrace.contrib.internal.trace_utils import int_service
+from ddtrace.contrib.internal.trace_utils import unwrap as _u
 from ddtrace.ext import SpanTypes
 from ddtrace.internal import core
 from ddtrace.internal.schema import schematize_cloud_faas_operation

ddtrace/contrib/internal/botocore/patch.py

@@ -17,9 +17,9 @@
 
 from ddtrace import config
 from ddtrace.constants import SPAN_KIND
-from ddtrace.contrib.trace_utils import ext_service
-from ddtrace.contrib.trace_utils import unwrap
-from ddtrace.contrib.trace_utils import with_traced_module
+from ddtrace.contrib.internal.trace_utils import ext_service
+from ddtrace.contrib.internal.trace_utils import unwrap
+from ddtrace.contrib.internal.trace_utils import with_traced_module
 from ddtrace.ext import SpanKind
 from ddtrace.ext import SpanTypes
 from ddtrace.internal import core

ddtrace/contrib/internal/botocore/services/bedrock.py

@@ -7,7 +7,7 @@
 import wrapt
 
 from ddtrace import config
-from ddtrace.contrib.trace_utils import ext_service
+from ddtrace.contrib.internal.trace_utils import ext_service
 from ddtrace.ext import SpanTypes
 from ddtrace.internal import core
 from ddtrace.internal.logger import get_logger

ddtrace/contrib/internal/botocore/services/kinesis.py

@@ -10,7 +10,7 @@
 import botocore.exceptions
 
 from ddtrace import config
-from ddtrace.contrib.trace_utils import ext_service
+from ddtrace.contrib.internal.trace_utils import ext_service
 from ddtrace.ext import SpanTypes
 from ddtrace.internal import core
 from ddtrace.internal.logger import get_logger

ddtrace/contrib/internal/botocore/services/sqs.py

@@ -7,7 +7,7 @@
 import botocore.exceptions
 
 from ddtrace import config
-from ddtrace.contrib.trace_utils import ext_service
+from ddtrace.contrib.internal.trace_utils import ext_service
 from ddtrace.ext import SpanTypes
 from ddtrace.internal import core
 from ddtrace.internal.logger import get_logger

ddtrace/contrib/internal/botocore/services/stepfunctions.py

@@ -6,7 +6,7 @@
 
 from ddtrace import config
 from ddtrace.contrib.internal.botocore.constants import BOTOCORE_STEPFUNCTIONS_INPUT_KEY
-from ddtrace.contrib.trace_utils import ext_service
+from ddtrace.contrib.internal.trace_utils import ext_service
 from ddtrace.ext import SpanTypes
 from ddtrace.internal import core
 from ddtrace.internal.logger import get_logger

ddtrace/contrib/internal/celery/utils.py

@@ -3,7 +3,7 @@
 from weakref import WeakValueDictionary
 
 from ddtrace._trace.span import Span
-from ddtrace.contrib.trace_utils import set_flattened_tags
+from ddtrace.contrib.internal.trace_utils import set_flattened_tags
 from ddtrace.propagation.http import HTTPPropagator
 
 from .constants import CTX_KEY

ddtrace/contrib/internal/django/patch.py

@@ -23,7 +23,8 @@
 from ddtrace.constants import SPAN_KIND
 from ddtrace.contrib import dbapi
 from ddtrace.contrib import trace_utils
-from ddtrace.contrib.trace_utils import _get_request_header_user_agent
+from ddtrace.contrib.internal.trace_utils import _convert_to_string
+from ddtrace.contrib.internal.trace_utils import _get_request_header_user_agent
 from ddtrace.ext import SpanKind
 from ddtrace.ext import SpanTypes
 from ddtrace.ext import db
@@ -127,7 +128,7 @@ def patch_conn(django, conn):
     for tag, attr in DB_CONN_ATTR_BY_TAG.items():
         if attr in settings_dict:
             try:
-                tags[tag] = trace_utils._convert_to_string(conn.settings_dict.get(attr))
+                tags[tag] = _convert_to_string(conn.settings_dict.get(attr))
             except Exception:
                 tags[tag] = str(conn.settings_dict.get(attr))
     conn._datadog_tags = tags

ddtrace/contrib/internal/django/restframework.py

@@ -1,8 +1,8 @@
 import rest_framework.views
 from wrapt import wrap_function_wrapper as wrap
 
-from ddtrace.contrib.trace_utils import iswrapped
-from ddtrace.contrib.trace_utils import with_traced_module
+from ddtrace.contrib.internal.trace_utils import iswrapped
+from ddtrace.contrib.internal.trace_utils import with_traced_module
 
 
 @with_traced_module

ddtrace/contrib/internal/elasticsearch/patch.py

@@ -9,8 +9,8 @@
 from ddtrace.constants import SPAN_KIND
 from ddtrace.constants import SPAN_MEASURED_KEY
 from ddtrace.contrib.internal.elasticsearch.quantize import quantize
-from ddtrace.contrib.trace_utils import ext_service
-from ddtrace.contrib.trace_utils import extract_netloc_and_query_info_from_url
+from ddtrace.contrib.internal.trace_utils import ext_service
+from ddtrace.contrib.internal.trace_utils import extract_netloc_and_query_info_from_url
 from ddtrace.ext import SpanKind
 from ddtrace.ext import SpanTypes
 from ddtrace.ext import elasticsearch as metadata

ddtrace/contrib/internal/flask/patch.py

@@ -30,8 +30,8 @@
 from wrapt import wrap_function_wrapper as _w
 
 from ddtrace import config
+from ddtrace.contrib.internal.trace_utils import unwrap as _u
 from ddtrace.contrib.internal.wsgi.wsgi import _DDWSGIMiddlewareBase
-from ddtrace.contrib.trace_utils import unwrap as _u
 from ddtrace.internal.logger import get_logger
 from ddtrace.internal.utils import get_argument_value
 from ddtrace.internal.utils.importlib import func_name

ddtrace/contrib/internal/google_generativeai/patch.py

@@ -9,9 +9,9 @@
 from ddtrace.contrib.internal.google_generativeai._utils import _extract_api_key
 from ddtrace.contrib.internal.google_generativeai._utils import tag_request
 from ddtrace.contrib.internal.google_generativeai._utils import tag_response
-from ddtrace.contrib.trace_utils import unwrap
-from ddtrace.contrib.trace_utils import with_traced_module
-from ddtrace.contrib.trace_utils import wrap
+from ddtrace.contrib.internal.trace_utils import unwrap
+from ddtrace.contrib.internal.trace_utils import with_traced_module
+from ddtrace.contrib.internal.trace_utils import wrap
 from ddtrace.llmobs._integrations import GeminiIntegration
 from ddtrace.llmobs._integrations.utils import extract_model_name_google
 from ddtrace.trace import Pin

ddtrace/contrib/internal/grpc/patch.py

@@ -7,7 +7,7 @@
 from ddtrace.contrib.internal.grpc.client_interceptor import create_client_interceptor
 from ddtrace.contrib.internal.grpc.client_interceptor import intercept_channel
 from ddtrace.contrib.internal.grpc.server_interceptor import create_server_interceptor
-from ddtrace.contrib.trace_utils import unwrap as _u
+from ddtrace.contrib.internal.trace_utils import unwrap as _u
 from ddtrace.internal.logger import get_logger
 from ddtrace.internal.schema import schematize_service_name
 from ddtrace.internal.utils import get_argument_value

ddtrace/contrib/internal/httplib/patch.py

@@ -9,7 +9,7 @@
 from ddtrace.constants import _ANALYTICS_SAMPLE_RATE_KEY
 from ddtrace.constants import SPAN_KIND
 from ddtrace.contrib import trace_utils
-from ddtrace.contrib.trace_utils import unwrap as _u
+from ddtrace.contrib.internal.trace_utils import unwrap as _u
 from ddtrace.ext import SpanKind
 from ddtrace.ext import SpanTypes
 from ddtrace.internal.compat import httplib

ddtrace/contrib/internal/httpx/patch.py

@@ -8,9 +8,9 @@
 from ddtrace.constants import _ANALYTICS_SAMPLE_RATE_KEY
 from ddtrace.constants import SPAN_KIND
 from ddtrace.constants import SPAN_MEASURED_KEY
-from ddtrace.contrib.trace_utils import distributed_tracing_enabled
-from ddtrace.contrib.trace_utils import ext_service
-from ddtrace.contrib.trace_utils import set_http_meta
+from ddtrace.contrib.internal.trace_utils import distributed_tracing_enabled
+from ddtrace.contrib.internal.trace_utils import ext_service
+from ddtrace.contrib.internal.trace_utils import set_http_meta
 from ddtrace.ext import SpanKind
 from ddtrace.ext import SpanTypes
 from ddtrace.internal.compat import ensure_binary

ddtrace/contrib/internal/jinja2/patch.py

@@ -5,7 +5,7 @@
 
 from ddtrace import config
 from ddtrace.constants import SPAN_MEASURED_KEY
-from ddtrace.contrib.trace_utils import unwrap as _u
+from ddtrace.contrib.internal.trace_utils import unwrap as _u
 from ddtrace.ext import SpanTypes
 from ddtrace.internal.constants import COMPONENT
 from ddtrace.internal.utils import ArgumentError