Skip to content

Logging

get_formatter(log_format='plain', formatter_str=None, use_colors=False, access_log=False)

Build a formatter from a predefined name or a custom format string.

Source code in aloha/logger/logger.py
def get_formatter(
    log_format: str = "plain",
    formatter_str: str | None = None,
    use_colors: bool = False,
    access_log: bool = False,
) -> logging.Formatter:
    """Build a formatter from a predefined name or a custom format string."""
    if formatter_str:
        return logging.Formatter(formatter_str)
    if log_format == "plain":
        format_log = DEFAULT_ACCESS_LOG_FORMAT if access_log else DEFAULT_LOG_FORMAT
        return PlainFormatter(format_log, use_colors=use_colors, include_source=not access_log)
    if log_format == "json":
        return JsonFormatter(include_source=not access_log, include_logger=not access_log, include_extra=access_log)
    raise ValueError(f"Unsupported log format: {log_format!r}. Choose 'plain' or 'json'.")

get_logger(logger_name=None, level=logging.DEBUG, **kwargs)

Get a configured logger instance.

Creates or retrieves a logger by name and sets it up with file and stream handlers. Accepts string and integer logging levels. If logger_name is None, configures the root logger.

Parameters:

Name Type Description Default
level

Logging level (int or str, default: DEBUG)

DEBUG
logger_name str | None

Logger name (default: the root logger)

None
kwargs

Additional keyword arguments passed to setup_logger

{}

Returns:

Type Description
Logger

Configured logger instance

Source code in aloha/logger/logger.py
def get_logger(logger_name: str | None = None, level=logging.DEBUG, **kwargs) -> logging.Logger:
    """
    Get a configured logger instance.

    Creates or retrieves a logger by name and sets it up with file and stream handlers.
    Accepts string and integer logging levels. If ``logger_name`` is ``None``,
    configures the root logger.

    :param level: Logging level (int or str, default: DEBUG)
    :param logger_name: Logger name (default: the root logger)
    :param kwargs: Additional keyword arguments passed to setup_logger
    :return: Configured logger instance
    """

    logger = logging.getLogger(logger_name)

    if isinstance(level, str):
        level = getattr(logging, str(level).upper(), 10)

    setup_logger(logger, level=level, logger_name=logger_name, **kwargs)
    return logger

JsonFormatter

Bases: Formatter

Format log records as JSON objects.

Source code in aloha/logger/logger.py
class JsonFormatter(logging.Formatter):
    """Format log records as JSON objects."""

    def __init__(self, include_source: bool = True, include_logger: bool = True, include_extra: bool = False):
        super().__init__()
        self.include_source = include_source
        self.include_logger = include_logger
        self.include_extra = include_extra

    def format(self, record: logging.LogRecord) -> str:
        payload = {
            "timestamp": _format_timestamp(record.created),
            "level": record.levelname,
            **_get_runtime_fields(),
        }
        if self.include_logger:
            payload["logger"] = record.name
        payload["message"] = record.getMessage()
        if self.include_source:
            payload["source"] = f"{record.filename}:{record.lineno}"
        if self.include_extra:
            for key, value in _get_extra_fields(record).items():
                if key == "logger" and not self.include_logger:
                    continue
                payload.setdefault(key, value)
        if record.exc_info:
            payload["exception"] = self.formatException(record.exc_info)
        if record.stack_info and record.levelno > logging.INFO:
            payload["stack_info"] = self.formatStack(record.stack_info)
        return json.dumps(payload, ensure_ascii=False, default=str)

PlainFormatter

Bases: Formatter

Format plain logs with an optional Uvicorn-style colored level prefix.

Source code in aloha/logger/logger.py
class PlainFormatter(logging.Formatter):
    """Format plain logs with an optional Uvicorn-style colored level prefix."""

    def __init__(self, fmt: str, use_colors: bool = False, include_source: bool = True):
        super().__init__(fmt)
        self.use_colors = use_colors
        self.include_source = include_source

    def formatMessage(self, record: logging.LogRecord) -> str:
        record_copy = copy(record)
        level_name = record_copy.levelname
        if self.use_colors and record_copy.levelno in LEVEL_COLORS:
            level_name = f"\x1b[{LEVEL_COLORS[record_copy.levelno]}m{level_name}\x1b[0m"
        record_copy.__dict__["levelprefix"] = f"{level_name}:{' ' * (8 - len(record_copy.levelname))}"
        if self.include_source:
            record_copy.__dict__["source"] = f"{record_copy.filename}:{record_copy.lineno}"
        else:
            if isinstance(record_copy.args, tuple) and len(record_copy.args) == 5:
                record_copy.msg = _format_access_message(record_copy.args, self.use_colors)
                record_copy.args = ()
            fields_access = json.dumps(_get_access_fields(record_copy), ensure_ascii=False, default=str)
            record_copy.msg = f"{record_copy.getMessage()} {fields_access}"
            record_copy.args = ()
            record_copy.message = record_copy.msg
        return super().formatMessage(record_copy)

    def formatTime(self, record: logging.LogRecord, datefmt: str | None = None) -> str:
        return _format_timestamp(record.created)

