apppy-logger 0.15.1__py3-none-any.whl

apppy/logger/__init__.py

@@ -0,0 +1,72 @@
+import logging
+import sys
+
+from apppy.logger.filter import SuppressApiLoggingFilter
+from apppy.logger.format import ExtraLoggingFormatter, NewLineTerminator
+from apppy.logger.parser import LogRecordParser
+from apppy.logger.storage import LoggingStorage
+
+
+def bootstrap_global_logging(level, stdout=False):
+    """
+    Utility to apply custom logging configuration
+    to application loggers. It should be called very
+    early in the application boot process.
+    """
+    if isinstance(level, str):
+        level = logging._nameToLevel[level.upper()]
+
+    logging.root.setLevel(level)
+
+    if stdout:
+        # Configure the logging system to use stdout.
+        # This should be used for frameworks with minimal logging configuration (e.g. AWS Lambda)
+        # For mature application frameworks (e.g. uvicorn), do not use the stdout flag.
+        logging.basicConfig(level=level, handlers=[logging.StreamHandler(sys.stdout)], force=True)
+
+    logging.getLogger("httpcore").setLevel(logging.INFO)
+    logging.getLogger("httpcore.connection").setLevel(logging.INFO)
+    logging.getLogger("httpcore.http11").setLevel(logging.INFO)
+
+    # Setup global singletons
+    LogRecordParser.set_global()
+    LoggingStorage.set_global()
+    # Apply formatters to all loggers so that their
+    # output is uniform
+    ExtraLoggingFormatter.apply(logging.root)
+    ExtraLoggingFormatter.apply_all()
+    # Setup the filter to add Logging Storage state
+    # to each log record
+    LoggingStorage.apply_all()
+
+    if stdout:
+        # If we configured stdout (see comment above) then
+        # ensure logs go on separate lines
+        NewLineTerminator.apply_all()
+
+    # A /health endpoint is typically called a lot in deployed environments
+    # as part of load balancer checks. This bloats the application logs
+    # so this filter allows health checks to be skipped in logs.
+    SuppressApiLoggingFilter.apply(logging.getLogger("uvicorn.access"), "/health")
+
+
+class WithLogger:
+    """
+    Class decorator that injects a _logger object using a very standard
+    naming convention. The convention is based on the class name so that
+    log lines can be easily associated with a given class. For example:
+
+    class MyService(WithLogger):
+        ...
+        def do_something(self):
+            # This logger will be named with the module and class names
+            # e.g. 'module.path.to.MyService'
+            self._logger.info("I am doing something")
+        ...
+    """
+
+    _logger: logging.Logger
+
+    def __init_subclass__(cls, **kwargs):
+        super().__init_subclass__(**kwargs)
+        cls._logger = logging.getLogger(f"{cls.__module__}.{cls.__qualname__}")

apppy/logger/filter.py

@@ -0,0 +1,19 @@
+import logging
+
+
+class SuppressApiLoggingFilter(logging.Filter):
+    """
+    Suppress HTTP logs to an API endpoint via its path.
+    """
+
+    def __init__(self, path: str):
+        super().__init__(f"SuppressApiLoggingFilter_{path}")
+        self._path = path
+
+    def filter(self, record: logging.LogRecord) -> bool:
+        return record.getMessage().find(self._path) == -1
+
+    @classmethod
+    def apply(cls, logger: logging.Logger, path: str):
+        filter = cls(path)
+        logger.addFilter(filter)

apppy/logger/format.py

