csrd-logging 0.1.0__py3-none-any.whl

csrd/logging/__init__.py

@@ -0,0 +1,20 @@
+"""Context-enriched logging for all application layers.
+
+Provides :class:`ContextLogger` (a stdlib ``Logger`` wrapper that
+auto-enriches messages with request context), :class:`LoggingMixin`
+(a mixin with optional auto-instrumentation of public methods), and
+:class:`RequestContextFilter` (a stdlib ``logging.Filter`` for
+production formatters).
+
+Usable at any tier — services, delegates, repositories::
+
+    from csrd.logging import LoggingMixin
+
+    class OrderService(BaseService, LoggingMixin, auto_log=True):
+        ...
+"""
+
+from ._filter import RequestContextFilter
+from ._logging import ContextLogger, LoggingMixin
+
+__all__ = ("ContextLogger", "LoggingMixin", "RequestContextFilter")

csrd/logging/_filter.py

@@ -0,0 +1,62 @@
+"""Stdlib ``logging.Filter`` that injects request context into log records.
+
+Attach this filter to any handler (typically via ``logging.yml``) to make
+context fields available to formatters::
+
+    filters:
+      context:
+        "()": csrd.logging.RequestContextFilter
+
+    formatters:
+      structured:
+        style: "{"
+        format: "{asctime} hitId={hit_id} userId={user_id} level={levelname} {message}"
+
+Fields added to each record:
+
+* ``hit_id`` — request trace ID from ``csrd.context``
+* ``user_id`` — authenticated user's ``sub`` claim
+* ``app_id`` — application identifier header
+* ``api_version`` — resolved API version for the request
+"""
+
+from __future__ import annotations
+
+import logging
+
+from csrd.context import get_api_version, get_app_id
+from csrd.context.platform import hit_id_context, user_info_context
+
+
+class RequestContextFilter(logging.Filter):
+    """Injects request context fields into every log record.
+
+    Unknown/unavailable fields default to ``"-"`` so formatters never
+    raise ``KeyError``.
+    """
+
+    _FALLBACK = "-"
+
+    def filter(self, record: logging.LogRecord) -> bool:
+        record.hit_id = self._get_hit_id()  # type: ignore[attr-defined]
+        record.user_id = self._get_user_id()  # type: ignore[attr-defined]
+        record.app_id = get_app_id() or self._FALLBACK  # type: ignore[attr-defined]
+        record.api_version = get_api_version() or self._FALLBACK  # type: ignore[attr-defined]
+        return True
+
+    @staticmethod
+    def _get_hit_id() -> str:
+        val = hit_id_context.get()
+        return val if val and val != "unknown" else "-"
+
+    @staticmethod
+    def _get_user_id() -> str:
+        user = user_info_context.get()
+        if user is not None:
+            sub = getattr(user, "sub", None)
+            if sub:
+                return str(sub)
+        return "-"
+
+
+__all__ = ("RequestContextFilter",)

csrd/logging/_logging.py

