logging_handler.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# oc_diagnostics/logging_handler.py
 
"""
Python logging Handler
======================
 
Purpose
-------
Bridge the Python standard-library ``logging`` module into ``oc_diagnostics``
so that libraries and frameworks that emit log records via ``logging.getLogger``
are automatically captured and displayed through the unified diagnostics system.
 
Responsibilities
----------------
- Provide ``OcDiagnosticsHandler``, a ``logging.Handler`` subclass that
  converts each ``LogRecord`` to an ``oc_diagnostics._dbg()`` call.
- Map Python logging levels to oc_diagnostics diagnostic levels via a
  configurable ``level_map`` dict.
- Use a sensible default mapping:
    DEBUG    → L4 (deep tracing)
    INFO     → L2 (lifecycle)
    WARNING  → L1 (errors only)
    ERROR    → L1
    CRITICAL → L1
 
Diagnostics
-----------
Domain: configurable (default: "GENERAL")
Levels: determined by level_map at runtime
 
Contracts
---------
- Must not raise; errors are delegated to ``logging.Handler.handleError()``.
- Requires no optional dependencies (pure Python, always available).
- The ``domain`` and ``level_map`` are settable at construction time.
"""
 
import logging
 
from oc_diagnostics.unified_debug import _dbg
 
 
# Default mapping from Python logging level ints to oc_diagnostics levels
_DEFAULT_LEVEL_MAP: dict[int, int] = {
    logging.DEBUG:    4,
    logging.INFO:     2,
    logging.WARNING:  1,
    logging.ERROR:    1,
    logging.CRITICAL: 1,
}
 
 
class OcDiagnosticsHandler(logging.Handler):
    """A ``logging.Handler`` that routes records through ``oc_diagnostics._dbg()``.
 
    Parameters
    ----------
    domain : str
        The oc_diagnostics domain used for all records routed through this
        handler.  Default ``"GENERAL"``.
    level_map : dict[int, int] | None
        Mapping from Python ``logging`` level integers to oc_diagnostics
        diagnostic level integers.  When ``None``, the built-in default is
        used: DEBUG→4, INFO→2, WARNING/ERROR/CRITICAL→1.
 
    Example
    -------
    ::
 
        import logging
        from oc_diagnostics import OcDiagnosticsHandler
 
        handler = OcDiagnosticsHandler(domain="DATA")
        logging.getLogger("sqlalchemy").addHandler(handler)
    """
 
    def __init__(
        self,
        domain: str = "GENERAL",
        level_map: dict[int, int] | None = None,
    ) -> None:
        super().__init__()
        self.domain = domain
        self._level_map: dict[int, int] = (
            level_map if level_map is not None else _DEFAULT_LEVEL_MAP
        )
 
    def emit(self, record: logging.LogRecord) -> None:
        try:
            diag_level = self._level_map.get(record.levelno, 2)
            msg = self.format(record)
            _dbg(
                self.domain,
                record.funcName or "",
                msg,
                level=diag_level,
                _depth=2,
            )
        except Exception:
            self.handleError(record)