chore(tracer): deprecates patch_all (#11918)

## 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: Emmett Butler <[email protected]>

Author: ZStriker19

benchmarks/ddtrace_run/scenario.py

@@ -22,7 +22,7 @@ def run(self):
 
         # initialize subprocess args
         subp_cmd = []
-        code = "import ddtrace; ddtrace.patch_all()\n"
+        code = "import ddtrace; ddtrace._monkey._patch_all()\n"
         if self.ddtrace_run:
             subp_cmd = ["ddtrace-run"]
             code = ""

ddtrace/_monkey.py

@@ -9,10 +9,12 @@
 from ddtrace.appsec import load_common_appsec_modules
 from ddtrace.internal.telemetry.constants import TELEMETRY_NAMESPACE
 from ddtrace.settings.asm import config as asm_config
+from ddtrace.vendor.debtcollector import deprecate
 
 from .internal import telemetry
 from .internal.logger import get_logger
 from .internal.utils import formats
+from .internal.utils.deprecations import DDTraceDeprecationWarning  # noqa: E402
 
 
 if TYPE_CHECKING:  # pragma: no cover
@@ -224,8 +226,18 @@ def patch_all(**patch_modules: bool) -> None:
 
     :param dict patch_modules: Override whether particular modules are patched or not.
 
-        >>> patch_all(redis=False, cassandra=False)
+        >>> _patch_all(redis=False, cassandra=False)
     """
+    deprecate(
+        "patch_all is deprecated and will be removed in a future version of the tracer.",
+        message="""patch_all is deprecated in favor of ``import ddtrace.auto`` and ``DD_PATCH_MODULES``
+        environment variable if needed.""",
+        category=DDTraceDeprecationWarning,
+    )
+    _patch_all(**patch_modules)
+
+
+def _patch_all(**patch_modules: bool) -> None:
     modules = PATCH_MODULES.copy()
 
     # The enabled setting can be overridden by environment variables

ddtrace/bootstrap/preload.py

@@ -87,7 +87,7 @@ def _(_):
     LLMObs.enable(_auto=True)
 
 if asbool(os.getenv("DD_TRACE_ENABLED", default=True)):
-    from ddtrace import patch_all
+    from ddtrace._monkey import _patch_all
 
     @register_post_preload
     def _():
@@ -97,7 +97,7 @@ def _():
         modules_to_patch = os.getenv("DD_PATCH_MODULES")
         modules_to_str = parse_tags_str(modules_to_patch)
         modules_to_bool = {k: asbool(v) for k, v in modules_to_str.items()}
-        patch_all(**modules_to_bool)
+        _patch_all(**modules_to_bool)
 
     if config._trace_methods:
         _install_trace_methods(config._trace_methods)

ddtrace/contrib/_aws_lambda.py

@@ -13,10 +13,7 @@
 Global Configuration
 ~~~~~~~~~~~~~~~~~~~~
 
-This integration is configured automatically. The `datadog_lambda` package
-calls ``patch_all`` when ``DD_TRACE_ENABLED`` is set to ``true``.
-It's not recommended to call ``patch`` for it manually. Since it would not do
-anything for other environments that do not meet the criteria above.
+This integration is configured automatically when `ddtrace-run` or `import ddtrace.auto` is used.
 
 
 Configuration

ddtrace/contrib/_httplib.py

@@ -8,15 +8,9 @@
 
 The httplib integration is disabled by default. It can be enabled when using
 :ref:`ddtrace-run<ddtracerun>` or :ref:`import ddtrace.auto<ddtraceauto>`
-using the ``DD_TRACE_HTTPLIB_ENABLED`` environment variable::
+using the `DD_PATCH_MODULES` environment variable or `DD_TRACE_HTTPLIB_ENABLED`::
 
-    DD_TRACE_HTTPLIB_ENABLED=true ddtrace-run ....
-
-The integration can also be enabled manually in code with
-:func:`patch_all()<ddtrace.patch_all>`::
-
-    from ddtrace import patch_all
-    patch_all(httplib=True)
+    DD_PATCH_MODULES=httplib:true ddtrace-run ....
 
 
 Global Configuration

ddtrace/contrib/_kombu.py

@@ -1,6 +1,7 @@
 """Instrument kombu to report AMQP messaging.
 
-``patch_all`` will not automatically patch your Kombu client to make it work, as this would conflict with the
+ref:`import ddtrace.auto<ddtraceauto>` and `ddtrace-run` will not automatically patch your Kombu client to
+make it work, as this would conflict with the
 Celery integration. You must specifically request kombu be patched, as in the example below.
 
 Note: To permit distributed tracing for the kombu integration you must enable the tracer with priority
@@ -9,10 +10,11 @@
 
 Without enabling distributed tracing, spans within a trace generated by the kombu integration might be dropped
 without the whole trace being dropped.
-::
 
-    from ddtrace import patch
-    from ddtrace.trace import Pin
+Run with `DD_PATCH_MODULES=kombu:true`::
+
+    import ddtrace.auto
+    from ddtrace import Pin
     import kombu
 
     # If not patched yet, you can patch kombu specifically

ddtrace/contrib/_sanic.py

@@ -8,8 +8,7 @@
 
 Sanic tracing can also be enabled explicitly::
 
-    from ddtrace import patch_all
-    patch_all(sanic=True)
+    import ddtrace.auto
 
     from sanic import Sanic
     from sanic.response import text

ddtrace/contrib/_snowflake.py

@@ -9,19 +9,8 @@
 The integration is not enabled automatically when using
 :ref:`ddtrace-run<ddtracerun>` or :ref:`import ddtrace.auto<ddtraceauto>`.
 
-Use ``DD_TRACE_SNOWFLAKE_ENABLED=true`` to enable it with ``ddtrace-run``
-
-or :func:`patch()<ddtrace.patch>` to manually enable the integration::
-
-    from ddtrace import patch
-    patch(snowflake=True)
-
-or use :func:`patch_all()<ddtrace.patch_all>` to manually enable the integration::
-
-    from ddtrace import patch_all
-    patch_all(snowflake=True)
-
-
+Use environment variable ``DD_TRACE_SNOWFLAKE_ENABLED=true`` or `DD_PATCH_MODULES:snowflake:true`
+to manually enable the integration.
 
 
 Global Configuration

ddtrace/contrib/_urllib3.py

@@ -6,14 +6,12 @@
 Enabling
 ~~~~~~~~
 
-The ``urllib3`` integration is not enabled by default. Use ``patch_all()``
-with the environment variable ``DD_TRACE_URLLIB3_ENABLED`` set, or call
-:func:`patch()<ddtrace.patch>` with the ``urllib3`` argument set to ``True`` to manually
-enable the integration, before importing and using ``urllib3``::
-
-    from ddtrace import patch
-    patch(urllib3=True)
+The ``urllib3`` integration is not enabled by default. Use either ``ddtrace-run``
+or ``import ddtrace.auto`` with ``DD_PATCH_MODULES`` or ``DD_TRACE_URLLIB3_ENABLED`` to enable it.
+``DD_PATCH_MODULES=urllib3 ddtrace-run python app.py`` or
+``DD_PATCH_MODULES=urllib3:true python app.py``::
 
+    import ddtrace.auto
     # use urllib3 like usual
 
 

ddtrace/contrib/internal/pytest/plugin.py

@@ -40,7 +40,7 @@
 DDTRACE_HELP_MSG = "Enable tracing of pytest functions."
 NO_DDTRACE_HELP_MSG = "Disable tracing of pytest functions."
 DDTRACE_INCLUDE_CLASS_HELP_MSG = "Prepend 'ClassName.' to names of class-based tests."
-PATCH_ALL_HELP_MSG = "Call ddtrace.patch_all before running tests."
+PATCH_ALL_HELP_MSG = "Call ddtrace._patch_all before running tests."
 
 
 def is_enabled(config):
@@ -175,7 +175,7 @@ def patch_all(request):
     """Patch all available modules for Datadog tracing when ddtrace-patch-all
     is specified in command or .ini.
     """
-    import ddtrace
-
     if request.config.getoption("ddtrace-patch-all") or request.config.getini("ddtrace-patch-all"):
-        ddtrace.patch_all()
+        from ddtrace._monkey import _patch_all
+
+        _patch_all()

docs/api.rst

@@ -9,8 +9,6 @@ Tracing
 
 .. automodule:: ddtrace.auto
 
-.. autofunction:: ddtrace.patch_all
-
 .. autofunction:: ddtrace.patch
 
 .. autoclass:: ddtrace.trace.Tracer

releasenotes/notes/deprecate_patch_all-244eddcfacb1da14.yaml

@@ -0,0 +1,4 @@
+---
+deprecations:
+  - |
+    tracer: ``patch_all`` is deprecated. As an alternative to ``patch_all``, you can use ``import ddtrace.auto`` along with ``DD_PATCH_MODULES`` if specific module patching is necessary.

tests/appsec/iast/fixtures/entrypoint/views.py

@@ -22,9 +22,8 @@ def add_test():
 
 
 def create_app_patch_all():
-    from ddtrace import patch_all
+    import ddtrace.auto  # noqa: F401
 
-    patch_all()
     app = Flask(__name__)
     return app
 

tests/commands/test_runner.py

@@ -144,7 +144,7 @@ def test_dogstatsd_client_env_url_path(self):
 
     def test_patch_modules_from_env(self):
         """
-        DD_PATCH_MODULES overrides the defaults for patch_all()
+        DD_PATCH_MODULES overrides the defaults for _patch_all()
         """
         with self.override_env(
             env=dict(

tests/contrib/algoliasearch/test.py

@@ -1,5 +1,5 @@
 from ddtrace import config
-from ddtrace import patch_all
+from ddtrace._monkey import _patch_all
 from ddtrace.contrib.internal.algoliasearch.patch import algoliasearch_version
 from ddtrace.contrib.internal.algoliasearch.patch import patch
 from ddtrace.contrib.internal.algoliasearch.patch import unpatch
@@ -156,8 +156,9 @@ def test_patch_unpatch(self):
         assert len(spans) == 1
 
     def test_patch_all_auto_enable(self):
-        patch_all()
+        _patch_all()
         Pin._override(self.index, tracer=self.tracer)
+
         self.perform_search("test search")
 
         spans = self.get_spans()
@@ -178,7 +179,7 @@ def test_user_specified_service_default(self):
         When a service name is specified by the user
             The algoliasearch integration shouldn't use it as the service name
         """
-        patch_all()
+        _patch_all()
         Pin._override(self.index, tracer=self.tracer)
         self.perform_search("test search")
         spans = self.get_spans()
@@ -194,7 +195,7 @@ def test_user_specified_service_v0(self):
         When a service name is specified by the user
             The algoliasearch integration shouldn't use it as the service name
         """
-        patch_all()
+        _patch_all()
         Pin._override(self.index, tracer=self.tracer)
         self.perform_search("test search")
         spans = self.get_spans()
@@ -210,7 +211,7 @@ def test_user_specified_service_v1(self):
         In the v1 service name schema, services default to $DD_SERVICE,
             so make sure that is used and not the v0 schema 'algoliasearch'
         """
-        patch_all()
+        _patch_all()
         Pin._override(self.index, tracer=self.tracer)
         self.perform_search("test search")
         spans = self.get_spans()
@@ -222,7 +223,7 @@ def test_user_specified_service_v1(self):
 
     @TracerTestCase.run_in_subprocess(env_overrides=dict(DD_TRACE_SPAN_ATTRIBUTE_SCHEMA="v0"))
     def test_span_name_v0_schema(self):
-        patch_all()
+        _patch_all()
         Pin._override(self.index, tracer=self.tracer)
         self.perform_search("test search")
         spans = self.get_spans()
@@ -234,7 +235,7 @@ def test_span_name_v0_schema(self):
 
     @TracerTestCase.run_in_subprocess(env_overrides=dict(DD_TRACE_SPAN_ATTRIBUTE_SCHEMA="v1"))
     def test_span_name_v1_schema(self):
-        patch_all()
+        _patch_all()
         Pin._override(self.index, tracer=self.tracer)
         self.perform_search("test search")
         spans = self.get_spans()

tests/contrib/django/test_django.py

@@ -2120,7 +2120,8 @@ def test_django_use_handler_resource_format_env(client, test_spans):
                 "python",
                 "-c",
                 (
-                    "from ddtrace import config, patch_all; patch_all(); "
+                    "from ddtrace import config; "
+                    "from ddtrace._monkey import _patch_all; _patch_all(); "
                     "import django; "
                     "assert config.django.use_handler_resource_format; print('Test success')"
                 ),
@@ -2139,7 +2140,8 @@ def test_django_use_handler_with_url_name_resource_format_env(client, test_spans
                 "python",
                 "-c",
                 (
-                    "from ddtrace import config, patch_all; patch_all(); "
+                    "from ddtrace import config; "
+                    "from ddtrace._monkey import _patch_all; _patch_all(); "
                     "import django; "
                     "assert config.django.use_handler_with_url_name_resource_format; print('Test success')"
                 ),
@@ -2219,7 +2221,8 @@ def test_django_use_legacy_resource_format_env(client, test_spans):
                 "python",
                 "-c",
                 (
-                    "from ddtrace import config, patch_all; patch_all(); "
+                    "from ddtrace import config; "
+                    "from ddtrace._monkey import _patch_all; _patch_all(); "
                     "import django; "
                     "assert config.django.use_legacy_resource_format; print('Test success')"
                 ),

tests/contrib/psycopg/test_psycopg_snapshot.py

@@ -72,7 +72,7 @@ def test_connect_traced_via_env(run_python_code_in_subprocess):
 import ddtrace
 from tests.contrib.config import POSTGRES_CONFIG
 
-ddtrace.patch_all()
+ddtrace._monkey._patch_all()
 
 conn = psycopg.connect(**POSTGRES_CONFIG)
 assert conn

tests/contrib/psycopg2/test_psycopg.py

@@ -247,9 +247,9 @@ def test_manual_wrap_extension_adapt(self):
 
     @skipIf(PSYCOPG2_VERSION < (2, 7), "quote_ident not available in psycopg2<2.7")
     def test_manual_wrap_extension_quote_ident(self):
-        from ddtrace import patch_all
+        from ddtrace._monkey import _patch_all
 
-        patch_all()
+        _patch_all()
         from psycopg2.extensions import quote_ident
 
         # NOTE: this will crash if it doesn't work.
@@ -497,9 +497,9 @@ def test_postgres_dbm_propagation_comment(self):
 
 @skipIf(PSYCOPG2_VERSION < (2, 7), "quote_ident not available in psycopg2<2.7")
 def test_manual_wrap_extension_quote_ident_standalone():
-    from ddtrace import patch_all
+    from ddtrace._monkey import _patch_all
 
-    patch_all()
+    _patch_all()
     from psycopg2.extensions import quote_ident
 
     # NOTE: this will crash if it doesn't work.

tests/contrib/psycopg2/test_psycopg_snapshot.py

@@ -54,7 +54,7 @@ def test_connect_traced_via_env(run_python_code_in_subprocess):
 import ddtrace
 from tests.contrib.config import POSTGRES_CONFIG
 
-ddtrace.patch_all()
+ddtrace._monkey._patch_all()
 
 conn = psycopg2.connect(**POSTGRES_CONFIG)
 assert conn

tests/contrib/starlette/test_starlette.py

@@ -499,17 +499,17 @@ def test_incorrect_patching(run_python_code_in_subprocess):
 from starlette.testclient import TestClient
 import sqlalchemy
 
-from ddtrace import patch_all
+from ddtrace._monkey import _patch_all
 
 
 from tests.contrib.starlette.app import get_app
 
 engine = sqlalchemy.create_engine("sqlite:///test.db")
 app = get_app(engine)
 
-# Calling patch_all late
+# Calling _patch_all late
 # DEV: The test client uses `requests` so we want to ignore them for this scenario
-patch_all(requests=False, http=False)
+_patch_all(requests=False, http=False)
 with TestClient(app) as test_client:
     r = test_client.get("/200")