From c0076538f4d4b761076f1abdf143072ca5e5059c Mon Sep 17 00:00:00 2001
From: Munir Abdinur <munir.abdinur@datadoghq.com>
Date: Mon, 17 Nov 2025 12:10:00 -0500
Subject: [PATCH] chore(tornado): v4.0 deprecations (#15274)

Deprecated Tornado versions older than v6.1 and programmatic
configuration via ddtrace.contrib.tornado. Users should upgrade to
Tornado v6.1+ and use environment variables with import ddtrace.auto.

Tornado v6.1 (released in 2020) added contextvars support, eliminating
the need for a custom Tornado Context Provider. This allows us to remove
the last integration specific Context Provider and simplify our context
API.

---------

Co-authored-by: Brett Langdon <brett.langdon@datadoghq.com>
(cherry picked from commit 75a19c26b480e286fdec956a38aa277364bd844c)
---
 ddtrace/contrib/internal/tornado/patch.py        | 16 +++++++++++++++-
 ddtrace/contrib/tornado.py                       |  9 +++++++++
 ...-older-tornado-versions-381d2f4e6c4c8288.yaml |  4 ++++
 ...ornado-programmatic-api-5f7a8b9c1d2e3f4a.yaml |  4 ++++
 4 files changed, 32 insertions(+), 1 deletion(-)
 create mode 100644 releasenotes/notes/deprecate-older-tornado-versions-381d2f4e6c4c8288.yaml
 create mode 100644 releasenotes/notes/deprecate-tornado-programmatic-api-5f7a8b9c1d2e3f4a.yaml

diff --git a/ddtrace/contrib/internal/tornado/patch.py b/ddtrace/contrib/internal/tornado/patch.py
index 86daad24135..bc7fc387ec6 100644
--- a/ddtrace/contrib/internal/tornado/patch.py
+++ b/ddtrace/contrib/internal/tornado/patch.py
@@ -7,8 +7,10 @@
 import ddtrace
 from ddtrace import config
 from ddtrace.contrib.internal.tornado.stack_context import context_provider
+from ddtrace.internal.utils.deprecations import DDTraceDeprecationWarning
 from ddtrace.internal.utils.formats import asbool
 from ddtrace.internal.utils.wrappers import unwrap as _u
+from ddtrace.vendor.debtcollector import deprecate
 
 from . import application
 from . import decorators
@@ -26,7 +28,19 @@
 
 def get_version():
     # type: () -> str
-    return getattr(tornado, "version", "")
+    return getattr(tornado, "version", "0.0.0")
+
+
+VERSION_TUPLE = tuple([int(x) for x in get_version().split(".")])
+
+if VERSION_TUPLE < (6, 1, 0):
+    deprecate(
+        f"Tornado {VERSION_TUPLE} is deprecated",
+        message="Use Tornado v6.1 or later and configure tracing using "
+        "environment variables and ``ddtrace-run`` or ``import ddtrace.auto`` instead.",
+        category=DDTraceDeprecationWarning,
+        removal_version="4.0.0",
+    )
 
 
 def _supported_versions() -> Dict[str, str]:
diff --git a/ddtrace/contrib/tornado.py b/ddtrace/contrib/tornado.py
index dc231fce60d..f460d350886 100644
--- a/ddtrace/contrib/tornado.py
+++ b/ddtrace/contrib/tornado.py
@@ -100,8 +100,17 @@ def log_exception(self, typ, value, tb):
 from ddtrace.contrib.internal.tornado.stack_context import TracerStackContext
 from ddtrace.contrib.internal.tornado.stack_context import context_provider
 from ddtrace.contrib.internal.tornado.stack_context import run_with_trace_context
+from ddtrace.internal.utils.deprecations import DDTraceDeprecationWarning
+from ddtrace.vendor.debtcollector import deprecate
 
 
+deprecate(
+    "ddtrace.contrib.tornado is deprecated",
+    message="Use ``import ddtrace.auto`` and ``DD_PATCH_MODULES`` to configure tracing for Tornado.",
+    category=DDTraceDeprecationWarning,
+    removal_version="4.0.0",
+)
+
 __all__ = [
     "context_provider",
     "run_with_trace_context",
diff --git a/releasenotes/notes/deprecate-older-tornado-versions-381d2f4e6c4c8288.yaml b/releasenotes/notes/deprecate-older-tornado-versions-381d2f4e6c4c8288.yaml
new file mode 100644
index 00000000000..36ca9c79925
--- /dev/null
+++ b/releasenotes/notes/deprecate-older-tornado-versions-381d2f4e6c4c8288.yaml
@@ -0,0 +1,4 @@
+---
+deprecations:
+  - |
+    tornado: Deprecated support for Tornado versions older than v6.1. Use Tornado v6.1 or later.
diff --git a/releasenotes/notes/deprecate-tornado-programmatic-api-5f7a8b9c1d2e3f4a.yaml b/releasenotes/notes/deprecate-tornado-programmatic-api-5f7a8b9c1d2e3f4a.yaml
new file mode 100644
index 00000000000..c320664614a
--- /dev/null
+++ b/releasenotes/notes/deprecate-tornado-programmatic-api-5f7a8b9c1d2e3f4a.yaml
@@ -0,0 +1,4 @@
+---
+deprecations:
+  - |
+    tornado: Deprecates programmatic tracing configuration via the ``ddtrace.contrib.tornado`` module. Configure tracing using environment variables and ``import ddtrace.auto`` instead.