StackInfoFilter

Bases: Filter

Capture the calling stack for records above INFO when it was not supplied.

Source code in aloha/logger/logger.py
class StackInfoFilter(logging.Filter):
    """Capture the calling stack for records above INFO when it was not supplied."""

    def filter(self, record: logging.LogRecord) -> bool:
        if record.levelno > logging.INFO and not record.stack_info:
            frames = traceback.extract_stack()
            callsite = next(
                (
                    index
                    for index in range(len(frames) - 1, -1, -1)
                    if frames[index].filename == record.pathname and frames[index].lineno == record.lineno
                ),
                None,
            )
            if callsite is not None:
                frames = frames[: callsite + 1]
            else:
                frames = frames[:-1]
            record.stack_info = "Stack (most recent call last):\n" + "".join(traceback.format_list(frames))
        return True

get_formatter(log_format='plain', formatter_str=None, use_colors=False, access_log=False)

Build a formatter from a predefined name or a custom format string.

Source code in aloha/logger/logger.py
def get_formatter(
    log_format: str = "plain",
    formatter_str: str | None = None,
    use_colors: bool = False,
    access_log: bool = False,
) -> logging.Formatter:
    """Build a formatter from a predefined name or a custom format string."""
    if formatter_str:
        return logging.Formatter(formatter_str)
    if log_format == "plain":
        format_log = DEFAULT_ACCESS_LOG_FORMAT if access_log else DEFAULT_LOG_FORMAT
        return PlainFormatter(format_log, use_colors=use_colors, include_source=not access_log)
    if log_format == "json":
        return JsonFormatter(include_source=not access_log, include_logger=not access_log, include_extra=access_log)
    raise ValueError(f"Unsupported log format: {log_format!r}. Choose 'plain' or 'json'.")

get_logger(logger_name=None, level=logging.DEBUG, **kwargs)

Get a configured logger instance.

Creates or retrieves a logger by name and sets it up with file and stream handlers. Accepts string and integer logging levels. If logger_name is None, configures the root logger.

Parameters:

Name Type Description Default
level

Logging level (int or str, default: DEBUG)

DEBUG
logger_name str | None

Logger name (default: the root logger)

None
kwargs

Additional keyword arguments passed to setup_logger

{}

Returns:

Type Description
Logger

Configured logger instance

Source code in aloha/logger/logger.py
def get_logger(logger_name: str | None = None, level=logging.DEBUG, **kwargs) -> logging.Logger:
    """
    Get a configured logger instance.

    Creates or retrieves a logger by name and sets it up with file and stream handlers.
    Accepts string and integer logging levels. If ``logger_name`` is ``None``,
    configures the root logger.

    :param level: Logging level (int or str, default: DEBUG)
    :param logger_name: Logger name (default: the root logger)
    :param kwargs: Additional keyword arguments passed to setup_logger
    :return: Configured logger instance
    """

    logger = logging.getLogger(logger_name)

    if isinstance(level, str):
        level = getattr(logging, str(level).upper(), 10)

    setup_logger(logger, level=level, logger_name=logger_name, **kwargs)
    return logger

setup_logger(logger, level=logging.DEBUG, logger_name=None, module=None, formatter_str=None, log_format=None, log_format_file='json', log_format_stream='plain', stream=None, access_log=False)

Set up a logger with file and stream handlers.

Configures the logger with: - A multi-process safe daily rotating file handler - A console stream handler - A standard log format

Parameters:

Name Type Description Default
logger Logger

Logger instance to set up

required
level int

Logging level (default: DEBUG)

DEBUG
logger_name str | None

Name of the logger (optional)

None
module str | None

Module name for log file naming (optional)

None
formatter_str str | None

Custom log format string (optional)

None
log_format str | None

Deprecated format override for both file and stream

None
log_format_file str

Predefined format for the file handler

'json'
log_format_stream str

Predefined format for the console handler

'plain'
stream TextIO | None

Console output stream (defaults to stderr)

None
access_log bool

Use the access-log format and omit the source location