@@ -0,0 +1,209 @@
+"""Context-enriched logging mixin and logger facade.
+
+``LoggingMixin`` and ``ContextLogger`` provide structured, context-aware
+logging for any layer of the application (services, delegates, repositories).
+
+``ContextLogger`` wraps a stdlib :class:`logging.Logger` and automatically
+enriches every log message with available request context (``hit_id``,
+``user_id``, path params) formatted as ``key=value`` pairs.
+
+``LoggingMixin`` is a mixin class that provides a ``self.log`` property
+returning a ``ContextLogger``.  Subclasses can opt into **auto-logging**
+of all public methods via ``__init_subclass__``::
+
+    class OrderService(BaseService, LoggingMixin, auto_log=True):
+        async def place_order(self, cart: Cart) -> Order:
+            # entry + exception logging happens automatically
+            ...
+
+    class QuietService(BaseService, LoggingMixin):
+        def do_work(self):
+            self.log.info("manual log", meta={"item": 42})
+"""
+
+from __future__ import annotations
+
+import asyncio
+import functools
+import inspect
+import logging
+from typing import Any, ClassVar
+
+from csrd.context import get_path_params
+from csrd.context.platform import hit_id_context, user_info_context
+
+
+def _collect_context() -> dict[str, Any]:
+    """Gather available request context as a flat dict."""
+    ctx: dict[str, Any] = {}
+
+    hit_id = hit_id_context.get()
+    if hit_id and hit_id != "unknown":
+        ctx["hit_id"] = hit_id
+
+    user = user_info_context.get()
+    if user is not None:
+        sub = getattr(user, "sub", None)
+        if sub:
+            ctx["user_id"] = sub
+
+    path_params = get_path_params()
+    if path_params:
+        ctx.update(path_params)
+
+    return ctx
+
+
+def _format_message(message: str, meta: dict[str, Any] | None = None) -> str:
+    """Format a message with context and optional meta as key=value pairs."""
+    parts: dict[str, Any] = {}
+    parts.update(_collect_context())
+    if meta:
+        parts.update(meta)
+
+    if not parts:
+        return message
+
+    kv = " ".join(f"{k}={v}" for k, v in parts.items())
+    return f"{message} {kv}"
+
+
+class ContextLogger:
+    """Wraps a stdlib ``Logger`` — auto-enriches messages with request context.
+
+    Usage::
+
+        logger = ContextLogger(logging.getLogger(__name__))
+        logger.info("Order created", meta={"order_id": 42})
+        # → "Order created hit_id=abc-123 user_id=user1 order_id=42"
+    """
+
+    __slots__ = ("_logger",)
+
+    def __init__(self, logger: logging.Logger) -> None:
+        self._logger = logger
+
+    @property
+    def stdlib_logger(self) -> logging.Logger:
+        """Access the underlying stdlib logger directly."""
+        return self._logger
+
+    def info(
+        self, message: str, *args: Any, meta: dict[str, Any] | None = None, **kwargs: Any
+    ) -> None:
+        kwargs.setdefault("stacklevel", 2)
+        self._logger.info(_format_message(message, meta), *args, **kwargs)
+
+    def error(
+        self, message: str, *args: Any, meta: dict[str, Any] | None = None, **kwargs: Any
+    ) -> None:
+        kwargs.setdefault("stacklevel", 2)
+        self._logger.error(_format_message(message, meta), *args, **kwargs)
+
+    def warning(
+        self, message: str, *args: Any, meta: dict[str, Any] | None = None, **kwargs: Any
+    ) -> None:
+        kwargs.setdefault("stacklevel", 2)
+        self._logger.warning(_format_message(message, meta), *args, **kwargs)
+
+    def debug(
+        self, message: str, *args: Any, meta: dict[str, Any] | None = None, **kwargs: Any
+    ) -> None:
+        kwargs.setdefault("stacklevel", 2)
+        self._logger.debug(_format_message(message, meta), *args, **kwargs)
+
+    def exception(
+        self, message: str, *args: Any, meta: dict[str, Any] | None = None, **kwargs: Any
+    ) -> None:
+        kwargs.setdefault("stacklevel", 2)
+        self._logger.exception(_format_message(message, meta), *args, **kwargs)
+
+
+class LoggingMixin:
+    """Mixin that provides a context-enriched :class:`ContextLogger`.
+
+    Compose with any base class::
+
+        class MyService(BaseService, LoggingMixin):
+            ...
+
+        class MyDelegate(BaseDelegate, LoggingMixin):
+            ...
+
+    **Auto-logging** (opt-in): decorate all public methods with entry/exception
+    logging automatically::
+
+        class MyService(BaseService, LoggingMixin, auto_log=True):
+            __log_exclude__ = {"health_check"}   # skip noisy methods
+            ...
+    """
+
+    __log_exclude__: ClassVar[set[str]] = set()
+
+    _context_logger: ContextLogger
+
+    def __init_subclass__(cls, auto_log: bool = False, **kwargs: Any) -> None:
+        super().__init_subclass__(**kwargs)
+        if not auto_log:
+            return
+
+        # Collect excludes from the full MRO
+        excludes: set[str] = set()
+        for klass in cls.__mro__:
+            excludes |= getattr(klass, "__log_exclude__", set())
+
+        logger = logging.getLogger(f"{cls.__module__}.{cls.__qualname__}")
+
+        for attr_name, attr_value in list(cls.__dict__.items()):
+            if attr_name.startswith("_") or attr_name in excludes or not callable(attr_value):
+                continue
+
+            if asyncio.iscoroutinefunction(attr_value):
+                setattr(cls, attr_name, _wrap_async(logger, attr_name, attr_value))
+            elif inspect.isfunction(attr_value):
+                setattr(cls, attr_name, _wrap_sync(logger, attr_name, attr_value))
+
+    @property
+    def log(self) -> ContextLogger:
+        """Context-enriched logger for this instance."""
+        try:
+            return self._context_logger
+        except AttributeError:
+            name = f"{self.__class__.__module__}.{self.__class__.__qualname__}"
+            self._context_logger = ContextLogger(logging.getLogger(name))
+            return self._context_logger
+
+
+def _wrap_async(logger: logging.Logger, method_name: str, fn: Any) -> Any:
+    @functools.wraps(fn)
+    async def wrapper(*args: Any, **kwargs: Any) -> Any:
+        logger.info(_format_message(method_name), stacklevel=2)
+        try:
+            return await fn(*args, **kwargs)
+        except Exception:
+            logger.exception(
+                _format_message(f"{method_name} failed"),
+                stacklevel=2,
+            )
+            raise
+
+    return wrapper
+
+
+def _wrap_sync(logger: logging.Logger, method_name: str, fn: Any) -> Any:
+    @functools.wraps(fn)
+    def wrapper(*args: Any, **kwargs: Any) -> Any:
+        logger.info(_format_message(method_name), stacklevel=2)
+        try:
+            return fn(*args, **kwargs)
+        except Exception:
+            logger.exception(
+                _format_message(f"{method_name} failed"),
+                stacklevel=2,
+            )
+            raise
+
+    return wrapper
+
+
+__all__ = ("ContextLogger", "LoggingMixin")

