Environment variable to force StreamHandler instead of RichHandler

Author: TamiTakamiya

src/constants.py

@@ -52,7 +52,8 @@
 - Do **NOT** use all uppercase - capitalize only the first letter of significant words
 - Exclude articles and prepositions (e.g., "a," "the," "of," "on," "in")
 - Exclude all punctuation and interpunction marks (e.g., . , : ; ! ? | "")
-- Retain original abbreviations. Do not expand an abbreviation if its specific meaning in the context is unknown or ambiguous.
+- Retain original abbreviations. Do not expand an abbreviation if its specific meaning in the
+  context is unknown or ambiguous.
 - Neutral objective language
 - Do **NOT** provide explanations, reasoning, or "processing steps".
 - Do **NOT** provide multiple options (e.g., do not use "or").
@@ -188,3 +189,6 @@
 DEFAULT_LOG_LEVEL = "INFO"
 # Default log format for plain-text logging in non-TTY environments
 DEFAULT_LOG_FORMAT = "%(asctime)s %(levelname)-8s %(name)s:%(lineno)d %(message)s"
+# Environment variable to force StreamHandler instead of RichHandler
+# Set to any non-empty value to disable RichHandler
+LIGHTSPEED_STACK_DISABLE_RICH_HANDLER_ENV_VAR = "LIGHTSPEED_STACK_DISABLE_RICH_HANDLER"

src/log.py

@@ -7,9 +7,10 @@
 from rich.logging import RichHandler
 
 from constants import (
-    LIGHTSPEED_STACK_LOG_LEVEL_ENV_VAR,
-    DEFAULT_LOG_LEVEL,
     DEFAULT_LOG_FORMAT,
+    DEFAULT_LOG_LEVEL,
+    LIGHTSPEED_STACK_DISABLE_RICH_HANDLER_ENV_VAR,
+    LIGHTSPEED_STACK_LOG_LEVEL_ENV_VAR,
 )
 
 
@@ -38,8 +39,7 @@ def resolve_log_level() -> int:
         # through a logger produces inconsistent output depending on root-logger
         # state.
         print(
-            f"WARNING: Invalid log level '{level_str}', "
-            f"falling back to {DEFAULT_LOG_LEVEL}",
+            f"WARNING: Invalid log level '{level_str}', " f"falling back to {DEFAULT_LOG_LEVEL}",
             file=sys.stderr,
         )
         validated_level = getattr(logging, DEFAULT_LOG_LEVEL)
@@ -49,18 +49,23 @@ def resolve_log_level() -> int:
 
 def create_log_handler() -> logging.Handler:
     """
-    Create and return a configured log handler based on TTY availability.
+    Create and return a configured log handler based on TTY availability and environment settings.
 
-    If stderr is connected to a terminal (TTY), returns a RichHandler for
-    rich-formatted console output. Otherwise, returns a StreamHandler with
+    If LIGHTSPEED_STACK_DISABLE_RICH_HANDLER is set to any non-empty value,
+    returns a StreamHandler with plain-text formatting. Otherwise, if stderr
+    is connected to a terminal (TTY), returns a RichHandler for rich-formatted
+    console output. If neither condition is met, returns a StreamHandler with
     plain-text formatting suitable for non-TTY environments (e.g., containers).
 
-    Parameters:
-        None
-
     Returns:
         logging.Handler: A configured handler instance (RichHandler or StreamHandler).
     """
+    # Check if RichHandler is explicitly disabled via environment variable
+    if os.environ.get(LIGHTSPEED_STACK_DISABLE_RICH_HANDLER_ENV_VAR):
+        handler = logging.StreamHandler()
+        handler.setFormatter(logging.Formatter(DEFAULT_LOG_FORMAT))
+        return handler
+
     if sys.stderr.isatty():
         # RichHandler's columnar layout assumes a real terminal.
         # RichHandler handles its own formatting, so no formatter is set.

tests/unit/test_log.py

@@ -6,8 +6,12 @@
 from pytest_mock import MockerFixture
 from rich.logging import RichHandler
 
-from log import get_logger, resolve_log_level, create_log_handler
-from constants import LIGHTSPEED_STACK_LOG_LEVEL_ENV_VAR, DEFAULT_LOG_FORMAT
+from constants import (
+    DEFAULT_LOG_FORMAT,
+    LIGHTSPEED_STACK_DISABLE_RICH_HANDLER_ENV_VAR,
+    LIGHTSPEED_STACK_LOG_LEVEL_ENV_VAR,
+)
+from log import create_log_handler, get_logger, resolve_log_level
 
 
 def test_get_logger() -> None:
@@ -116,3 +120,36 @@ def test_create_log_handler_non_tty_format(mocker: MockerFixture) -> None:
     assert handler.formatter is not None
     # pylint: disable=protected-access
     assert handler.formatter._fmt == DEFAULT_LOG_FORMAT
+
+
+def test_create_log_handler_disable_rich_with_tty(
+    mocker: MockerFixture, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """Test that RichHandler is disabled when env var is set, even with TTY."""
+    mocker.patch("sys.stderr.isatty", return_value=True)
+    monkeypatch.setenv(LIGHTSPEED_STACK_DISABLE_RICH_HANDLER_ENV_VAR, "1")
+    handler = create_log_handler()
+    assert isinstance(handler, logging.StreamHandler)
+    assert not isinstance(handler, RichHandler)
+
+
+def test_create_log_handler_disable_rich_format(
+    mocker: MockerFixture, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """Test that disabled RichHandler uses DEFAULT_LOG_FORMAT."""
+    mocker.patch("sys.stderr.isatty", return_value=True)
+    monkeypatch.setenv(LIGHTSPEED_STACK_DISABLE_RICH_HANDLER_ENV_VAR, "true")
+    handler = create_log_handler()
+    assert handler.formatter is not None
+    # pylint: disable=protected-access
+    assert handler.formatter._fmt == DEFAULT_LOG_FORMAT
+
+
+def test_create_log_handler_enable_rich_when_env_var_empty(
+    mocker: MockerFixture, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """Test that RichHandler is used when env var is empty string."""
+    mocker.patch("sys.stderr.isatty", return_value=True)
+    monkeypatch.setenv(LIGHTSPEED_STACK_DISABLE_RICH_HANDLER_ENV_VAR, "")
+    handler = create_log_handler()
+    assert isinstance(handler, RichHandler)