gllm-core-binary 0.4.4__py3-none-macosx_13_0_arm64.whl

gllm_core/utils/logger_manager.py

@@ -0,0 +1,339 @@
+"""Defines a logger manager to manage logging configuration across the Gen AI application components.
+
+Authors:
+    Dimitrij Ray (dimitrij.ray@gdplabs.id)
+    Henry Wicaksono (henry.wicaksono@gdplabs.id)
+    Hermes Vincentius Gani (hermes.v.gani@gdplabs.id)
+
+References:
+    NONE
+"""
+
+import logging
+import os
+import threading
+
+from pythonjsonlogger.core import LogRecord
+from pythonjsonlogger.json import JsonFormatter
+from rich.console import Console
+from rich.highlighter import NullHighlighter
+from rich.logging import RichHandler
+
+from gllm_core.constants import LogMode
+
+DEFAULT_DATE_FORMAT = "%Y-%m-%dT%H:%M:%S%z"
+TEXT_COLOR_MAP = {
+    logging.DEBUG: "green",
+    logging.INFO: "blue",
+    logging.WARNING: "yellow",
+    logging.ERROR: "red",
+    logging.CRITICAL: "bold black on red",
+}
+LOG_FORMAT_KEY = "LOG_FORMAT"
+RICH_CLOSE_TAG = "[/"
+JSON_LOG_FIELDS = ["timestamp", "name", "level", "message"]
+JSON_ERROR_FIELDS_MAP = {
+    "exc_info": "message",
+    "stack_info": "stacktrace",
+    "error_code": "code",
+}
+
+
+class TextRichHandler(RichHandler):
+    """Custom RichHandler that applies specific colors and log format."""
+
+    def emit(self, record: logging.LogRecord) -> None:
+        """Emits a log record with custom coloring.
+
+        Args:
+            record (logging.LogRecord): The log record to emit.
+        """
+        color = TEXT_COLOR_MAP.get(record.levelno, "white")
+
+        name, msg = record.name, record.getMessage()
+        msg = msg.replace(RICH_CLOSE_TAG, rf"\{RICH_CLOSE_TAG}")
+
+        record.msg = f"[{color}][{name}] {msg}[/]"
+        record.args = None
+
+        super().emit(record)
+
+
+class SimpleRichHandler(logging.StreamHandler):
+    """Custom StreamHandler that utilizes Rich only to apply colors, without columns or Rich formatting.
+
+    Attributes:
+        console (Console): The Rich Console object to use for printing.
+    """
+
+    def __init__(self, *args, **kwargs) -> None:
+        """Initializes a new instance of the SimpleRichHandler class."""
+        super().__init__(*args, **kwargs)
+        self.console = Console(file=self.stream)
+
+    def emit(self, record: logging.LogRecord) -> None:
+        """Emits a log record with simple Rich coloring.
+
+        Args:
+            record (logging.LogRecord): The log record to emit.
+        """
+        color = TEXT_COLOR_MAP.get(record.levelno, "white")
+        msg = self.format(record)
+        msg = msg.replace(RICH_CLOSE_TAG, rf"\{RICH_CLOSE_TAG}")
+
+        self.console.print(f"[{color}]{msg}[/]", markup=True, highlight=False)
+
+
+class AppJSONFormatter(JsonFormatter):
+    """JSON formatter that groups error-related fields under an 'error' key.
+
+    This formatter renames the following fields when present:
+    1. exc_info -> error.message
+    2. stack_info -> error.stacktrace
+    3. error_code -> error.code
+    """
+
+    def process_log_record(self, log_record: LogRecord) -> LogRecord:
+        """Process log record to group and rename error-related fields.
+
+        Args:
+            log_record (LogRecord): The original log record.
+
+        Returns:
+            LogRecord: The processed log record.
+        """
+        record = super().process_log_record(log_record)
+        logged_record = {key: value for key, value in record.items() if key in JSON_LOG_FIELDS}
+        error_payload: dict[str, str] = dict.fromkeys(JSON_ERROR_FIELDS_MAP.values(), "")
+
+        for key, new_key in JSON_ERROR_FIELDS_MAP.items():
+            if value := record.get(key):
+                error_payload[new_key] = value
+
+        if any(error_payload.values()):
+            logged_record["error"] = error_payload
+
+        return logged_record
+
+
+LOG_FORMAT_HANDLER_MAP = {
+    LogMode.TEXT: TextRichHandler(
+        markup=True,
+        omit_repeated_times=False,
+        highlighter=NullHighlighter(),
+    ),
+    LogMode.SIMPLE: SimpleRichHandler(),
+    LogMode.JSON: logging.StreamHandler(),
+}
+
+LOG_FORMAT_MAP = {
+    LogMode.TEXT: "%(message)s",
+    LogMode.SIMPLE: "[%(asctime)s.%(msecs)03d %(name)s %(levelname)s] %(message)s",
+    LogMode.JSON: "{asctime} {name} {levelname} {message}",
+}
+
+
+class LoggerManager:
+    """A singleton class to manage logging configuration.
+
+    This class ensures that the root logger is initialized only once and is used across the application.
+
+    Basic usage:
+        The `LoggerManager` can be used to get a logger instance as follows:
+        ```python
+        logger = LoggerManager().get_logger()
+        logger.info("This is an info message")
+        ```
+
+    Set logging configuration:
+        The `LoggerManager` also provides capabilities to set the logging configuration:
+        ```python
+        manager = LoggerManager()
+        manager.set_level(logging.DEBUG)
+        manager.set_log_format(custom_log_format)
+        manager.set_date_format(custom_date_format)
+        ```
+
+    Add custom handlers:
+        The `LoggerManager` also provides capabilities to add custom handlers to the root logger:
+        ```python
+        manager = LoggerManager()
+        handler = logging.FileHandler("app.log")
+        manager.add_handler(handler)
+        ```
+
+    Extra error information:
+        When logging errors, extra error information can be added as follows:
+        ```python
+        logger.error("I am dead!", extra={"error_code": "ERR_CONN_REFUSED"})
+        ```
+
+    Logging modes:
+        The `LoggerManager` supports three logging modes:
+
+        1. Text: Logs in a human-readable format with RichHandler column-based formatting.
+            Used when the `LOG_FORMAT` environment variable is set to "text".
+            Output example:
+            ```log
+            2025-10-08T09:26:16 DEBUG    [LoggerName] This is a debug message.
+            2025-10-08T09:26:17 INFO     [LoggerName] This is an info message.
+            2025-10-08T09:26:18 WARNING  [LoggerName] This is a warning message.
+            2025-10-08T09:26:19 ERROR    [LoggerName] This is an error message.
+            2025-10-08T09:26:20 CRITICAL [LoggerName] This is a critical message.
+            ```
+
+        2. Simple: Logs in a human-readable format with Rich colors but without columns-based formatting.
+            Used when the `LOG_FORMAT` environment variable is set to "simple".
+            Output example:
+            ```log
+            [2025-10-08T09:26:16.123 LoggerName DEBUG] This is a debug message.
+            [2025-10-08T09:26:17.456 LoggerName INFO] This is an info message.
+            [2025-10-08T09:26:18.789 LoggerName WARNING] This is a warning message.
+            [2025-10-08T09:26:19.012 LoggerName ERROR] This is an error message.
+            [2025-10-08T09:26:20.345 LoggerName CRITICAL] This is a critical message.
+            ```
+
+        3. JSON: Logs in a JSON format, recommended for easy parsing due to the structured nature of the log records.
+            Used when the `LOG_FORMAT` environment variable is set to "json".
+            Output example:
+            ```log
+            {"timestamp": "2025-10-08T11:23:43+0700", "name": "LoggerName", "level": "DEBUG", "message": "..."}
+            {"timestamp": "2025-10-08T11:23:44+0700", "name": "LoggerName", "level": "INFO", "message": "..."}
+            {"timestamp": "2025-10-08T11:23:45+0700", "name": "LoggerName", "level": "WARNING", "message": "..."}
+            {"timestamp": "2025-10-08T11:23:46+0700", "name": "LoggerName", "level": "ERROR", "message": "..."}
+            {"timestamp": "2025-10-08T11:23:47+0700", "name": "LoggerName", "level": "CRITICAL", "message": "..."}
+            ```
+
+        When the `LOG_FORMAT` environment is not set, the `LoggerManager` defaults to "text" mode.
+    """
+
+    _instance = None
+    _root_logger = None
+    _handlers = None
+    _formatter = None
+    _lock = threading.Lock()
+
+    def __new__(cls) -> "LoggerManager":
+        """Initialize the singleton instance.
+
+        Returns:
+            LoggerManager: The singleton instance.
+        """
+        with cls._lock:
+            if cls._instance is None:
+                cls._instance = super().__new__(cls)
+                cls._initialize_root_logger()
+            return cls._instance
+
+    # TODO: Refactor determining log mode via parameter instead of environment variable
+    @classmethod
+    def _initialize_root_logger(cls) -> None:
+        """Initialize the root logger with default configuration."""
+        log_mode = os.getenv(LOG_FORMAT_KEY, LogMode.TEXT).lower()
+
+        cls._log_mode = log_mode if log_mode in LOG_FORMAT_HANDLER_MAP else LogMode.TEXT
+        cls._root_logger = logging.getLogger()
+        cls._root_logger.handlers.clear()
+        cls._formatter = cls._build_formatter()
+
+        default_handler = LOG_FORMAT_HANDLER_MAP[cls._log_mode]
+        default_handler.setFormatter(cls._formatter)
+        cls._handlers = [default_handler]
+        cls._root_logger.addHandler(default_handler)
+        cls._root_logger.setLevel(logging.INFO)
+        cls._root_logger.propagate = False
+
+    @classmethod
+    def _build_formatter(cls, fmt: str | None = None, datefmt: str = DEFAULT_DATE_FORMAT) -> logging.Formatter:
+        """Create a formatter based on current mode (JSON, TEXT, or SIMPLE).
+
+        Args:
+            fmt (str | None, optional): The format string. Defaults to None,
+                in which case the default log format is used.
+            datefmt (str, optional): The date format string. Defaults to DEFAULT_DATE_FORMAT.
+
+        Returns:
+            logging.Formatter: The formatter.
+        """
+        fmt = fmt or LOG_FORMAT_MAP[cls._log_mode]
+
+        if not cls._log_mode == LogMode.JSON:
+            return logging.Formatter(fmt, datefmt)
+
+        return AppJSONFormatter(
+            fmt=fmt,
+            datefmt=datefmt,
+            style="{",
+            rename_fields={"asctime": "timestamp", "levelname": "level"},
+        )
+
+    def get_logger(self, name: str | None = None) -> logging.Logger:
+        """Get a logger instance.
+
+        This method returns a logger instance that is a child of the root logger. If name is not provided,
+        the root logger will be returned instead.
+
+        Args:
+            name (str | None, optional): The name of the child logger. If None, the root logger will be returned.
+                Defaults to None.
+
+        Returns:
+            logging.Logger: Configured logger instance.
+        """
+        if name:
+            child = self._root_logger.getChild(name)
+            child.propagate = False
+            if not child.handlers:
+                for handler in self._handlers:
+                    child.addHandler(handler)
+            return child
+        return self._root_logger
+
+    def set_level(self, level: int) -> None:
+        """Set logging level for all loggers in the hierarchy.
+
+        Args:
+            level (int): The logging level to set (e.g., logging.INFO, logging.DEBUG).
+        """
+        self._root_logger.setLevel(level)
+
+    def set_log_format(self, log_format: str) -> None:
+        """Set logging format for all loggers in the hierarchy.
+
+        Args:
+            log_format (str): The log format to set.
+        """
+        self._update_formatter(fmt=log_format)
+
+    def set_date_format(self, date_format: str) -> None:
+        """Set date format for all loggers in the hierarchy.
+
+        Args:
+            date_format (str): The date format to set.
+        """
+        self._update_formatter(datefmt=date_format)
+
+    def add_handler(self, handler: logging.Handler) -> None:
+        """Add a custom handler to the root logger.
+
+        Args:
+            handler (logging.Handler): The handler to add to the root logger.
+        """
+        handler.setFormatter(self._formatter)
+        self._root_logger.addHandler(handler)
+        self._handlers.append(handler)
+
+    def _update_formatter(self, fmt: str | None = None, datefmt: str | None = None) -> None:
+        """Update formatter and apply to all handlers.
+
+        Args:
+            fmt (str | None, optional): The format string. Defaults to None.
+            datefmt (str | None, optional): The date format string. Defaults to None.
+        """
+        current_fmt_default = LOG_FORMAT_MAP[self._log_mode]
+        current_fmt = fmt if fmt is not None else getattr(self._formatter, "_fmt", current_fmt_default)
+        current_datefmt = datefmt if datefmt is not None else getattr(self._formatter, "datefmt", DEFAULT_DATE_FORMAT)
+
+        self._formatter = self._build_formatter(current_fmt, current_datefmt)
+        for handler in self._handlers:
+            handler.setFormatter(self._formatter)