@@ -0,0 +1,62 @@
+import logging
+
+from apppy.logger.parser import LogRecordParser
+
+fmt_default = "%(asctime)s | %(levelname)s | %(name)s | %(message)s"
+datefmt_default = "%Y-%m-%dT%H:%M:%SZ%z"
+
+
+class ExtraLoggingFormatter(logging.Formatter):
+    def __init__(self, fmt=None, datefmt=None, style="%"):
+        super().__init__(fmt, datefmt, style)
+
+    def format(self, record):
+        message = super().format(record)
+
+        state_info = LogRecordParser.get_global().parse_state_info(record)
+        if state_info:
+            state_str = " | ".join(f"{key}={value}" for key, value in state_info.items())
+            message = f"{message} | {state_str}"
+
+        extra_info = LogRecordParser.get_global().parse_extra_info(record)
+        if extra_info:
+            extra_str = " | ".join(f"{key}={value}" for key, value in extra_info.items())
+            message = f"{message} | {extra_str}"
+
+        return message
+
+    @classmethod
+    def apply(cls, logger: logging.Logger, fmt: str = fmt_default, datefmt: str = datefmt_default):
+        # Check if the logger has any handlers and add a default if none exist
+        if not logger.hasHandlers():
+            handler = logging.StreamHandler()
+            logger.addHandler(handler)
+
+        # Apply formatter to all handlers
+        formatter = cls(fmt=fmt, datefmt=datefmt)
+        for h in logger.handlers:
+            h.setFormatter(formatter)
+
+    @classmethod
+    def apply_all(cls, fmt: str = fmt_default, datefmt: str = datefmt_default):
+        logger_dict = logging.Logger.manager.loggerDict
+        for logger_name in logger_dict:
+            logger = logger_dict.get(logger_name)
+            if isinstance(logger, logging.Logger):
+                ExtraLoggingFormatter.apply(logger, fmt=fmt, datefmt=datefmt)
+
+
+class NewLineTerminator:
+    @classmethod
+    def apply(cls, logger: logging.Logger):
+        for h in logger.handlers:
+            if isinstance(h, logging.StreamHandler):
+                h.terminator = "\n"
+
+    @classmethod
+    def apply_all(cls):
+        logger_dict = logging.Logger.manager.loggerDict
+        for logger_name in logger_dict:
+            logger = logger_dict.get(logger_name)
+            if isinstance(logger, logging.Logger):
+                NewLineTerminator.apply(logger)

apppy/logger/format_unit_test.py

