DM-32142: Add logging.trace_set_at

doc/changes/DM-32142.feature.rst

@@ -0,0 +1 @@
+Add `lsst.logging.set_trace_at` to control TRACE loggers.

python/lsst/utils/logging.py

@@ -11,7 +11,7 @@
 
 from __future__ import annotations
 
-__all__ = ("TRACE", "VERBOSE", "getLogger", "LsstLogAdapter")
+__all__ = ("TRACE", "VERBOSE", "getLogger", "LsstLogAdapter", "trace_set_at")
 
 import logging
 from logging import LoggerAdapter
@@ -35,6 +35,40 @@
 logging.addLevelName(VERBOSE, "VERBOSE")
 
 
+def trace_set_at(name: str, number: int) -> None:
+    """Adjusts logging level to display messages with the trace number being
+    less than or equal to the provided value.
+
+    Parameters
+    ----------
+    name : `str`
+        Name of the logger.
+    number : `int`
+        The trace number threshold for display.
+
+    Notes
+    -----
+    Loggers ``TRACE0.`` to ``TRACE5.`` are set. All loggers above
+    the specified threshold are set to ``INFO`` and those below the threshold
+    are set to ``DEBUG``.  The expectation is that ``TRACE`` loggers only
+    issue ``DEBUG`` log messages.
+
+    Examples
+    --------
+
+    .. code-block:: python
+
+       lsst.utils.logging.trace_set_at("lsst.afw", 3)
+
+    This will set loggers ``TRACE0.lsst.afw`` to ``TRACE3.lsst.afw`` to
+    ``DEBUG`` and ``TRACE4.lsst.afw`` and ``TRACE5.lsst.afw`` to ``INFO``.
+    """
+    for i in range(6):
+        level = logging.INFO if i > number else logging.DEBUG
+        log_name = f"TRACE{i}.{name}" if name else f"TRACE{i}"
+        logging.getLogger(log_name).setLevel(level)
+
+
 class _F:
     """
     Format, supporting `str.format()` syntax.

tests/test_logging.py

@@ -15,7 +15,7 @@
 import logging
 import unittest
 
-from lsst.utils.logging import getLogger
+from lsst.utils.logging import getLogger, trace_set_at
 
 
 class TestLogging(unittest.TestCase):
@@ -65,6 +65,29 @@ def testLogCommands(self):
         child.setLevel(root.DEBUG)
         self.assertNotEqual(child.getEffectiveLevel(), root.getEffectiveLevel())
 
+    def testTraceSetAt(self):
+        log_name = "lsst.afw"
+        trace_set_at(log_name, 2)
+        trace2_log = getLogger(f"TRACE2.{log_name}")
+        trace3_log = getLogger(f"TRACE3.{log_name}")
+        self.assertEqual(trace2_log.getEffectiveLevel(), logging.DEBUG)
+        self.assertEqual(trace3_log.getEffectiveLevel(), logging.INFO)
+
+        # Check that child loggers are affected.
+        log_name = "lsst.daf"
+        child3_log = getLogger("TRACE3.lsst.daf")
+        child2_log = getLogger("TRACE2.lsst.daf")
+        self.assertEqual(child3_log.getEffectiveLevel(), logging.WARNING)
+        self.assertEqual(child2_log.getEffectiveLevel(), logging.WARNING)
+        trace_set_at("lsst", 2)
+        self.assertEqual(child3_log.getEffectiveLevel(), logging.INFO)
+        self.assertEqual(child2_log.getEffectiveLevel(), logging.DEBUG)
+
+        # Also check the root logger.
+        trace_set_at("", 3)
+        self.assertEqual(trace3_log.getEffectiveLevel(), logging.INFO)
+        self.assertEqual(getLogger("TRACE3.test").getEffectiveLevel(), logging.DEBUG)
+
 
 if __name__ == "__main__":
     unittest.main()