gllm_core/utils/logger_manager.pyi

@@ -0,0 +1,176 @@
+import logging
+from _typeshed import Incomplete
+from gllm_core.constants import LogMode as LogMode
+from pythonjsonlogger.core import LogRecord
+from pythonjsonlogger.json import JsonFormatter
+from rich.logging import RichHandler
+
+DEFAULT_DATE_FORMAT: str
+TEXT_COLOR_MAP: Incomplete
+LOG_FORMAT_KEY: str
+RICH_CLOSE_TAG: str
+JSON_LOG_FIELDS: Incomplete
+JSON_ERROR_FIELDS_MAP: Incomplete
+
+class TextRichHandler(RichHandler):
+    """Custom RichHandler that applies specific colors and log format."""
+    def emit(self, record: logging.LogRecord) -> None:
+        """Emits a log record with custom coloring.
+
+        Args:
+            record (logging.LogRecord): The log record to emit.
+        """
+
+class SimpleRichHandler(logging.StreamHandler):
+    """Custom StreamHandler that utilizes Rich only to apply colors, without columns or Rich formatting.
+
+    Attributes:
+        console (Console): The Rich Console object to use for printing.
+    """
+    console: Incomplete
+    def __init__(self, *args, **kwargs) -> None:
+        """Initializes a new instance of the SimpleRichHandler class."""
+    def emit(self, record: logging.LogRecord) -> None:
+        """Emits a log record with simple Rich coloring.
+
+        Args:
+            record (logging.LogRecord): The log record to emit.
+        """
+
+class AppJSONFormatter(JsonFormatter):
+    """JSON formatter that groups error-related fields under an 'error' key.
+
+    This formatter renames the following fields when present:
+    1. exc_info -> error.message
+    2. stack_info -> error.stacktrace
+    3. error_code -> error.code
+    """
+    def process_log_record(self, log_record: LogRecord) -> LogRecord:
+        """Process log record to group and rename error-related fields.
+
+        Args:
+            log_record (LogRecord): The original log record.
+
+        Returns:
+            LogRecord: The processed log record.
+        """
+
+LOG_FORMAT_HANDLER_MAP: Incomplete
+LOG_FORMAT_MAP: Incomplete
+
+class LoggerManager:
+    '''A singleton class to manage logging configuration.
+
+    This class ensures that the root logger is initialized only once and is used across the application.
+
+    Basic usage:
+        The `LoggerManager` can be used to get a logger instance as follows:
+        ```python
+        logger = LoggerManager().get_logger()
+        logger.info("This is an info message")
+        ```
+
+    Set logging configuration:
+        The `LoggerManager` also provides capabilities to set the logging configuration:
+        ```python
+        manager = LoggerManager()
+        manager.set_level(logging.DEBUG)
+        manager.set_log_format(custom_log_format)
+        manager.set_date_format(custom_date_format)
+        ```
+
+    Add custom handlers:
+        The `LoggerManager` also provides capabilities to add custom handlers to the root logger:
+        ```python
+        manager = LoggerManager()
+        handler = logging.FileHandler("app.log")
+        manager.add_handler(handler)
+        ```
+
+    Extra error information:
+        When logging errors, extra error information can be added as follows:
+        ```python
+        logger.error("I am dead!", extra={"error_code": "ERR_CONN_REFUSED"})
+        ```
+
+    Logging modes:
+        The `LoggerManager` supports three logging modes:
+
+        1. Text: Logs in a human-readable format with RichHandler column-based formatting.
+            Used when the `LOG_FORMAT` environment variable is set to "text".
+            Output example:
+            ```log
+            2025-10-08T09:26:16 DEBUG    [LoggerName] This is a debug message.
+            2025-10-08T09:26:17 INFO     [LoggerName] This is an info message.
+            2025-10-08T09:26:18 WARNING  [LoggerName] This is a warning message.
+            2025-10-08T09:26:19 ERROR    [LoggerName] This is an error message.
+            2025-10-08T09:26:20 CRITICAL [LoggerName] This is a critical message.
+            ```
+
+        2. Simple: Logs in a human-readable format with Rich colors but without columns-based formatting.
+            Used when the `LOG_FORMAT` environment variable is set to "simple".
+            Output example:
+            ```log
+            [2025-10-08T09:26:16.123 LoggerName DEBUG] This is a debug message.
+            [2025-10-08T09:26:17.456 LoggerName INFO] This is an info message.
+            [2025-10-08T09:26:18.789 LoggerName WARNING] This is a warning message.
+            [2025-10-08T09:26:19.012 LoggerName ERROR] This is an error message.
+            [2025-10-08T09:26:20.345 LoggerName CRITICAL] This is a critical message.
+            ```
+
+        3. JSON: Logs in a JSON format, recommended for easy parsing due to the structured nature of the log records.
+            Used when the `LOG_FORMAT` environment variable is set to "json".
+            Output example:
+            ```log
+            {"timestamp": "2025-10-08T11:23:43+0700", "name": "LoggerName", "level": "DEBUG", "message": "..."}
+            {"timestamp": "2025-10-08T11:23:44+0700", "name": "LoggerName", "level": "INFO", "message": "..."}
+            {"timestamp": "2025-10-08T11:23:45+0700", "name": "LoggerName", "level": "WARNING", "message": "..."}
+            {"timestamp": "2025-10-08T11:23:46+0700", "name": "LoggerName", "level": "ERROR", "message": "..."}
+            {"timestamp": "2025-10-08T11:23:47+0700", "name": "LoggerName", "level": "CRITICAL", "message": "..."}
+            ```
+
+        When the `LOG_FORMAT` environment is not set, the `LoggerManager` defaults to "text" mode.
+    '''
+    def __new__(cls) -> LoggerManager:
+        """Initialize the singleton instance.
+
+        Returns:
+            LoggerManager: The singleton instance.
+        """
+    def get_logger(self, name: str | None = None) -> logging.Logger:
+        """Get a logger instance.
+
+        This method returns a logger instance that is a child of the root logger. If name is not provided,
+        the root logger will be returned instead.
+
+        Args:
+            name (str | None, optional): The name of the child logger. If None, the root logger will be returned.
+                Defaults to None.
+
+        Returns:
+            logging.Logger: Configured logger instance.
+        """
+    def set_level(self, level: int) -> None:
+        """Set logging level for all loggers in the hierarchy.
+
+        Args:
+            level (int): The logging level to set (e.g., logging.INFO, logging.DEBUG).
+        """
+    def set_log_format(self, log_format: str) -> None:
+        """Set logging format for all loggers in the hierarchy.
+
+        Args:
+            log_format (str): The log format to set.
+        """
+    def set_date_format(self, date_format: str) -> None:
+        """Set date format for all loggers in the hierarchy.
+
+        Args:
+            date_format (str): The date format to set.
+        """
+    def add_handler(self, handler: logging.Handler) -> None:
+        """Add a custom handler to the root logger.
+
+        Args:
+            handler (logging.Handler): The handler to add to the root logger.
+        """