csrd-logging 0.1.0__tar.gz

csrd_logging-0.1.0/.gitignore

@@ -0,0 +1,217 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+#poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+#pdm.lock
+#pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+#pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+/env/
+/venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Abstra
+# Abstra is an AI-powered process automation framework.
+# Ignore directories containing user credentials, local state, and settings.
+# Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore
+#  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#  and can be added to the global gitignore or merged into this file. However, if you prefer,
+#  you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Cursor
+#  Cursor is an AI-powered code editor. `.cursorignore` specifies files/directories to
+#  exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
+#  refer to https://docs.cursor.com/context/ignore-files
+.cursorignore
+.cursorindexingignore
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+*.db
+
+
+# Import linter cache
+.import_linter_cache/
+
+# IDE
+.idea/
+.idea/*

csrd_logging-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,154 @@
+# csrd.logging
+
+Context-enriched logging for all application layers.
+
+## Dependency tier
+
+```
+Tier 1        csrd.models · csrd.lifespan · csrd.context
+Tier 1.5      csrd.logging  ← depends on csrd.context only
+Tier 2        csrd.delegate · csrd.repository · csrd.service
+Tier 3        csrd.versioning
+```
+
+## Components
+
+### `ContextLogger`
+
+A stdlib `Logger` wrapper that auto-enriches every message with request context (`hit_id`, `user_id`, path params) as `key=value` pairs.
+
+```python
+from csrd.logging import ContextLogger
+
+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"
+```
+
+All standard logging kwargs (`exc_info`, `extra`, `stacklevel`) pass through. The `meta` kwarg adds extra key=value pairs per call.
+
+### `LoggingMixin`
+
+A mixin providing `self.log` (a `ContextLogger`) for any class. Works at every layer.
+
+```python
+from csrd.logging import LoggingMixin
+
+class OrderService(BaseService, LoggingMixin):
+    async def place_order(self, cart):
+        self.log.info("Placing order", meta={"items": len(cart)})
+```
+
+#### Auto-logging (opt-in)
+
+Pass `auto_log=True` to automatically log entry and exceptions for every public method:
+
+```python
+class OrderService(BaseService, LoggingMixin, auto_log=True):
+    async def place_order(self, cart):  # ← entry logged at INFO, exceptions at ERROR
+        ...
+```
+
+Exclude noisy methods:
+
+```python
+class MyService(BaseService, LoggingMixin, auto_log=True):
+    __log_exclude__ = {"health_check"}
+```
+
+Both sync and async methods are handled. Private methods (`_name`) are always skipped.
+
+### `RequestContextFilter`
+
+A stdlib `logging.Filter` that injects context fields into log **records** (not messages). Use this when your logging backend (Splunk, ELK, Datadog) needs structured fields in a configurable format.
+
+Fields added to each record:
+
+| Field | Source | Default |
+|-------|--------|---------|
+| `hit_id` | Request trace ID | `"-"` |
+| `user_id` | Authenticated user's `sub` claim | `"-"` |
+| `app_id` | Application identifier header | `"-"` |
+| `api_version` | Resolved API version | `"-"` |
+
+## Production logging configuration
+
+`ContextLogger` enriches log **messages** — it works out of the box with zero configuration. For production deployments you'll typically also want to configure stdlib logging with structured formatters, handlers, and filters.
+
+### Approach 1: `ContextLogger` only (simplest)
+
+No configuration needed. Messages include context automatically:
+
+```
+2025-07-15 10:23:45 INFO  Order created hit_id=abc-123 user_id=user1 order_id=42
+```
+
+Good for development and simple deployments.
+
+### Approach 2: YAML logging configuration (production)
+
+Create a `config/logging.yml` in your application:
+
+```yaml
+version: 1
+disable_existing_loggers: false
+
+formatters:
+  structured:
+    style: "{"
+    format: "{asctime} hitId={hit_id} userId={user_id} module={name} func={funcName} level={levelname} {message}"
+
+filters:
+  context:
+    "()": csrd.logging.RequestContextFilter
+
+handlers:
+  console:
+    class: logging.StreamHandler
+    level: INFO
+    formatter: structured
+    stream: ext://sys.stdout
+    filters: [context]
+
+loggers:
+  uvicorn:
+    handlers: [console]
+    level: INFO
+    propagate: false
+  uvicorn.access:
+    handlers: [console]
+    level: INFO
+    propagate: false
+  root:
+    level: INFO
+    handlers: [console]
+```
+
+Load it at startup:
+
+```python
+import logging.config
+import yaml
+from pathlib import Path
+
+with open(Path("config/logging.yml")) as f:
+    logging.config.dictConfig(yaml.safe_load(f))
+```
+
+### Approach 3: Both together (recommended for production)
+
+Use `ContextLogger` / `LoggingMixin` in your code for dev-friendly messages, **and** attach `RequestContextFilter` to your production handlers for structured logging backends. The two are complementary — `ContextLogger` enriches the message text, `RequestContextFilter` adds record-level fields for formatters.
+
+### When to use which
+
+| Approach | Context in logs | Config required | Best for |
+|----------|----------------|-----------------|----------|
+| `ContextLogger` | In message text (`key=value`) | None | Dev, simple apps |
+| `logging.yml` + `RequestContextFilter` | In log record fields | YAML file | Splunk, ELK, structured logging |
+| Both together | Both | YAML file | Full production setup |
+
+## Installation
+
+```bash
+uv add csrd-logging
+```

csrd_logging-0.1.0/pyproject.toml

@@ -0,0 +1,24 @@
+[project]
+name = "csrd-logging"
+version = "0.1.0"
+description = "Context-enriched logging mixin with optional auto-instrumentation"
+license = { text = "MIT" }
+requires-python = ">=3.12"
+dependencies = [
+    "csrd-context",
+]
+
+[tool.uv.sources]
+csrd-context = { workspace = true }
+
+[project.urls]
+Repository = "https://github.com/csrd-api/fastapi-common"
+Documentation = "https://github.com/csrd-api/fastapi-common/tree/main/packages/logging"
+Changelog = "https://github.com/csrd-api/fastapi-common/blob/main/CHANGELOG.md"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/csrd"]

csrd_logging-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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/tests/test_logging.py

@@ -0,0 +1,323 @@
+"""Tests for csrd.logging — ContextLogger and LoggingMixin."""
+
+import logging
+from typing import ClassVar
+
+import pytest
+
+from csrd.context._contextvars import reset_global_configuration
+from csrd.context.platform import hit_id_context, user_info_context
+from csrd.logging import ContextLogger, LoggingMixin, RequestContextFilter
+
+
+@pytest.fixture(autouse=True)
+def _clean_context():
+    """Reset context vars around each test."""
+    hit_token = hit_id_context.set("unknown")
+    user_token = user_info_context.set(None)
+    yield
+    hit_id_context.reset(hit_token)
+    user_info_context.reset(user_token)
+    reset_global_configuration()
+
+
+# ── ContextLogger ────────────────────────────────────────────────────────
+
+
+class TestContextLogger:
+    def test_plain_message(self, caplog):
+        logger = ContextLogger(logging.getLogger("test.plain"))
+        with caplog.at_level(logging.INFO, logger="test.plain"):
+            logger.info("hello world")
+        assert "hello world" in caplog.text
+
+    def test_message_with_meta(self, caplog):
+        logger = ContextLogger(logging.getLogger("test.meta"))
+        with caplog.at_level(logging.INFO, logger="test.meta"):
+            logger.info("order created", meta={"order_id": 42})
+        assert "order created" in caplog.text
+        assert "order_id=42" in caplog.text
+
+    def test_enriched_with_hit_id(self, caplog):
+        hit_id_context.set("req-abc-123")
+        logger = ContextLogger(logging.getLogger("test.hit"))
+        with caplog.at_level(logging.INFO, logger="test.hit"):
+            logger.info("processing")
+        assert "hit_id=req-abc-123" in caplog.text
+
+    def test_enriched_with_user_id(self, caplog):
+        class FakeClaims:
+            sub = "user42"
+
+        user_info_context.set(FakeClaims())
+        logger = ContextLogger(logging.getLogger("test.user"))
+        with caplog.at_level(logging.INFO, logger="test.user"):
+            logger.info("action")
+        assert "user_id=user42" in caplog.text
+
+    def test_no_context_no_extras(self, caplog):
+        logger = ContextLogger(logging.getLogger("test.empty"))
+        with caplog.at_level(logging.INFO, logger="test.empty"):
+            logger.info("bare")
+        # Should just be the message, no key=value pairs
+        assert caplog.records[0].message == "bare"
+
+    def test_all_levels(self, caplog):
+        logger = ContextLogger(logging.getLogger("test.levels"))
+        with caplog.at_level(logging.DEBUG, logger="test.levels"):
+            logger.debug("d")
+            logger.info("i")
+            logger.warning("w")
+            logger.error("e")
+        level_records = [r for r in caplog.records if r.name == "test.levels"]
+        assert len(level_records) == 4
+
+    def test_exception_level(self, caplog):
+        logger = ContextLogger(logging.getLogger("test.exc"))
+        with caplog.at_level(logging.ERROR, logger="test.exc"):
+            try:
+                raise ValueError("boom")
+            except ValueError:
+                logger.exception("caught it")
+        assert "caught it" in caplog.text
+
+    def test_stdlib_logger_accessible(self):
+        stdlib = logging.getLogger("test.stdlib")
+        ctx = ContextLogger(stdlib)
+        assert ctx.stdlib_logger is stdlib
+
+
+# ── LoggingMixin ─────────────────────────────────────────────────────────
+
+
+class TestLoggingMixin:
+    def test_log_property_returns_context_logger(self):
+        class MyClass(LoggingMixin):
+            pass
+
+        obj = MyClass()
+        assert isinstance(obj.log, ContextLogger)
+
+    def test_log_property_cached(self):
+        class MyClass(LoggingMixin):
+            pass
+
+        obj = MyClass()
+        assert obj.log is obj.log
+
+    def test_logger_name_includes_class(self):
+        class OrderService(LoggingMixin):
+            pass
+
+        obj = OrderService()
+        assert "OrderService" in obj.log.stdlib_logger.name
+
+    def test_manual_logging(self, caplog):
+        class MyService(LoggingMixin):
+            def do_work(self):
+                self.log.info("doing work", meta={"item": 5})
+
+        svc = MyService()
+        with caplog.at_level(logging.INFO):
+            svc.do_work()
+        assert "doing work" in caplog.text
+        assert "item=5" in caplog.text
+
+
+# ── Auto-logging ─────────────────────────────────────────────────────────
+
+
+class TestAutoLogging:
+    def test_sync_method_logged(self, caplog):
+        class Svc(LoggingMixin, auto_log=True):
+            def process(self):
+                return "done"
+
+        svc = Svc()
+        with caplog.at_level(logging.INFO):
+            result = svc.process()
+        assert result == "done"
+        assert "process" in caplog.text
+
+    @pytest.mark.asyncio
+    async def test_async_method_logged(self, caplog):
+        class Svc(LoggingMixin, auto_log=True):
+            async def fetch(self):
+                return 42
+
+        svc = Svc()
+        with caplog.at_level(logging.INFO):
+            result = await svc.fetch()
+        assert result == 42
+        assert "fetch" in caplog.text
+
+    def test_private_methods_skipped(self, caplog):
+        class Svc(LoggingMixin, auto_log=True):
+            def _internal(self):
+                return "private"
+
+            def public(self):
+                return "public"
+
+        svc = Svc()
+        with caplog.at_level(logging.INFO):
+            svc._internal()
+            caplog.clear()
+            svc.public()
+        assert "public" in caplog.text
+
+    def test_excluded_methods_skipped(self, caplog):
+        class Svc(LoggingMixin, auto_log=True):
+            __log_exclude__: ClassVar[set[str]] = {"health_check"}
+
+            def health_check(self):
+                return "ok"
+
+            def process(self):
+                return "done"
+
+        svc = Svc()
+        with caplog.at_level(logging.INFO):
+            svc.health_check()
+        assert "health_check" not in caplog.text
+
+    def test_exception_logged(self, caplog):
+        class Svc(LoggingMixin, auto_log=True):
+            def fail(self):
+                raise ValueError("boom")
+
+        svc = Svc()
+        with caplog.at_level(logging.ERROR), pytest.raises(ValueError, match="boom"):
+            svc.fail()
+        assert "fail failed" in caplog.text
+
+    @pytest.mark.asyncio
+    async def test_async_exception_logged(self, caplog):
+        class Svc(LoggingMixin, auto_log=True):
+            async def fail(self):
+                raise RuntimeError("async boom")
+
+        svc = Svc()
+        with caplog.at_level(logging.ERROR), pytest.raises(RuntimeError, match="async boom"):
+            await svc.fail()
+        assert "fail failed" in caplog.text
+
+    def test_no_auto_log_by_default(self, caplog):
+        class Svc(LoggingMixin):
+            def process(self):
+                return "done"
+
+        svc = Svc()
+        with caplog.at_level(logging.INFO):
+            svc.process()
+        # No auto entry log
+        assert "process" not in caplog.text
+
+    def test_context_enrichment_in_auto_log(self, caplog):
+        hit_id_context.set("trace-xyz")
+
+        class Svc(LoggingMixin, auto_log=True):
+            def work(self):
+                return True
+
+        svc = Svc()
+        with caplog.at_level(logging.INFO):
+            svc.work()
+        assert "hit_id=trace-xyz" in caplog.text
+
+    def test_excludes_inherited(self, caplog):
+        class Base(LoggingMixin, auto_log=True):
+            __log_exclude__: ClassVar[set[str]] = {"noisy"}
+
+        class Child(Base, auto_log=True):
+            __log_exclude__: ClassVar[set[str]] = {"also_noisy"}
+
+            def noisy(self):
+                return "n"
+
+            def also_noisy(self):
+                return "an"
+
+            def normal(self):
+                return "ok"
+
+        svc = Child()
+        with caplog.at_level(logging.INFO):
+            svc.noisy()
+            svc.also_noisy()
+        assert "noisy" not in caplog.text
+        assert "also_noisy" not in caplog.text
+
+
+# ── RequestContextFilter ─────────────────────────────────────────────────
+
+
+class TestRequestContextFilter:
+    def _make_handler_with_filter(
+        self, formatter_str: str
+    ) -> tuple[logging.Logger, logging.Handler]:
+        """Create a logger with a handler that uses RequestContextFilter."""
+        logger = logging.getLogger(f"test.filter.{id(self)}")
+        logger.setLevel(logging.DEBUG)
+        handler = logging.StreamHandler()
+        handler.addFilter(RequestContextFilter())
+        handler.setFormatter(logging.Formatter(formatter_str))
+        logger.addHandler(handler)
+        return logger, handler
+
+    def test_adds_hit_id_to_record(self, caplog):
+        hit_id_context.set("trace-999")
+        f = RequestContextFilter()
+        record = logging.LogRecord("test", logging.INFO, "", 0, "msg", (), None)
+        f.filter(record)
+        assert record.hit_id == "trace-999"  # type: ignore[attr-defined]
+
+    def test_adds_user_id_to_record(self):
+        class FakeClaims:
+            sub = "alice"
+
+        user_info_context.set(FakeClaims())
+        f = RequestContextFilter()
+        record = logging.LogRecord("test", logging.INFO, "", 0, "msg", (), None)
+        f.filter(record)
+        assert record.user_id == "alice"  # type: ignore[attr-defined]
+
+    def test_defaults_to_dash_when_no_context(self):
+        f = RequestContextFilter()
+        record = logging.LogRecord("test", logging.INFO, "", 0, "msg", (), None)
+        f.filter(record)
+        assert record.hit_id == "-"  # type: ignore[attr-defined]
+        assert record.user_id == "-"  # type: ignore[attr-defined]
+        assert record.app_id == "-"  # type: ignore[attr-defined]
+        assert record.api_version == "-"  # type: ignore[attr-defined]
+
+    def test_always_returns_true(self):
+        f = RequestContextFilter()
+        record = logging.LogRecord("test", logging.INFO, "", 0, "msg", (), None)
+        assert f.filter(record) is True
+
+    def test_works_with_formatter(self, caplog):
+        hit_id_context.set("req-abc")
+
+        class FakeClaims:
+            sub = "bob"
+
+        user_info_context.set(FakeClaims())
+
+        logger = logging.getLogger("test.filter.fmt")
+        logger.handlers.clear()
+        logger.setLevel(logging.INFO)
+
+        handler = logging.StreamHandler()
+        handler.addFilter(RequestContextFilter())
+        fmt = logging.Formatter("%(message)s hit_id=%(hit_id)s user_id=%(user_id)s")
+        handler.setFormatter(fmt)
+        logger.addHandler(handler)
+
+        with caplog.at_level(logging.INFO, logger="test.filter.fmt"):
+            logger.info("hello")
+
+        # The caplog records should have the filter-injected attributes
+        record = next(r for r in caplog.records if r.name == "test.filter.fmt")
+        assert record.hit_id == "req-abc"  # type: ignore[attr-defined]
+        assert record.user_id == "bob"  # type: ignore[attr-defined]