Function install_debug_recorder

deeplabcut/core/debug/debug_logger.py:205–253

Attach a single in-memory recorder to the requested logger namespace. Idempotent: repeated calls return the same recorder. Parameters ---------- logger_name: Logger namespace to attach the recorder to. capacity: Maximum number of captured records. By default, us

(
    *,
    logger_name: str = "deeplabcut",
    capacity: int = LOG_QUEUE_MAXLEN,
    handler_level: int = logging.INFO,
    ensure_logger_level: int | None = None,
)

def install_debug_recorder(
    *,
    logger_name: str = "deeplabcut",
    capacity: int = LOG_QUEUE_MAXLEN,
    handler_level: int = logging.INFO,
    ensure_logger_level: int | None = None,
) -> InMemoryDebugRecorder:
    """Attach a single in-memory recorder to the requested logger namespace.

    Idempotent: repeated calls return the same recorder.

    Parameters
    ----------
    logger_name:
        Logger namespace to attach the recorder to.
    capacity:
        Maximum number of captured records. By default, uses LOG_QUEUE_MAXLEN.
    handler_level:
        Minimum level stored by the recorder itself.
    ensure_logger_level:
        Controls whether to adjust the target logger level.

        - None: never modify the logger level
        - int: lower the logger only if its effective level is more restrictive
    """

    root_logger = logging.getLogger(logger_name)

    existing = getattr(root_logger, _DEBUG_HANDLER_ATTR, None)
    if isinstance(existing, InMemoryDebugRecorder):
        return existing

    recorder = InMemoryDebugRecorder(capacity=capacity, level=handler_level)
    recorder.set_name("deeplabcut-debug-recorder")

    # Important:
    # - attach only to a DLC-owned logger namespace, not the global root logger
    # - keep propagation unchanged
    # - logger level adjustment, if any, is handled below; "auto" initializes
    #   an unset logger to ``handler_level`` rather than forcing DEBUG
    root_logger.addHandler(recorder)

    if isinstance(ensure_logger_level, int):
        # Only lower verbosity if explicitly requested.
        if root_logger.getEffectiveLevel() > ensure_logger_level:
            root_logger.setLevel(ensure_logger_level)

    setattr(root_logger, _DEBUG_HANDLER_ATTR, recorder)
    return recorder


def get_debug_recorder(*, logger_name: str = "deeplabcut") -> InMemoryDebugRecorder | None: