Add debug recorder and reporting utilities

Introduce a new debug subsystem under deeplabcut/core/debug. Adds an in-memory, bounded log recorder (InMemoryDebugRecorder) with safe fail-open semantics, helper functions to install/get the recorder, and a scoped log_timing context manager. Provides utilities to collect runtime, package, and external executable information (LibrarySpec, ExecutableSpec, collect_version_summary, collect_executable_summary, collect_debug_sections) and to format/assemble a full debug report (format_debug_report, build_debug_report). Includes small helper functions (_which, _command_version) and sane defaults (lists of core/GUI/TensorFlow libs, ffmpeg executable). Exports are wired in __init__.py.
DeepLabCut · C-Achard · May 12, 2026 · May 12, 2026 · May 12, 2026 · May 12, 2026
commit 1676f0d118111ce4117a62816ce94599fa9f4c10
diff --git a/deeplabcut/core/debug/__init__.py b/deeplabcut/core/debug/__init__.py
@@ -0,0 +1,37 @@
+from collections.abc import Sequence
+
+from .debug_logger import (
+    DLC_ALL_LIBS_SPECS,
+    DLC_LOG_TIMING,
+    LOG_QUEUE_MAXLEN,
+    ExecutableSpec,
+    InMemoryDebugRecorder,
+    LibrarySpec,
+    RecordedLog,
+    build_debug_report,
+    collect_debug_sections,
+    collect_executable_summary,
+    collect_version_summary,
+    format_debug_report,
+    get_debug_recorder,
+    install_debug_recorder,
+    log_timing,
+)
+
+__all__: Sequence[str] = (
+    "DLC_LOG_TIMING",
+    "DLC_ALL_LIBS_SPECS",
+    "InMemoryDebugRecorder",
+    "LibrarySpec",
+    "ExecutableSpec",
+    "LOG_QUEUE_MAXLEN",
+    "RecordedLog",
+    "build_debug_report",
+    "collect_debug_sections",
+    "collect_version_summary",
+    "format_debug_report",
+    "get_debug_recorder",
+    "install_debug_recorder",
+    "log_timing",
+    "collect_executable_summary",
+)
diff --git a/deeplabcut/core/debug/_debug_utils.py b/deeplabcut/core/debug/_debug_utils.py
@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+import shutil
+import subprocess
+from collections.abc import Sequence
+from pathlib import Path
+
+
+def _which(command: str) -> str:
+    try:
+        resolved = shutil.which(command)
+        return str(Path(resolved).resolve()) if resolved else "not-found"
+    except Exception:
+        return "not-found"
+
+
+def _command_version(command: str, version_args: Sequence[str] = ("-version",)) -> str:
+    try:
+        completed = subprocess.run(
+            [command, *version_args],
+            check=False,
+            capture_output=True,
+            text=True,
+            timeout=3,
+        )
+    except Exception:
+        return "unavailable"
+
+    text = (completed.stdout or completed.stderr or "").strip()
+    if not text:
+        return "unavailable"
+
+    first_line = text.splitlines()[0].strip()
+    return first_line or "unavailable"