Skip to content

~95% on SimpleQA (e.g. Qwen3.6-27B on a 3090). Supports all local and cloud LLMs (llama.cpp, Ollama, Google, ...). 10+ search engines - arXiv, PubMed, your private documents. Everything Local & Encrypted.

5.1 KB
Raw Blame
"""Shared logging helpers for controlling exception detail.

``log_exception_type()`` logs a fixed action and exception class at ERROR
without exception text or tracebacks, including in diagnose mode.

Provider and search-engine exception handlers must stay observable at
ERROR level, but plain ``loguru.logger.exception()`` always attaches the
active exception to the record — every sink (stderr, database, frontend)
then renders or persists the traceback, including the ``__cause__`` /
``__context__`` chain, which has leaked Authorization headers and full
URLs embedded in wrapped exceptions (#4183).

:data:`logger` exported here is a :class:`SecureLogger` proxy around the
real loguru logger. Its ``.exception()`` is equivalent to::

    logger.opt(exception=is_diagnose_mode()).error(...)

so in normal operation the record carries *no* exception object — no sink
can render a traceback — while the event itself still lands at ERROR.
Developers opt into full tracebacks by setting **both** ``LDR_APP_DEBUG``
and ``LDR_LOGURU_DIAGNOSE`` to a truthy value ("1", "true", "yes").

Usage — a drop-in replacement for the loguru import::

    from ..security.secure_logging import logger

    try:
        ...
    except Exception as e:
        safe_msg = scrub_error(e)  # from ..security.log_sanitizer
        logger.exception(f"Engine request failed: {safe_msg}")

Caveats:

* **Messages are production-visible at ERROR.** The wrapper only strips
  the traceback; the message string itself reaches every sink. Call sites
  must still pass scrubbed text (``scrub_error`` — or in engine
  subclasses ``self._scrub_error``), never raw ``str(e)``.
* **Known bypass routes.** ``logger.opt(exception=True).error(...)`` and
  ``@logger.catch`` delegate to plain loguru and are NOT gated. No call
  site under ``llm/providers/``, ``embeddings/providers/`` or
  ``web_search_engines/`` uses them today; the #4183 step-2 pre-commit
  hook should detect them.
* **Env-gated only.** ``config_logger()`` in ``utilities/log_utils.py``
  gates its per-sink ``diagnose`` flag on its ``debug`` argument, which
  may come from the ``app.debug`` DB setting — this wrapper reads only
  the environment, so a DB-enabled debug mode does not enable wrapper
  tracebacks. See the cross-reference comment in ``config_logger``.
"""

import os

from loguru import logger as _loguru_logger


def log_exception_type(action: str, exc: Exception) -> None:
    """Log a fixed action and exception class without exception details.

    ``action`` must be developer-written text, with no request data or
    exception text interpolated into it. The exception is never stringified
    or attached to the record, even in diagnose mode. ``depth=1`` preserves
    the caller's location and module-based logging filters.
    """
    _loguru_logger.opt(exception=False, depth=1).error(
        "{action} ({error_type})",
        action=action,
        error_type=type(exc).__name__,
    )


def env_truthy(name: str) -> bool:
    """Return True if env var *name* is set to a truthy value ("1", "true", "yes")."""
    return os.environ.get(name, "").strip().lower() in ("1", "true", "yes")


def is_diagnose_mode() -> bool:
    """Return True when the operator explicitly opted into traceback output.

    Requires BOTH ``LDR_APP_DEBUG`` and ``LDR_LOGURU_DIAGNOSE`` to be
    truthy, mirroring the two-flag opt-in that ``config_logger()`` uses
    for loguru's frame-locals ``diagnose`` rendering.
    """
    return env_truthy("LDR_APP_DEBUG") and env_truthy("LDR_LOGURU_DIAGNOSE")


class SecureLogger:
    """Thin proxy over the loguru logger with a diagnose-gated ``exception()``.

    Everything except ``exception()``, ``bind()`` and ``patch()``
    delegates straight to loguru. Not a ``loguru._logger.Logger``
    subclass: its ``__init__`` takes ~10 positional private arguments
    that shift between releases, so a proxy is the version-stable shape.
    """

    __slots__ = ("_logger",)

    def __init__(self, wrapped=None):
        self._logger = wrapped if wrapped is not None else _loguru_logger

    def exception(__self, __message, *args, **kwargs):  # noqa: N805
        """Log at ERROR; attach the active exception only in diagnose mode.

        Positional-only ``__self`` / ``__message`` mirror loguru's own
        signature so ``str.format`` keyword fields (e.g. ``msg=``) cannot
        collide with parameter names. ``depth=1`` attributes the record
        to the caller's module/function/line, keeping
        ``logger.enable()`` / ``logger.disable()`` namespace semantics.
        """
        __self._logger.opt(exception=is_diagnose_mode(), depth=1).error(
            __message, *args, **kwargs
        )

    def bind(self, *args, **kwargs):
        """Like loguru's ``bind()`` but the result keeps the gated ``exception()``."""
        return SecureLogger(self._logger.bind(*args, **kwargs))

    def patch(self, *args, **kwargs):
        """Like loguru's ``patch()`` but the result keeps the gated ``exception()``."""
        return SecureLogger(self._logger.patch(*args, **kwargs))

    def __getattr__(self, name):
        return getattr(self._logger, name)


logger = SecureLogger()