@@ -0,0 +1,127 @@
+import logging
+from logging import LogRecord
+
+from apppy.logger.format import ExtraLoggingFormatter, datefmt_default, fmt_default
+from apppy.logger.parser import LogRecordParser
+from apppy.logger.storage import LoggingStorage
+
+LogRecordParser.set_global()
+LoggingStorage.set_global()
+
+
+def test_format_no_extra():
+    formatter: ExtraLoggingFormatter = ExtraLoggingFormatter(
+        fmt=fmt_default, datefmt=datefmt_default
+    )
+
+    logger = logging.Logger("test_format_no_extra")
+    record: LogRecord = logger.makeRecord(
+        name="test_format_no_extra",
+        level=logging.INFO,
+        fn="test_format_no_extra",
+        lno=19,
+        msg="test_format_no_extra message",
+        args=None,
+        exc_info=None,
+    )
+    msg = formatter.format(record)
+    assert msg.endswith(
+        "| INFO | test_format_no_extra | test_format_no_extra message"
+    ), f"Unexpected formatted msg: {msg}"
+
+
+def test_format_with_extra():
+    formatter: ExtraLoggingFormatter = ExtraLoggingFormatter(
+        fmt=fmt_default, datefmt=datefmt_default
+    )
+
+    logger = logging.Logger("test_format_with_extra")
+    record: LogRecord = logger.makeRecord(
+        name="test_format_with_extra",
+        level=logging.INFO,
+        fn="test_format_with_extra",
+        lno=19,
+        msg="test_format_with_extra message",
+        args=None,
+        exc_info=None,
+        extra={"extra": "value"},
+    )
+    msg = formatter.format(record)
+    assert msg.endswith(
+        "| INFO | test_format_with_extra | test_format_with_extra message | extra=value"
+    ), f"Unexpected formatted msg: {msg}"
+
+
+def test_format_with_extra_multiple():
+    formatter: ExtraLoggingFormatter = ExtraLoggingFormatter(
+        fmt=fmt_default, datefmt=datefmt_default
+    )
+
+    logger = logging.Logger("test_format_with_extra_multiple")
+    record: LogRecord = logger.makeRecord(
+        name="test_format_with_extra_multiple",
+        level=logging.INFO,
+        fn="test_format_with_extra_multiple",
+        lno=19,
+        msg="test_format_with_extra_multiple message",
+        args=None,
+        exc_info=None,
+        extra={"extra1": "value1", "extra2": "value2"},
+    )
+    msg = formatter.format(record)
+    assert msg.endswith(
+        "| INFO | test_format_with_extra_multiple | test_format_with_extra_multiple message | extra1=value1 | extra2=value2"  # noqa: E501
+    ), f"Unexpected formatted msg: {msg}"
+
+
+def test_format_with_storage_state():
+    formatter: ExtraLoggingFormatter = ExtraLoggingFormatter(
+        fmt=fmt_default, datefmt=datefmt_default
+    )
+
+    logger = logging.Logger("test_format_with_storage_state")
+    record: LogRecord = logger.makeRecord(
+        name="test_format_with_storage_state",
+        level=logging.INFO,
+        fn="test_format_with_storage_state",
+        lno=19,
+        msg="test_format_with_storage_state message",
+        args=None,
+        exc_info=None,
+    )
+
+    LoggingStorage.get_global().add_request_id("test_format_with_storage_state_request")
+    LoggingStorage.get_global().filter(record)
+    msg = formatter.format(record)
+    LoggingStorage.get_global().reset()
+
+    assert msg.endswith(
+        "| INFO | test_format_with_storage_state | test_format_with_storage_state message | request_id=test_format_with_storage_state_request"  # noqa: E501
+    ), f"Unexpected formatted msg: {msg}"
+
+
+def test_format_with_storage_state_and_extra():
+    formatter: ExtraLoggingFormatter = ExtraLoggingFormatter(
+        fmt=fmt_default, datefmt=datefmt_default
+    )
+
+    logger = logging.Logger("test_format_with_storage_state_and_extra")
+    record: LogRecord = logger.makeRecord(
+        name="test_format_with_storage_state_and_extra",
+        level=logging.INFO,
+        fn="test_format_with_storage_state_and_extra",
+        lno=19,
+        msg="test_format_with_storage_state_and_extra message",
+        args=None,
+        exc_info=None,
+        extra={"extra": "value"},
+    )
+
+    LoggingStorage.get_global().add_request_id("test_format_with_storage_state_and_extra_request")
+    LoggingStorage.get_global().filter(record)
+    msg = formatter.format(record)
+    LoggingStorage.get_global().reset()
+
+    assert msg.endswith(
+        "| INFO | test_format_with_storage_state_and_extra | test_format_with_storage_state_and_extra message | request_id=test_format_with_storage_state_and_extra_request | extra=value"  # noqa: E501
+    ), f"Unexpected formatted msg: {msg}"

apppy/logger/parser.py

@@ -0,0 +1,54 @@
+import logging
+from typing import Any, Optional, cast
+
+
+class LogRecordParser:
+    _global_instance: Optional["LogRecordParser"] = None
+
+    def __init__(self):
+        # Standard LogRecord fields that should not be considered extra
+        self._standard_attrs = list(
+            logging.LogRecord("", 0, "", 0, "", (), None, "").__dict__.keys()
+        )
+        self._standard_attrs.append("asctime")
+        self._standard_attrs.append("message")
+        # The state field is add via LoggingStorageLoggingFilter
+        # and we handle that separately
+        self._standard_attrs.append("state")
+
+    def parse_extra_info(self, log_record: logging.LogRecord) -> dict[str, Any]:
+        """
+        Parse extra data from the given log record that is not considered
+        standard. That is, which is added at logging time. For example, for
+        the log line:
+
+        self._logger.info("My log message", extra={'user': user_id})
+
+        This method will return {'user': user_id}
+        """
+        extra_info = {
+            key: value
+            for key, value in log_record.__dict__.items()
+            if key not in self._standard_attrs
+        }
+        return extra_info
+
+    def parse_state_info(self, log_record: logging.LogRecord) -> dict[str, Any]:
+        """
+        Parse state data from the given log record that is added via LoggingStorage.
+        """
+        if hasattr(log_record, "state") and isinstance(log_record.state, dict):
+            return cast(dict[str, Any], log_record.state)
+
+        return {}
+
+    @classmethod
+    def get_global(cls) -> "LogRecordParser":
+        if cls._global_instance is None:
+            raise RuntimeError("LogRecordParser has not been initialized.")
+        return cls._global_instance
+
+    @classmethod
+    def set_global(cls) -> None:
+        if cls._global_instance is None:
+            cls._global_instance = LogRecordParser()

