Source code for kelvin.logs

"""Kelvin application logging configuration.

This module provides structured logging configuration for Kelvin applications
using structlog. It automatically configures console rendering for interactive
sessions and JSON rendering for production environments.

Main Components:
    configure_logger: Initialize the structlog logging configuration.
    logger: Pre-configured structlog logger instance.
    iso_datetime_processor: Processor to convert datetime values to ISO strings.

Example:
    >>> from kelvin.logs import logger, configure_logger
    >>> configure_logger()
    >>> logger.info("Application started", version="1.0.0")
"""

from __future__ import annotations

import sys
from datetime import datetime
from typing import Any, Mapping, MutableMapping

import structlog




def iso_datetime_processor(_: Any, __: str, event_dict: MutableMapping[str, Any]) -> Mapping[str, Any]:
    """
    Scan the event_dict for datetime values and convert them to ISO strings.
    """
    for key, value in list(event_dict.items()):
        if isinstance(value, datetime):
            event_dict[key] = value.isoformat()
    return event_dict





def configure_logger(*args: Any, **initial_values: Any) -> None:
    """Configure structlog."""

    if not structlog.is_configured():
        structlog.configure_once(
            processors=[
                structlog.stdlib.add_log_level,
                structlog.stdlib.PositionalArgumentsFormatter(),
                structlog.processors.dict_tracebacks,
                structlog.processors.format_exc_info,
                structlog.processors.TimeStamper(fmt="iso", utc=True),
                iso_datetime_processor,
                structlog.dev.ConsoleRenderer() if sys.stdout.isatty() else structlog.processors.JSONRenderer(),
            ],
            cache_logger_on_first_use=True,
        )



logger = structlog.get_logger()