feat: add logger

common/src/common/config.py

@@ -60,6 +60,15 @@ class Settings(BaseSettings):
         description="Service label surfaced in lifespan / health checks.",
     )
 
+    # ── logging ───────────────────────────────────────────────────
+    log_level: str = Field(
+        default="DEBUG",
+        description=(
+            "loguru stderr sink level. One of DEBUG/INFO/WARNING/ERROR/CRITICAL; "
+            "anything else falls back to INFO inside configure_logging()."
+        ),
+    )
+
     # ── runtime container endpoint ───────────────────────────────
     runtime_api_url: str = Field(
         default="http://runtime:8000",

common/src/common/logging.py

@@ -0,0 +1,39 @@
+"""Centralised loguru configuration. Call :func:`configure_logging` once per process, as early as possible. Idempotent."""
+
+from __future__ import annotations
+
+import sys
+
+from loguru import logger
+
+_DEFAULT_FORMAT = (
+    "<green>{time:YYYY-MM-DD HH:mm:ss.SSS}</green> "
+    "<level>{level: <8}</level> | "
+    "<cyan>{name}</cyan>:<cyan>{function}</cyan>:<cyan>{line}</cyan> - "
+    "<level>{message}</level>"
+)
+_ALLOWED_LEVELS = {"DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"}
+_CONFIGURED: bool = False
+
+
+def configure_logging(level: str = "INFO") -> str:
+    """Configure loguru's default stderr sink and return the normalised level."""
+    global _CONFIGURED
+    if _CONFIGURED:
+        return level.upper()
+
+    normalised = level.upper() if level.upper() in _ALLOWED_LEVELS else "INFO"
+
+    logger.remove()
+    logger.add(
+        sys.stderr,
+        level=normalised,
+        format=_DEFAULT_FORMAT,
+        backtrace=True,
+        diagnose=False,
+        enqueue=False,
+        catch=True,
+    )
+
+    _CONFIGURED = True
+    return normalised