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 'fallbackPathApplication.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 'fallbackPathApplication.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 'fallbackPathApplication.log'.

    """
    logger = logging.getLogger(name)
    if not logger.hasHandlers():
        file_handler = logging.FileHandler(os.environ.get('APP_LOG_FILE', 'fallbackPathApplication.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