chore(internal): avoid freezegun in ddtrace (DataDog#11406)

`freezegun` (and `pytest-freezegun`) may cause wrong durations to be
reported when used, so we add an integration that automatically enforces
that `ddtrace` be an ignored module by:
- calling `freezegun.configure()` with `extend_ignore_list` to add
`ddtrace`
- wrapping `freezegun.configure()` so that any attempt to reset the
`default_ignore_list` includes `ddtrace`

Additionally, since `pytest` does not patch all integrations by default,
and because we don't want to force users to use `--ddtrace-patch-all`
for `freezegun` to be patched, we update our `pytest` plugin(s) to patch
`freezegun` during the `pytest_load_initial_conftests` hook (which
should be early enough).

This is not considered a fix as there are no active issues reported and
this (so far) primarily affects telemetry recorded by the CI Visibility
service.

## 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)

Author: romainkomorn-exdatadog

.github/CODEOWNERS

@@ -77,6 +77,10 @@ tests/coverage                                        @DataDog/apm-core-python @
 tests/tracer/test_ci.py                               @DataDog/ci-app-libraries
 ddtrace/ext/git.py                                    @DataDog/ci-app-libraries @DataDog/apm-core-python
 scripts/ci_visibility/*                               @DataDog/ci-app-libraries
+# Test Visibility owns the freezegun integration because it's the team most affected by it
+ddtrace/contrib/freezegun                             @DataDog/ci-app-libraries
+ddtrace/contrib/internal/freezegun                    @DataDog/ci-app-libraries
+tests/contrib/freezegun                               @DataDog/ci-app-libraries
 
 # Debugger
 ddtrace/debugging/                  @DataDog/debugger-python

ddtrace/_monkey.py

@@ -41,6 +41,7 @@
     "elasticsearch": True,
     "algoliasearch": True,
     "futures": True,
+    "freezegun": True,
     "google_generativeai": True,
     "gevent": True,
     "graphql": True,

ddtrace/contrib/freezegun/__init__.py

@@ -0,0 +1,28 @@
+"""
+The freezegun integration reconfigures freezegun's default ignore list to ignore ddtrace.
+
+Enabling
+~~~~~~~~
+The freezegun integration is enabled by default. Use :func:`patch()<ddtrace.patch>` to enable the integration::
+    from ddtrace import patch
+    patch(freezegun=True)
+
+
+Configuration
+~~~~~~~~~~~~~
+The freezegun integration is not configurable, but may be disabled using DD_PATCH_MODULES=freezegun:false .
+"""
+
+from ...internal.utils.importlib import require_modules
+
+
+required_modules = ["freezegun"]
+
+with require_modules(required_modules) as missing_modules:
+    if not missing_modules:
+        # Expose public methods
+        from ..internal.freezegun.patch import get_version
+        from ..internal.freezegun.patch import patch
+        from ..internal.freezegun.patch import unpatch
+
+        __all__ = ["get_version", "patch", "unpatch"]

ddtrace/contrib/internal/freezegun/patch.py

@@ -0,0 +1,68 @@
+from ddtrace.internal.logger import get_logger
+from ddtrace.internal.wrapping.context import WrappingContext
+
+
+log = get_logger(__name__)
+
+DDTRACE_MODULE_NAME = "ddtrace"
+
+
+class FreezegunConfigWrappingContext(WrappingContext):
+    """Wraps the call to freezegun.configure to ensure that ddtrace remains patched if default_ignore_list is passed
+    in as an argument
+    """
+
+    # __exit__ comes from the parent class
+    # no-dd-sa:python-best-practices/ctx-manager-enter-exit-defined
+    def __enter__(self) -> "FreezegunConfigWrappingContext":
+        super().__enter__()
+        try:
+            default_ignore_list = self.get_local("default_ignore_list")
+        except KeyError:
+            log.debug("Could not get default_ignore_list on call to configure()")
+            return
+
+        if default_ignore_list is not None and DDTRACE_MODULE_NAME not in default_ignore_list:
+            default_ignore_list.append(DDTRACE_MODULE_NAME)
+
+        return self
+
+
+def get_version() -> str:
+    import freezegun
+
+    try:
+        return freezegun.__version__
+    except AttributeError:
+        log.debug("Could not get freezegun version")
+        return ""
+
+
+def patch() -> None:
+    import freezegun
+
+    if getattr(freezegun, "_datadog_patch", False):
+        return
+
+    FreezegunConfigWrappingContext(freezegun.configure).wrap()
+
+    freezegun.configure(extend_ignore_list=[DDTRACE_MODULE_NAME])
+
+    freezegun._datadog_patch = True
+
+
+def unpatch() -> None:
+    import freezegun
+
+    if not getattr(freezegun, "_datadog_patch", False):
+        return
+
+    if FreezegunConfigWrappingContext.is_wrapped(freezegun.configure):
+        FreezegunConfigWrappingContext.extract(freezegun.configure).unwrap()
+
+    # Note: we do not want to restore to the original ignore list, as it may have been modified by the user, but we do
+    # want to remove the ddtrace module from the ignore list
+    new_ignore_list = [m for m in freezegun.config.settings.default_ignore_list if m != DDTRACE_MODULE_NAME]
+    freezegun.configure(default_ignore_list=new_ignore_list)
+
+    freezegun._datadog_patch = False

ddtrace/contrib/pytest/_plugin_v1.py

@@ -423,6 +423,9 @@ def pytest_load_initial_conftests(early_config, parser, args):
 
         log = get_logger(__name__)
 
+        # Freezegun is proactively patched to avoid it interfering with internal timing
+        ddtrace.patch(freezegun=True)
+
         COVER_SESSION = asbool(os.environ.get("_DD_COVER_SESSION", "false"))
 
         if USE_DD_COVERAGE:

ddtrace/contrib/pytest/_plugin_v2.py

@@ -6,6 +6,7 @@
 
 from ddtrace import DDTraceDeprecationWarning
 from ddtrace import config as dd_config
+from ddtrace import patch
 from ddtrace.contrib.coverage import patch as patch_coverage
 from ddtrace.contrib.internal.coverage.constants import PCT_COVERED_KEY
 from ddtrace.contrib.internal.coverage.data import _coverage_data
@@ -163,6 +164,8 @@ def pytest_load_initial_conftests(early_config, parser, args):
     try:
         take_over_logger_stream_handler()
         log.warning("This version of the ddtrace pytest plugin is currently in beta.")
+        # Freezegun is proactively patched to avoid it interfering with internal timing
+        patch(freezegun=True)
         dd_config.test_visibility.itr_skipping_level = ITR_SKIPPING_LEVEL.SUITE
         enable_test_visibility(config=dd_config.pytest)
         if InternalTestSession.should_collect_coverage():

hatch.toml

@@ -450,3 +450,24 @@ dependencies = [
 view = [
     "python scripts/ci_visibility/view_snapshot.py {args:}",
 ]
+
+[envs.freezegun]
+template = "freezegun"
+dependencies = [
+    "freezegun{matrix:freezegun}",
+    "pytest",
+    "pytest-cov",
+    "hypothesis",
+]
+
+[envs.freezegun.env-vars]
+DD_PYTEST_USE_NEW_PLUGIN_BETA = "true"
+
+[envs.freezegun.scripts]
+test = [
+    "pytest tests/contrib/freezegun {args:}",
+]
+
+[[envs.freezegun.matrix]]
+python = ["3.7", "3.10", "3.12"]
+freezegun = ["~=1.3.0", "~=1.5.0"]

tests/contrib/freezegun/test_freezegun.py

@@ -0,0 +1,107 @@
+import datetime
+import os
+import time
+
+import pytest
+
+from ddtrace import tracer as dd_tracer
+from ddtrace.internal.utils.time import StopWatch
+from tests.contrib.pytest.test_pytest import PytestTestCaseBase
+
+
+class TestFreezegunTestCase:
+    @pytest.fixture(autouse=True)
+    def _patch_freezegun(self):
+        from ddtrace.contrib.freezegun import patch
+        from ddtrace.contrib.freezegun import unpatch
+
+        patch()
+        yield
+        unpatch()
+
+    def test_freezegun_unpatch(self):
+        import freezegun
+
+        from ddtrace.contrib.freezegun import unpatch
+
+        unpatch()
+
+        with freezegun.freeze_time("2020-01-01"):
+            with dd_tracer.trace("freezegun.test") as span:
+                time.sleep(1)
+
+        assert span.duration == 0
+
+    def test_freezegun_does_not_freeze_tracing(self):
+        import freezegun
+
+        with freezegun.freeze_time("2020-01-01"):
+            with dd_tracer.trace("freezegun.test") as span:
+                time.sleep(1)
+
+        assert span.duration >= 1
+
+    def test_freezegun_fast_forward_does_not_affect_tracing(self):
+        import freezegun
+
+        with freezegun.freeze_time("2020-01-01") as frozen_time:
+            with dd_tracer.trace("freezegun.test") as span:
+                time.sleep(1)
+                frozen_time.tick(delta=datetime.timedelta(days=10))
+        assert 1 <= span.duration <= 5
+
+    def test_freezegun_does_not_freeze_stopwatch(self):
+        import freezegun
+
+        with freezegun.freeze_time("2020-01-01"):
+            with StopWatch() as sw:
+                time.sleep(1)
+            assert sw.elapsed() >= 1
+
+    def test_freezegun_configure_default_ignore_list_continues_to_ignore_ddtrace(self):
+        import freezegun
+
+        freezegun.configure(default_ignore_list=[])
+
+        with freezegun.freeze_time("2020-01-01"):
+            with dd_tracer.trace("freezegun.test") as span:
+                time.sleep(1)
+
+        assert span.duration >= 1
+
+
+class PytestFreezegunTestCase(PytestTestCaseBase):
+    def test_freezegun_pytest_plugin(self):
+        """Tests that pytest's patching of freezegun in the v1 plugin version works"""
+        import sys
+
+        from ddtrace.contrib.freezegun import unpatch
+
+        unpatch()
+        if "freezegun" in sys.modules:
+            del sys.modules["freezegun"]
+
+        py_file = self.testdir.makepyfile(
+            """
+            import datetime
+            import time
+
+            import freezegun
+
+            from ddtrace import tracer as dd_tracer
+
+            def test_pytest_patched_freezegun():
+                with freezegun.freeze_time("2020-01-01"):
+                    with dd_tracer.trace("freezegun.test") as span:
+                        time.sleep(1)
+                assert span.duration >= 1
+
+        """
+        )
+        file_name = os.path.basename(py_file.strpath)
+        self.inline_run("--ddtrace", "-s", file_name)
+        spans = self.pop_spans()
+
+        assert len(spans) == 4
+        for span in spans:
+            assert span.get_tag("test.status") == "pass"

tests/contrib/suitespec.yml

@@ -97,6 +97,9 @@ components:
     - ddtrace/contrib/flask_cache/*
     - ddtrace/contrib/internal/flask_cache/*
     - ddtrace/contrib/flask_login/*
+  freezegun:
+    - ddtrace/contrib/freezegun/*
+    - ddtrace/contrib/internal/freezegun/*
   futures:
     - ddtrace/contrib/futures/*
     - ddtrace/contrib/internal/futures/*
@@ -609,6 +612,16 @@ suites:
       - memcached
       - redis
     snapshot: true
+  freezegun:
+    paths:
+        - '@bootstrap'
+        - '@core'
+        - '@contrib'
+        - '@tracing'
+        - '@freezegun'
+        - tests/contrib/freezegun/*
+    runner: hatch
+    snapshot: true
   gevent:
     paths:
       - '@bootstrap'