feat(logging): add configurable log level via LIGHTSPEED_STACK_LOG_LEVEL env var

This commit introduces runtime-configurable logging via the LIGHTSPEED_STACK_LOG_LEVEL environment variable, allowing deployment-time control of log verbosity without code changes.

Key changes:
- Added LIGHTSPEED_STACK_LOG_LEVEL_ENV_VAR and DEFAULT_LOG_LEVEL constants
- Modified get_logger() to read log level from environment with defensive validation
- Updated lightspeed_stack.py basicConfig() to respect the environment variable
- Added force=True to basicConfig() to override llama_stack_client's early logging setup
- Revived --verbose CLI flag to set DEBUG level and update all existing loggers
- Added comprehensive unit tests covering default, custom, case-insensitive, invalid, and all valid log levels

The --verbose flag now provides a convenient CLI shortcut for enabling debug logging, while the environment variable enables fine-grained control in containerized deployments.

Signed-off-by: Pavel Tišnovský <ptisnovs@redhat.com>
Signed-off-by: Major Hayden <major@redhat.com>

Author: major

src/constants.py

@@ -176,3 +176,9 @@
 
 # SOLR OKP RAG
 MIMIR_DOC_URL = "https://mimir.corp.redhat.com"
+
+# Logging configuration constants
+# Environment variable name for configurable log level
+LIGHTSPEED_STACK_LOG_LEVEL_ENV_VAR = "LIGHTSPEED_STACK_LOG_LEVEL"
+# Default log level when environment variable is not set
+DEFAULT_LOG_LEVEL = "INFO"

src/lightspeed_stack.py

@@ -6,6 +6,7 @@
 
 import logging
 import os
+import sys
 from argparse import ArgumentParser
 
 
@@ -16,10 +17,20 @@
 from runners.uvicorn import start_uvicorn
 from runners.quota_scheduler import start_quota_scheduler
 from utils import schema_dumper
+from constants import LIGHTSPEED_STACK_LOG_LEVEL_ENV_VAR, DEFAULT_LOG_LEVEL
 
 FORMAT = "%(message)s"
+# Read log level from environment variable with validation
+log_level_str = os.environ.get(LIGHTSPEED_STACK_LOG_LEVEL_ENV_VAR, DEFAULT_LOG_LEVEL)
+log_level = getattr(logging, log_level_str.upper(), None)
+if not isinstance(log_level, int):
+    print(
+        f"WARNING: Invalid log level '{log_level_str}', falling back to {DEFAULT_LOG_LEVEL}",
+        file=sys.stderr,
+    )
+    log_level = getattr(logging, DEFAULT_LOG_LEVEL)
 logging.basicConfig(
-    level="INFO", format=FORMAT, datefmt="[%X]", handlers=[RichHandler()]
+    level=log_level, format=FORMAT, datefmt="[%X]", handlers=[RichHandler()], force=True
 )
 
 logger = get_logger(__name__)
@@ -83,6 +94,7 @@ def main() -> None:
     Start the Lightspeed Core Stack service process based on CLI flags and configuration.
 
     Parses command-line arguments, loads the configured settings, and then:
+    - If --verbose is provided, sets all loggers to DEBUG level.
     - If --dump-configuration is provided, writes the active configuration to
       configuration.json and exits (exits with status 1 on failure).
     - If --dump-schema is provided, writes the active configuration schema to
@@ -101,6 +113,14 @@ def main() -> None:
     parser = create_argument_parser()
     args = parser.parse_args()
 
