Function configure_logging

config/logging_config.py:107–159

Configure loguru with JSON output to log_file and intercept stdlib logging. Idempotent: skips if already configured (e.g. hot reload). Use force=True to reconfigure (e.g. in tests with a different log path). When ``verbose_third_party`` is false, noisy HTTP and Telegram loggers are cap

(
    log_file: str | Path, *, force: bool = False, verbose_third_party: bool = False
)

def configure_logging(
    log_file: str | Path, *, force: bool = False, verbose_third_party: bool = False
) -> None:
    """Configure loguru with JSON output to log_file and intercept stdlib logging.

    Idempotent: skips if already configured (e.g. hot reload).
    Use force=True to reconfigure (e.g. in tests with a different log path).

    When ``verbose_third_party`` is false, noisy HTTP and Telegram loggers are capped
    at WARNING unless explicitly configured otherwise.
    """
    global _configured
    if _configured and not force:
        return
    _configured = True

    # Remove default loguru handler (writes to stderr)
    logger.remove()

    log_path = Path(log_file)
    log_path.parent.mkdir(parents=True, exist_ok=True)

    # Truncate log file on fresh start for clean debugging
    log_path.write_text("")

    # Add file sink: JSON lines, DEBUG level, context vars at top level
    logger.add(
        log_file,
        level="DEBUG",
        format=_serialize_with_context,
        encoding="utf-8",
        mode="a",
        rotation="50 MB",
        enqueue=True,
    )

    # Intercept stdlib logging: route all root logger output to loguru
    intercept = InterceptHandler()
    logging.root.handlers = [intercept]
    logging.root.setLevel(logging.DEBUG)

    third_party = (
        "httpx",
        "httpcore",
        "httpcore.http11",
        "httpcore.connection",
        "telegram",
        "telegram.ext",
    )
    for name in third_party:
        logging.getLogger(name).setLevel(
            logging.WARNING if not verbose_third_party else logging.NOTSET
        )