apppy/logger/storage.py

@@ -0,0 +1,65 @@
+import contextvars
+import logging
+from typing import Any, Literal, Optional
+
+LoggingStorageKey = Literal["request_id"]
+
+# Define a context variable per key
+_global_logging_vars: dict[str, contextvars.ContextVar[Any | None]] = {
+    "request_id": contextvars.ContextVar("request_id", default=None),
+}
+
+
+class LoggingStorage(logging.Filter):
+    _global_instance: Optional["LoggingStorage"] = None
+
+    def add_request_id(self, request_id: str) -> str:
+        _global_logging_vars["request_id"].set(request_id)
+        return request_id
+
+    def filter(self, record: logging.LogRecord) -> bool:
+        stored_state = self.read_all()
+        if hasattr(record, "state") and isinstance(record.state, dict):
+            record.state.update(stored_state)  # type: ignore[invalid-assignment]
+        else:
+            record.state = stored_state
+
+        return True
+
+    def read(self, key: LoggingStorageKey) -> Any | None:
+        return _global_logging_vars[key].get()
+
+    def read_all(self) -> dict[str, Any]:
+        return {
+            key: value
+            for key in _global_logging_vars
+            if (value := _global_logging_vars[key].get()) is not None
+        }
+
+    def reset(self):
+        # contextvars can't be "deleted", so just reset to None
+        for key in _global_logging_vars:
+            _global_logging_vars[key].set(None)
+
+    @classmethod
+    def get_global(cls) -> "LoggingStorage":
+        if cls._global_instance is None:
+            raise RuntimeError("LoggingStorage has not been initialized.")
+        return cls._global_instance
+
+    @classmethod
+    def set_global(cls) -> None:
+        if cls._global_instance is None:
+            cls._global_instance = LoggingStorage()
+
+    @staticmethod
+    def apply(logger: logging.Logger):
+        logger.addFilter(LoggingStorage.get_global())
+
+    @staticmethod
+    def apply_all():
+        logger_dict = logging.Logger.manager.loggerDict
+        for logger_name in logger_dict:
+            logger = logger_dict.get(logger_name)
+            if isinstance(logger, logging.Logger):
+                LoggingStorage.apply(logger)

apppy_logger-0.15.1.dist-info/METADATA

@@ -0,0 +1,10 @@
+Metadata-Version: 2.4
+Name: apppy-logger
+Version: 0.15.1
+Summary: Python logger extensions for server development
+Project-URL: Homepage, https://github.com/spals/apppy
+Author: Tim Kral
+License: MIT
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.11

apppy_logger-0.15.1.dist-info/RECORD

@@ -0,0 +1,9 @@
+apppy/logger/__init__.py,sha256=x7m4v_p5bK0etKD8QcLEdiAVZk2z-Vr_ZdW2B2uA1Ls,2658
+apppy/logger/filter.py,sha256=2FTt_ADwc2phniY541_xKX1zR6K8BY3kCFRdJ5FEoBI,509
+apppy/logger/format.py,sha256=JTOJBDzWQzA4axacseibjDAGA0wQspd7byvK-kHH-34,2257
+apppy/logger/format_unit_test.py,sha256=51Jhr8mzaFxvEC0tCdkUP5V-noefDI4fR0jH8FQSnBA,4411
+apppy/logger/parser.py,sha256=QmGm7eaH3lORot8PbAB5Bee_tyHvgC8i80JL_3P4VRc,1898
+apppy/logger/storage.py,sha256=HJ3oYzknBAq7GR7tCrkD18lrP3IEprLMkXJIGIbMirI,2103
+apppy_logger-0.15.1.dist-info/METADATA,sha256=h-5tJ0DAhxIOfmYHXrPEIPbHLVK--AIGllgAqcQKhMg,321
+apppy_logger-0.15.1.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+apppy_logger-0.15.1.dist-info/RECORD,,

apppy_logger-0.15.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any