jmri_core.log

  1"""``jmri_core.log`` — logging bootstrap for headless installs.
  2
  3Every entry point (jmri-server's uvicorn app, WiThrottle server,
  4scripts) calls :func:`configure` once at startup. Configuration is
  5driven by the env vars in :mod:`jmri_core.env`:
  6
  7* ``JMRI_LOG_LEVEL`` — root threshold (default ``INFO``).
  8* ``JMRI_LOG_FILE`` — path to a rotating log file. If unset, logs go
  9  to the console only, matching pre-Tier-2 behaviour so unattended
 10  installs don't grow files without an operator opting in.
 11* ``JMRI_LOG_MAX_MB`` — rotation size in MiB (default 5).
 12* ``JMRI_LOG_BACKUPS`` — number of rotated files to keep (default 3).
 13
 14The unified format is:
 15
 16    2026-08-04 15:03:07,412 INFO  [jmri_nce.connection] NCE ready
 17
 18Timestamps use the local timezone (matches JMRI Java). Level column is
 195-wide so ``INFO`` / ``WARN`` / ``ERROR`` align. Logger name goes in
 20brackets so grep on ``[jmri_nce`` picks up every NCE line regardless
 21of the sub-module.
 22
 23:func:`configure` is idempotent — a repeat call replaces the handlers
 24so tests can reconfigure without leaking handlers across the process.
 25"""
 26from __future__ import annotations
 27
 28import logging
 29import logging.handlers
 30import pathlib
 31import sys
 32
 33from jmri_core import env
 34
 35# Column widths chosen so INFO / WARN / DEBUG all align and the logger
 36# name doesn't wander. Longer logger names wrap inside the brackets.
 37_FORMAT = "%(asctime)s %(levelname)-5s [%(name)s] %(message)s"
 38_DATEFMT = "%Y-%m-%d %H:%M:%S"
 39
 40# Tracked handlers we've installed. Kept so a re-configure removes
 41# them cleanly instead of adding on top (which would double every log
 42# line and eventually thrash file descriptors in tests).
 43_installed: list[logging.Handler] = []
 44
 45
 46def configure(
 47    *,
 48    level: str | None = None,
 49    log_file: pathlib.Path | str | None = None,
 50    max_mb: int | None = None,
 51    backups: int | None = None,
 52    console: bool = True,
 53) -> pathlib.Path | None:
 54    """Install root-logger handlers.
 55
 56    Parameters mirror the :mod:`jmri_core.env` getters. Passing an
 57    explicit value overrides the env; passing ``None`` reads the env.
 58
 59    Returns the resolved log-file path (or ``None`` if no file handler
 60    was installed). Callers who want to advertise the log location on a
 61    status page can use the return value directly.
 62    """
 63    _clear()
 64
 65    resolved_level = (level or env.log_level()).upper()
 66    numeric = getattr(logging, resolved_level, None)
 67    if not isinstance(numeric, int):
 68        logging.getLogger(__name__).warning(
 69            "unknown log level %r; using INFO", resolved_level,
 70        )
 71        numeric = logging.INFO
 72    root = logging.getLogger()
 73    root.setLevel(numeric)
 74
 75    formatter = logging.Formatter(fmt=_FORMAT, datefmt=_DATEFMT)
 76
 77    if console:
 78        console_handler = logging.StreamHandler(stream=sys.stderr)
 79        console_handler.setFormatter(formatter)
 80        root.addHandler(console_handler)
 81        _installed.append(console_handler)
 82
 83    resolved_file: pathlib.Path | None = None
 84    if log_file is None:
 85        resolved_file = env.log_file()
 86    else:
 87        resolved_file = pathlib.Path(log_file).expanduser()
 88
 89    if resolved_file is not None:
 90        resolved_file.parent.mkdir(parents=True, exist_ok=True)
 91        rotate_bytes = (max_mb or env.log_max_mb()) * 1024 * 1024
 92        backup_count = backups if backups is not None else env.log_backups()
 93        file_handler = logging.handlers.RotatingFileHandler(
 94            resolved_file,
 95            maxBytes=rotate_bytes,
 96            backupCount=backup_count,
 97            encoding="utf-8",
 98        )
 99        file_handler.setFormatter(formatter)
100        root.addHandler(file_handler)
101        _installed.append(file_handler)
102
103    return resolved_file
104
105
106def _clear() -> None:
107    """Remove any handlers we've previously added. Used by
108    :func:`configure` for idempotency, and by tests via
109    :func:`reset`."""
110    root = logging.getLogger()
111    for handler in _installed:
112        root.removeHandler(handler)
113        try:
114            handler.close()
115        except OSError:
116            pass
117    _installed.clear()
118
119
120def reset() -> None:
121    """Public alias for the private cleanup — useful in test teardown
122    so each test gets a fresh handler set."""
123    _clear()
124
125
126def tail(path: pathlib.Path, n: int) -> list[str]:
127    """Return the last *n* non-blank log lines from *path*.
128
129    Reads the whole file — cheap for logs bounded by
130    ``JMRI_LOG_MAX_MB`` (default 5 MB). If the file doesn't exist,
131    returns an empty list rather than raising, so the /logs endpoint
132    can render a graceful empty state.
133    """
134    if not path.is_file():
135        return []
136    try:
137        text = path.read_text(encoding="utf-8", errors="replace")
138    except OSError:
139        return []
140    lines = [line for line in text.splitlines() if line.strip()]
141    return lines[-n:] if n > 0 else []