Add structured logging and API_LOG_PATH

Emit JSON log lines to stdout and optionally to a file via API_LOG_PATH.
Wire uvicorn logs to the same handlers.
Add a basic log file test and update README.

Author: matthewhorridge

README.md

@@ -45,8 +45,8 @@ Graceful shutdown is supported via:
 POST http://127.0.0.1:54321/shutdown/
 ```
 
-Logs are written to stdout/stderr. Optionally, set `API_LOG_PATH` to also write
-logs to a file (if/when this is enabled).
+Logs are written to stdout/stderr as JSON lines. Optionally, set `API_LOG_PATH`
+to also write logs to a file.
 
 ### Sidecar packaging (CI)
 

src/harmonization_framework/api/sidecar.py

@@ -7,8 +7,10 @@
 
 import os
 import sys
+import json
 import logging
-from typing import Optional
+from datetime import datetime, timezone
+from typing import Optional, List
 
 import uvicorn
 
@@ -17,6 +19,7 @@
 DEFAULT_HOST = "127.0.0.1"
 ENV_PORT = "API_PORT"
 ENV_HOST = "API_HOST"
+ENV_LOG_PATH = "API_LOG_PATH"
 
 
 def _parse_port(value: str) -> int:
@@ -37,6 +40,51 @@ def _resolve_host(value: Optional[str]) -> str:
     return "127.0.0.1" if host == "localhost" else host
 
 
+class _JsonLogFormatter(logging.Formatter):
+    """Format log records as compact JSON lines for stdout/stderr capture."""
+    def format(self, record: logging.LogRecord) -> str:
+        payload = {
+            "ts": datetime.fromtimestamp(record.created, tz=timezone.utc).isoformat(),
+            "level": record.levelname,
+            "logger": record.name,
+            "message": record.getMessage(),
+        }
+        return json.dumps(payload, separators=(",", ":"))
+
+
+def _configure_logging(log_path: Optional[str]) -> List[logging.Handler]:
+    """
+    Configure structured logging to stdout and optionally to a log file.
+    """
+    formatter = _JsonLogFormatter()
+    handlers: List[logging.Handler] = []
+
+    stream_handler = logging.StreamHandler(stream=sys.stdout)
+    stream_handler.setFormatter(formatter)
+    handlers.append(stream_handler)
+
+    if log_path:
+        try:
+            file_handler = logging.FileHandler(log_path)
+        except OSError as exc:
+            raise ValueError(f"{ENV_LOG_PATH} is not writable: {log_path}") from exc
+        file_handler.setFormatter(formatter)
+        handlers.append(file_handler)
+
+    root_logger = logging.getLogger()
+    root_logger.setLevel(logging.INFO)
+    root_logger.handlers = handlers
+
+    # Ensure uvicorn loggers use the same handlers/format.
+    for logger_name in ("uvicorn.error", "uvicorn.access"):
+        logger = logging.getLogger(logger_name)
+        logger.handlers = handlers
+        logger.setLevel(logging.INFO)
+        logger.propagate = False
+
+    return handlers
+
+
 def main() -> None:
     """
     Start the FastAPI sidecar using environment configuration.
@@ -46,7 +94,12 @@ def main() -> None:
     Optional:
         API_HOST: host to bind, defaults to 127.0.0.1.
     """
-    logging.basicConfig(level=logging.INFO, format="%(message)s")
+    log_path = os.getenv(ENV_LOG_PATH)
+    try:
+        _configure_logging(log_path)
+    except ValueError as exc:
+        logging.error(str(exc))
+        sys.exit(2)
 
     port_raw = os.getenv(ENV_PORT)
     if not port_raw:

tests/test_sidecar_config.py

@@ -1,7 +1,7 @@
 import pytest
 
 from harmonization_framework.api import sidecar
-from harmonization_framework.api.sidecar import _parse_port, _resolve_host
+from harmonization_framework.api.sidecar import _parse_port, _resolve_host, _configure_logging
 
 
 def test_parse_port_accepts_valid_range():
@@ -77,3 +77,10 @@ def fake_run(app, host, port, log_level):
     sidecar.main()
 
     assert calls == {"host": "127.0.0.1", "port": 54321, "log_level": "info"}
+
+
+def test_configure_logging_with_file(tmp_path):
+    log_path = tmp_path / "sidecar.log"
+    handlers = _configure_logging(str(log_path))
+    assert len(handlers) == 2
+    assert log_path.exists()