debug: --debug=core for showing why the core was chosen

Author: nedbat

CHANGES.rst

@@ -41,6 +41,8 @@ Unreleased
   slight performance improvement, but I couldn't reproduce the performance
   gain, so it's been reverted, fixing the debugger problem.
 
+- A new debug option ``--debug=core`` shows which core is in use and why.
+
 - Split ``sqlite`` debugging information out of the ``sys`` :ref:`coverage
   debug <cmd_debug>` and :ref:`cmd_run_debug` options since it's bulky and not
   very useful.

coverage/control.py

@@ -585,6 +585,7 @@ def _init_for_start(self) -> None:
 
         self._core = Core(
             warn=self._warn,
+            debug=(self._debug if self._debug.should("core") else None),
             config=self.config,
             dynamic_contexts=(should_start_context is not None),
             metacov=self._metacov,

coverage/core.py

@@ -16,7 +16,7 @@
 from coverage.misc import isolate_module
 from coverage.pytracer import PyTracer
 from coverage.sysmon import SysMonitor
-from coverage.types import TFileDisposition, Tracer, TWarnFn
+from coverage.types import TDebugCtl, TFileDisposition, Tracer, TWarnFn
 
 os = isolate_module(os)
 
@@ -56,11 +56,19 @@ class Core:
 
     def __init__(
         self,
+        *,
         warn: TWarnFn,
+        debug: TDebugCtl | None,
         config: CoverageConfig,
         dynamic_contexts: bool,
         metacov: bool,
     ) -> None:
+        def _debug(msg: str) -> None:
+            if debug:
+                debug.write(msg)
+
+        _debug("in core.py")
+
         # Check the conditions that preclude us from using sys.monitoring.
         reason_no_sysmon = ""
         if not env.PYBEHAVIOR.pep669:
@@ -75,26 +83,34 @@ def __init__(
         core_name: str | None = None
         if config.timid:
             core_name = "pytrace"
+            _debug("core.py: Using pytrace because timid=True")
         elif core_name is None:
             # This could still leave core_name as None.
             core_name = config.core
+            _debug(f"core.py: core from config is {core_name!r}")
 
         if core_name == "sysmon" and reason_no_sysmon:
+            _debug(f"core.py: raising ConfigError because sysmon not usable: {reason_no_sysmon}")
             raise ConfigError(
                 f"Can't use core=sysmon: sys.monitoring {reason_no_sysmon}", skip_tests=True
             )
 
         if core_name is None:
             if env.SYSMON_DEFAULT and not reason_no_sysmon:
                 core_name = "sysmon"
+                _debug("core.py: Using sysmon because SYSMON_DEFAULT is set")
             else:
                 core_name = "ctrace"
+                _debug("core.py: Defaulting to ctrace core")
 
         if core_name == "ctrace":
             if not CTRACER_FILE:
                 if IMPORT_ERROR and env.SHIPPING_WHEELS:
                     warn(f"Couldn't import C tracer: {IMPORT_ERROR}", slug="no-ctracer", once=True)
                 core_name = "pytrace"
+                _debug("core.py: Falling back to pytrace because C tracer not available")
+
+        _debug(f"core.py: Using core={core_name}")
 
         self.tracer_kwargs = {}
 

doc/commands/cmd_debug.rst

@@ -68,6 +68,8 @@ of activity to log:
 * ``config``: before starting, dump all the :ref:`configuration <config>`
   values.
 
+* ``core``: log decision about choosing the measurement core to use.
+
 * ``dataio``: log when reading or writing any data file.
 
 * ``dataop``: log a summary of data being added to CoverageData objects.