shared-snippets/python/logging/base_logger.py

#
# -----------------
# Copyright © 2024 ACK Cyfronet AGH, Poland.
# -----------------
#
import os
import logging

def getDefaultLogger(name):
    """
    Retrieves or creates a logger with the specified name and sets it up with a file handler.
    
    The logger is configured to write log messages to the file path specified by the
    'APP_LOG_FILE' environment variable. If the environment variable is not set,
    the logger will write to the file 'base-logger-log.log' in the current
    working directory. The logger uses the 'INFO' level as the default logging level
    and writes log entries in the following format:
    
    'YYYY-MM-DD HH:MM:SS,ms LEVEL logger_name message'
    
    If the logger does not already have handlers, a file handler is created, and the 
    logging output is appended to the file. The log format includes the timestamp with 
    milliseconds, log level, logger name, and the log message.

    Parameters:
    -----------
    name : str
        The name of the logger. This can be the name of the module or any identifier 
        that you want to associate with the logger.

    Returns:
    --------
    logger : logging.Logger
        A logger instance with the specified name. The logger is configured with a 
        file handler that writes to the file specified by the 'APP_LOG_FILE' 
        environment variable, or to 'base-logger-log.log' if the environment 
        variable is not set.
    
    Example:
    --------
    logger = getDefaultLogger(__name__)
    logger.info("This is an info message.")
    try:
        # some code causing exception
    except Exception:
        logger.exception('An error occurred')

    Notes:
    ------
    - The 'APP_LOG_FILE' environment variable should specify the full path to the log file.
    - If 'APP_LOG_FILE' is not set, logs will be written to 'base-logger-log.log'.

    """
    logger = logging.getLogger(name)
    if not logger.hasHandlers():
        file_handler = logging.FileHandler(os.environ.get('APP_LOG_FILE', 'base-logger-log.log'), mode='a')
        formatter = logging.Formatter('%(asctime)s,%(msecs)d %(levelname)s %(name)s %(message)s')
        file_handler.setFormatter(formatter)
        logger.addHandler(file_handler)
    logger.setLevel(logging.INFO)
    
    return logger