+    if args.verbose:
+        os.environ[LIGHTSPEED_STACK_LOG_LEVEL_ENV_VAR] = "DEBUG"
+        logging.getLogger().setLevel(logging.DEBUG)
+        for logger_name in logging.Logger.manager.loggerDict:
+            existing_logger = logging.getLogger(logger_name)
+            if isinstance(existing_logger, logging.Logger):
+                existing_logger.setLevel(logging.DEBUG)
+
     configuration.load_configuration(args.config_file)
     logger.info("Configuration: %s", configuration.configuration)
     logger.info(

src/log.py

@@ -1,16 +1,20 @@
 """Log utilities."""
 
 import logging
+import os
 from rich.logging import RichHandler
 
+from constants import LIGHTSPEED_STACK_LOG_LEVEL_ENV_VAR, DEFAULT_LOG_LEVEL
+
 
 def get_logger(name: str) -> logging.Logger:
     """
     Get a logger configured for Rich console output.
 
-    The returned logger has its level set to DEBUG, its handlers replaced with
-    a single RichHandler for rich-formatted console output, and propagation to
-    ancestor loggers disabled.
+    The returned logger has its level set based on the LIGHTSPEED_STACK_LOG_LEVEL
+    environment variable (defaults to INFO), its handlers replaced with a single
+    RichHandler for rich-formatted console output, and propagation to ancestor
+    loggers disabled.
 
     Parameters:
         name (str): Name of the logger to retrieve or create.
@@ -19,7 +23,25 @@ def get_logger(name: str) -> logging.Logger:
         logging.Logger: The configured logger instance.
     """
     logger = logging.getLogger(name)
-    logger.setLevel(logging.DEBUG)
+
+    # Skip reconfiguration if logger already has a RichHandler from a prior call
+    if any(isinstance(h, RichHandler) for h in logger.handlers):
+        return logger
+
+    # Read log level from environment variable with default fallback
+    level_str = os.environ.get(LIGHTSPEED_STACK_LOG_LEVEL_ENV_VAR, DEFAULT_LOG_LEVEL)
+
+    # Validate the level string and convert to logging level constant
+    validated_level = getattr(logging, level_str.upper(), None)
+    if not isinstance(validated_level, int):
+        logger.warning(
+            "Invalid log level '%s', falling back to %s",
+            level_str,
+            DEFAULT_LOG_LEVEL,
+        )
+        validated_level = getattr(logging, DEFAULT_LOG_LEVEL)
+
+    logger.setLevel(validated_level)
     logger.handlers = [RichHandler()]
     logger.propagate = False
     return logger

tests/unit/test_log.py

@@ -1,6 +1,10 @@
 """Unit tests for functions defined in src/log.py."""
 
+import logging
+import pytest
+
 from log import get_logger
+from constants import LIGHTSPEED_STACK_LOG_LEVEL_ENV_VAR
 
 
 def test_get_logger() -> None:
@@ -12,3 +16,44 @@ def test_get_logger() -> None:
 
     # at least one handler need to be set
     assert len(logger.handlers) >= 1
+
+
+def test_get_logger_invalid_env_var_fallback(monkeypatch: pytest.MonkeyPatch) -> None:
+    """Test that invalid env var value falls back to INFO level."""
+    monkeypatch.setenv(LIGHTSPEED_STACK_LOG_LEVEL_ENV_VAR, "FOOBAR")
+
+    logger = get_logger("test_invalid")
+    assert logger.level == logging.INFO
+
+
+@pytest.mark.parametrize(
+    "level_name,expected_level",
+    [
+        ("DEBUG", logging.DEBUG),
+        ("debug", logging.DEBUG),
+        ("INFO", logging.INFO),
+        ("info", logging.INFO),
+        ("WARNING", logging.WARNING),
+        ("warning", logging.WARNING),
+        ("ERROR", logging.ERROR),
+        ("error", logging.ERROR),
+        ("CRITICAL", logging.CRITICAL),
+        ("critical", logging.CRITICAL),
+    ],
+)
+def test_get_logger_log_level(
+    monkeypatch: pytest.MonkeyPatch, level_name: str, expected_level: int
+) -> None:
+    """Test that all valid log levels work correctly, case-insensitively."""
+    monkeypatch.setenv(LIGHTSPEED_STACK_LOG_LEVEL_ENV_VAR, level_name)
+
+    logger = get_logger(f"test_{level_name}")
+    assert logger.level == expected_level
+
+
+def test_get_logger_default_log_level(monkeypatch: pytest.MonkeyPatch) -> None:
+    """Test that get_logger() uses INFO level by default when env var is not set."""
+    monkeypatch.delenv(LIGHTSPEED_STACK_LOG_LEVEL_ENV_VAR, raising=False)
+
+    logger = get_logger("test_default")
+    assert logger.level == logging.INFO