Split logs to stdout and stderr by default

Author: davegaeddert

plain/plain/logs/README.md

@@ -137,3 +137,40 @@ app_logger.debug("This might not appear")
 with app_logger.force_debug():
     app_logger.debug("This will definitely appear", extra_data="debug_info")
 ```
+
+## Advanced usage
+
+### Output streams
+
+By default, Plain splits log output by severity level to ensure proper log classification on cloud platforms:
+
+- **DEBUG, INFO** → `stdout` (standard output)
+- **WARNING, ERROR, CRITICAL** → `stderr` (error output)
+
+This behavior ensures that platforms which automatically detect log severity based on output streams correctly classify logs as informational vs errors.
+
+You can customize this behavior using the `PLAIN_LOG_STREAM` environment variable:
+
+```bash
+# Default: split by level (INFO to stdout, WARNING+ to stderr)
+export PLAIN_LOG_STREAM=split
+
+# Send all logs to stdout (simple, predictable)
+export PLAIN_LOG_STREAM=stdout
+
+# Send all logs to stderr (legacy Python behavior)
+export PLAIN_LOG_STREAM=stderr
+```
+
+## Logging settings
+
+All logging settings can be configured via environment variables:
+
+| Setting               | Environment Variable        | Default      | Description                                              |
+| --------------------- | --------------------------- | ------------ | -------------------------------------------------------- |
+| `FRAMEWORK_LOG_LEVEL` | `PLAIN_FRAMEWORK_LOG_LEVEL` | `"INFO"`     | Log level for the `plain` logger                         |
+| `LOG_LEVEL`           | `PLAIN_LOG_LEVEL`           | `"INFO"`     | Log level for the `app` logger                           |
+| `LOG_FORMAT`          | `PLAIN_LOG_FORMAT`          | `"keyvalue"` | Output format: `"json"`, `"keyvalue"`, or `"standard"`   |
+| `LOG_STREAM`          | `PLAIN_LOG_STREAM`          | `"split"`    | Output stream mode: `"split"`, `"stdout"`, or `"stderr"` |
+
+**Log levels:** `"DEBUG"`, `"INFO"`, `"WARNING"`, `"ERROR"`, `"CRITICAL"`

plain/plain/logs/__init__.py

@@ -1,3 +1,3 @@
-from .loggers import app_logger
+from .app import app_logger
 
 __all__ = ["app_logger"]

plain/plain/logs/loggers.py plain/plain/logs/app.pyplain/plain/logs/loggers.py renamed to plain/plain/logs/app.py

@@ -1,37 +1,85 @@
 import logging
+import sys
+from typing import TextIO
 
+from .filters import DebugInfoFilter, WarningErrorCriticalFilter
 from .formatters import JSONFormatter, KeyValueFormatter
 
 
+def attach_log_handlers(
+    *,
+    logger: logging.Logger,
+    info_stream: TextIO,
+    warning_stream: TextIO,
+    formatter: logging.Formatter,
+) -> None:
+    """Attach two handlers to a logger that split by log level.
+
+    INFO and below go to info_stream, WARNING and above go to warning_stream.
+    """
+    # DEBUG and INFO handler
+    info_handler = logging.StreamHandler(info_stream)
+    info_handler.addFilter(DebugInfoFilter())
+    info_handler.setFormatter(formatter)
+    logger.addHandler(info_handler)
+
+    # WARNING, ERROR, and CRITICAL handler
+    warning_handler = logging.StreamHandler(warning_stream)
+    warning_handler.addFilter(WarningErrorCriticalFilter())
+    warning_handler.setFormatter(formatter)
+    logger.addHandler(warning_handler)
+
+
 def configure_logging(
-    *, plain_log_level: int | str, app_log_level: int | str, app_log_format: str
+    *,
+    plain_log_level: int | str,
+    app_log_level: int | str,
+    app_log_format: str,
+    log_stream: str = "split",
 ) -> None:
+    # Determine which streams to use based on log_stream setting
+    if log_stream == "split":
+        info_stream = sys.stdout
+        warning_stream = sys.stderr
+    elif log_stream == "stdout":
+        info_stream = sys.stdout
+        warning_stream = sys.stdout
+    else:  # stderr (or any other value defaults to stderr for backwards compat)
+        info_stream = sys.stderr
+        warning_stream = sys.stderr
+
     # Create and configure the plain logger (uses standard Logger, not AppLogger)
     plain_logger = logging.getLogger("plain")
     plain_logger.setLevel(plain_log_level)
-    plain_handler = logging.StreamHandler()
-    plain_handler.setFormatter(logging.Formatter("[%(levelname)s] %(message)s"))
-    plain_logger.addHandler(plain_handler)
+    attach_log_handlers(
+        logger=plain_logger,
+        info_stream=info_stream,
+        warning_stream=warning_stream,
+        formatter=logging.Formatter("[%(levelname)s] %(message)s"),
+    )
     plain_logger.propagate = False
 
     # Configure the existing app_logger
-    from .loggers import app_logger
+    from .app import app_logger
 
     app_logger.setLevel(app_log_level)
     app_logger.propagate = False
 
-    app_handler = logging.StreamHandler()
+    # Determine formatter based on app_log_format
     match app_log_format:
         case "json":
-            app_handler.setFormatter(JSONFormatter("%(json)s"))
+            formatter = JSONFormatter("%(json)s")
         case "keyvalue":
-            app_handler.setFormatter(
-                KeyValueFormatter("[%(levelname)s] %(message)s %(keyvalue)s")
-            )
+            formatter = KeyValueFormatter("[%(levelname)s] %(message)s %(keyvalue)s")
         case _:
-            app_handler.setFormatter(logging.Formatter("[%(levelname)s] %(message)s"))
+            formatter = logging.Formatter("[%(levelname)s] %(message)s")
 
-    app_logger.addHandler(app_handler)
+    attach_log_handlers(
+        logger=app_logger,
+        info_stream=info_stream,
+        warning_stream=warning_stream,
+        formatter=formatter,
+    )
 
     # Register the app_logger in the logging system so getLogger("app") returns it
     logging.root.manager.loggerDict["app"] = app_logger

plain/plain/logs/configure.py

@@ -0,0 +1,15 @@
+import logging
+
+
+class DebugInfoFilter(logging.Filter):
+    """Filter that only allows DEBUG and INFO log records."""
+
+    def filter(self, record: logging.LogRecord) -> bool:
+        return record.levelno <= logging.INFO
+
+
+class WarningErrorCriticalFilter(logging.Filter):
+    """Filter that only allows WARNING, ERROR, and CRITICAL log records."""
+
+    def filter(self, record: logging.LogRecord) -> bool:
+        return record.levelno >= logging.WARNING

plain/plain/logs/filters.py

@@ -67,6 +67,7 @@ def setup() -> None:
         plain_log_level=settings.FRAMEWORK_LOG_LEVEL,
         app_log_level=settings.LOG_LEVEL,
         app_log_format=settings.LOG_FORMAT,
+        log_stream=settings.LOG_STREAM,
     )
 
     packages_registry.populate(settings.INSTALLED_PACKAGES)

plain/plain/runtime/__init__.py

@@ -138,6 +138,7 @@
 FRAMEWORK_LOG_LEVEL: str = "INFO"
 LOG_LEVEL: str = "INFO"
 LOG_FORMAT: str = "keyvalue"
+LOG_STREAM: str = "split"  # "split", "stdout", or "stderr"
 
 # MARK: Assets
 

plain/plain/runtime/global_settings.py

@@ -5,9 +5,9 @@
 import pytest
 
 from plain.logs import app_logger
+from plain.logs.app import AppLogger
 from plain.logs.configure import configure_logging
 from plain.logs.formatters import JSONFormatter, KeyValueFormatter
-from plain.logs.loggers import AppLogger
 
 
 class TestLoggingConfiguration: