evaluation/utils/logger.py

"""Centralised logging initialisation (console + rotating file)."""

from __future__ import annotations
import logging
import logging.handlers
import os
import sys
from datetime import datetime
from pathlib import Path
from typing import Optional

__all__ = ["init_logging"]


def init_logging(
    *,
    log_dir: str | os.PathLike = "logs",
    level: str | int = "INFO",
    fmt: str = "%(asctime)s | %(levelname)s | %(name)s | %(message)s",
    max_mb: int = 5,
    backups: int = 5,
) -> Path:
    """Configure root logger for both console *and* rotating-file output.

    Returns
    -------
    Path to the log file.
    """
    log_dir = Path(log_dir)
    log_dir.mkdir(parents=True, exist_ok=True)
    logfile = log_dir / f"{datetime.now(datetime.timezone.utc):%Y%m%d_%H%M%S}.log"

    if isinstance(level, str):
        level = logging._nameToLevel.get(level.upper(), logging.INFO)
    formatter = logging.Formatter(fmt)

    root = logging.getLogger()
    root.setLevel(level)
    root.handlers.clear()           # avoid duplicate handlers on re-init

    # Console
    ch = logging.StreamHandler(sys.stderr)
    ch.setLevel(level)
    ch.setFormatter(formatter)
    root.addHandler(ch)

    # Rotating file
    fh = logging.handlers.RotatingFileHandler(
        logfile, maxBytes=max_mb * 1024 * 1024, backupCount=backups
    )
    fh.setLevel(level)
    fh.setFormatter(formatter)
    root.addHandler(fh)

    root.info("Logging initialised. File=%s  Level=%s", logfile, logging.getLevelName(level))
    return logfile