False
Source code in aloha/logger/logger.py
def setup_logger(
    logger: logging.Logger,
    level: int = logging.DEBUG,
    logger_name: str | None = None,
    module: str | None = None,
    formatter_str: str | None = None,
    log_format: str | None = None,
    log_format_file: str = "json",
    log_format_stream: str = "plain",
    stream: TextIO | None = None,
    access_log: bool = False,
):
    """
    Set up a logger with file and stream handlers.

    Configures the logger with:
    - A multi-process safe daily rotating file handler
    - A console stream handler
    - A standard log format

    :param logger: Logger instance to set up
    :param level: Logging level (default: DEBUG)
    :param logger_name: Name of the logger (optional)
    :param module: Module name for log file naming (optional)
    :param formatter_str: Custom log format string (optional)
    :param log_format: Deprecated format override for both file and stream
    :param log_format_file: Predefined format for the file handler
    :param log_format_stream: Predefined format for the console handler
    :param stream: Console output stream (defaults to stderr)
    :param access_log: Use the access-log format and omit the source location
    """
    if not logger.handlers:
        if log_format is not None:
            log_format_file = log_format
            log_format_stream = log_format

        folder = os.environ.get("DIR_LOG", "logs")
        os.makedirs(folder, exist_ok=True)

        if module is None:
            from ..settings import SETTINGS

            module = SETTINGS.config.get("APP_MODULE") or os.environ.get("APP_MODULE")
        module = module or "default"

        path_file = pjoin(folder, f"{module}.log")

        file_handler = MultiProcessSafeDailyRotatingFileHandler(
            path_file,
            filename_suffix=".access" if access_log else "",
        )
        file_handler.setFormatter(
            get_formatter(log_format=log_format_file, formatter_str=formatter_str, access_log=access_log)
        )
        file_handler.addFilter(StackInfoFilter())
        logger.addHandler(file_handler)

        stream_handler = logging.StreamHandler(stream)
        stream_formatter = get_formatter(
            log_format=log_format_stream,
            formatter_str=formatter_str,
            use_colors=stream_handler.stream.isatty(),
            access_log=access_log,
        )
        stream_handler.setFormatter(stream_formatter)
        stream_handler.addFilter(StackInfoFilter())
        logger.addHandler(stream_handler)

        logger.setLevel(level)

MultiProcessSafeDailyRotatingFileHandler

Bases: BaseRotatingHandler

Similar with logging.TimedRotatingFileHandler, while this one is - Multi process safe - Rotate at midnight only - Utc not supported

Source code in aloha/logger/handler.py
class MultiProcessSafeDailyRotatingFileHandler(BaseRotatingHandler):
    """Similar with `logging.TimedRotatingFileHandler`, while this one is
    - Multi process safe
    - Rotate at midnight only
    - Utc not supported
    """

    def __init__(
        self,
        filename: str,
        encoding="utf8",
        delay=False,
        utc=False,
        date_format="%Y-%m%d",
        filename_suffix="",
        **kwargs,
    ):
        self.utc = utc
        self.date_format = date_format
        self.filename_suffix = filename_suffix
        self.baseFilename = filename
        self.currentFileName = self._compute_fn()
        BaseRotatingHandler.__init__(self, filename, "a", encoding, delay)

    def shouldRollover(self, record):
        return self.currentFileName != self._compute_fn()

    def doRollover(self):
        if self.stream:
            self.stream.close()
            self.stream = None
        self.currentFileName = self._compute_fn()
        if not self.delay:
            self.stream = self._open()

    def _compute_fn(self):
        return (
            self.baseFilename.removesuffix(".log")
            + "_"
            + time.strftime(self.date_format, time.localtime())
            + self.filename_suffix
            + ".log"
        )

    def _open(self):
        return open(self.currentFileName, mode=self.mode, encoding=self.encoding)

    def close(self):
        """Closes the stream."""
        self.acquire()
        try:
            try:
                if self.stream:
                    try:
                        self.flush()
                    finally:
                        stream = self.stream
                        self.stream = None
                        if hasattr(stream, "close"):
                            # print('ttt')
                            stream.close()
            finally:
                # Issue #19523: call unconditionally to prevent a handler leak when delay is set
                StreamHandler.close(self)
        finally:
            self.release()

close()

Closes the stream.

Source code in aloha/logger/handler.py
def close(self):
    """Closes the stream."""
    self.acquire()
    try:
        try:
            if self.stream:
                try:
                    self.flush()
                finally:
                    stream = self.stream
                    self.stream = None
                    if hasattr(stream, "close"):
                        # print('ttt')
                        stream.close()
        finally:
            # Issue #19523: call unconditionally to prevent a handler leak when delay is set
            StreamHandler.close(self)
    finally:
        self.release()