feat: add 0.x upgrade guide for deprecations (#3338) (#3351)

(cherry picked from commit 70fcc7b)

Co-authored-by: Tahir H. Butt <[email protected]>

Author: mergify[bot]

ddtrace/__init__.py

@@ -1,5 +1,10 @@
+import os
+import warnings
+
 from ._monkey import patch  # noqa: E402
 from ._monkey import patch_all
+from .internal.utils.deprecations import DDTraceDeprecationWarning
+from .internal.utils.formats import asbool
 from .pin import Pin  # noqa: E402
 from .settings import _config as config  # noqa: E402
 from .span import Span  # noqa: E402
@@ -24,11 +29,15 @@
 ]
 
 
-@remove(removal_version="1.0.0")
+if asbool(os.getenv("DD_TRACE_RAISE_DEPRECATIONWARNING")):
+    warnings.filterwarnings(action="error", category=DDTraceDeprecationWarning)
+
+
+@remove(category=DDTraceDeprecationWarning, removal_version="1.0.0")
 def install_excepthook():
     """Install a hook that intercepts unhandled exception and send metrics about them."""
 
 
-@remove(removal_version="1.0.0")
+@remove(category=DDTraceDeprecationWarning, removal_version="1.0.0")
 def uninstall_excepthook():
     """Uninstall the global tracer except hook."""

ddtrace/_monkey.py

@@ -6,6 +6,7 @@
 from typing import Callable
 from typing import List
 
+from ddtrace.internal.utils.deprecation import DDTraceDeprecationWarning
 from ddtrace.vendor.wrapt.importer import when_imported
 
 from .internal.logger import get_logger
@@ -202,7 +203,7 @@ def patch(raise_errors=True, **patch_modules):
     )
 
 
-@remove(removal_version="1.0.0")
+@remove(category=DDTraceDeprecationWarning, removal_version="1.0.0")
 def patch_module(module, raise_errors=True):
     # type: (str, bool) -> bool
     return _patch_module(module, raise_errors=raise_errors)
@@ -227,7 +228,7 @@ def _patch_module(module, raise_errors=True):
         return False
 
 
-@remove(removal_version="1.0.0")
+@remove(category=DDTraceDeprecationWarning, removal_version="1.0.0")
 def get_patched_modules():
     # type: () -> List[str]
     return _get_patched_modules()

ddtrace/compat.py

@@ -1,3 +1,5 @@
+from ddtrace.internal.utils.deprecation import DDTraceDeprecationWarning
+
 from .internal.compat import CONTEXTVARS_IS_AVAILABLE
 from .internal.compat import NumericType
 from .internal.compat import PY2
@@ -74,5 +76,6 @@
 
 removed_module(
     module="ddtrace.compat",
+    category=DDTraceDeprecationWarning,
     removal_version="1.0.0",
 )

ddtrace/constants.py

@@ -1,4 +1,5 @@
 from ddtrace.internal.compat import ensure_pep562
+from ddtrace.internal.utils.deprecation import DDTraceDeprecationWarning
 from ddtrace.vendor import debtcollector
 
 
@@ -56,6 +57,7 @@ def __getattr__(name):
     if name in _DEPRECATED:
         debtcollector.deprecate(
             ("%s.%s is deprecated" % (__name__, name)),
+            category=DDTraceDeprecationWarning,
             removal_version="1.0.0",
         )
         return _DEPRECATED[name]

ddtrace/context.py

@@ -4,6 +4,8 @@
 from typing import TYPE_CHECKING
 from typing import Text
 
+from ddtrace.internal.utils.deprecation import DDTraceDeprecationWarning
+
 from .constants import ORIGIN_KEY
 from .constants import SAMPLING_PRIORITY_KEY
 from .internal.compat import NumericType
@@ -107,7 +109,11 @@ def dd_origin(self, value):
                 return
             self._meta[ORIGIN_KEY] = value
 