csrd_logging-0.1.0.dist-info/METADATA

@@ -0,0 +1,10 @@
+Metadata-Version: 2.4
+Name: csrd-logging
+Version: 0.1.0
+Summary: Context-enriched logging mixin with optional auto-instrumentation
+Project-URL: Repository, https://github.com/csrd-api/fastapi-common
+Project-URL: Documentation, https://github.com/csrd-api/fastapi-common/tree/main/packages/logging
+Project-URL: Changelog, https://github.com/csrd-api/fastapi-common/blob/main/CHANGELOG.md
+License: MIT
+Requires-Python: >=3.12
+Requires-Dist: csrd-context

csrd_logging-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+csrd/logging/__init__.py,sha256=n66-lxe4Y5xkYHq17ZWTlqw4RAYH3qcIVZ01VgfMv4U,694
+csrd/logging/_filter.py,sha256=tNQIlgW1pM1DorkldoutLuo2CRNK8V_OsA2NiMekTdk,1884
+csrd/logging/_logging.py,sha256=0ORuq9D5-u5gie24NEemOfXAzcshAPfXdh56P-EQP2A,6756
+csrd/logging/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+csrd_logging-0.1.0.dist-info/METADATA,sha256=ZaIqKoLmZ0PKVmVWrPD3WgRgeffEKBLX2GRrJakOegg,452
+csrd_logging-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+csrd_logging-0.1.0.dist-info/RECORD,,

csrd_logging-0.1.0.dist-info/WHEEL

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