-    @remove(message="Cloning contexts will no longer be required in 0.50", removal_version="1.0.0")
+    @remove(
+        message="Cloning contexts will no longer be required in 0.50",
+        category=DDTraceDeprecationWarning,
+        removal_version="1.0.0",
+    )
     def clone(self):
         # type: () -> Context
         """

ddtrace/contrib/cassandra/session.py

@@ -6,6 +6,7 @@
 import cassandra.cluster
 
 from ddtrace import config
+from ddtrace.internal.utils.deprecations import DDTraceDeprecationWarning
 
 from ...constants import ANALYTICS_SAMPLE_RATE_KEY
 from ...constants import ERROR_MSG
@@ -278,7 +279,7 @@ def _sanitize_query(span, query):
 #
 # DEPRECATED
 #
-@remove(message="Use patching instead (see the docs).", removal_version="1.0.0")
+@remove(message="Use patching instead (see the docs).", category=DDTraceDeprecationWarning, removal_version="1.0.0")
 def get_traced_cassandra(*args, **kwargs):
     return _get_traced_cluster(*args, **kwargs)
 

ddtrace/contrib/celery/task.py

@@ -1,3 +1,5 @@
+from ddtrace.internal.utils.deprecations import DDTraceDeprecationWarning
+
 from ...vendor.debtcollector import deprecate
 from .app import patch_app
 
@@ -10,6 +12,7 @@ def patch_task(task, pin=None):
     deprecate(
         "ddtrace.contrib.celery.patch_task is deprecated",
         message="Use `patch(celery=True)` or `ddtrace-run` script instead",
+        category=DDTraceDeprecationWarning,
         removal_version="1.0.0",
     )
 
@@ -26,6 +29,7 @@ def unpatch_task(task):
     deprecate(
         "ddtrace.contrib.celery.patch_task is deprecated",
         message="Use `unpatch()` instead",
+        category=DDTraceDeprecationWarning,
         removal_version="1.0.0",
     )
     return task

ddtrace/contrib/flask/middleware.py

@@ -6,6 +6,7 @@
 from ddtrace import config
 from ddtrace.constants import ERROR_MSG
 from ddtrace.constants import ERROR_TYPE
+from ddtrace.internal.utils.deprecations import DDTraceDeprecationWarning
 
 from .. import trace_utils
 from ...ext import SpanTypes
@@ -28,7 +29,7 @@ def _normalize_resource(resource):
 
 
 class TraceMiddleware(object):
-    @remove(message="Use patching instead (see the docs).", removal_version="1.0.0")
+    @remove(message="Use patching instead (see the docs).", category=DDTraceDeprecationWarning, removal_version="1.0.0")
     def __init__(self, app, tracer, service="flask", use_signals=True, distributed_tracing=None):
         self.app = app
         log.debug("flask: initializing trace middleware")

ddtrace/contrib/mongoengine/patch.py

@@ -1,5 +1,7 @@
 import mongoengine
 
+from ddtrace.internal.utils.deprecations import DDTraceDeprecationWarning
+
 from ...vendor.debtcollector.removals import remove
 from .trace import WrappedConnect
 
@@ -16,6 +18,6 @@ def unpatch():
     setattr(mongoengine, "connect", _connect)
 
 
-@remove(message="Use patching instead (see the docs).", removal_version="1.0.0")
+@remove(message="Use patching instead (see the docs).", category=DDTraceDeprecationWarning, removal_version="1.0.0")
 def trace_mongoengine(*args, **kwargs):
     return _connect

ddtrace/contrib/mysql/tracers.py

@@ -1,8 +1,10 @@
 import mysql.connector
 
+from ddtrace.internal.utils.deprecations import DDTraceDeprecationWarning
+
 from ...vendor.debtcollector.removals import remove
 
 
-@remove(message="Use patching instead (see the docs).", removal_version="1.0.0")
+@remove(message="Use patching instead (see the docs).", category=DDTraceDeprecationWarning, removal_version="1.0.0")
 def get_traced_mysql_connection(*args, **kwargs):
     return mysql.connector.MySQLConnection