ENG-10963 feat(log): add stdlib logging pipeline in reflex_base.utils.log (1/5)

news/+eng-10963-log-pipeline.feature.md

@@ -0,0 +1 @@
+Framework logging now flows through standard python `logging` with per-module loggers (`reflex_base.utils.log`, re-exported as `reflex.utils.log`), bootstrapped on `import reflex`. Rich colored output is preserved at the sink, and `REFLEX_LOG_JSON` emits machine-readable JSON-lines records. `--loglevel critical` no longer prints the system-info banner (broken `LogLevel` string-compare ordering fixed).

packages/reflex-base/news/+eng-10963-log-pipeline.feature.md

@@ -0,0 +1 @@
+Added `reflex_base.utils.log`: a standard python logging pipeline with a rich-rendering console handler (legacy colors preserved), a JSON-lines handler behind `REFLEX_LOG_JSON`, record deduplication, and file logging. `LogLevel` gained a correct total ordering and `to_logging_level()`, and the interactive console helpers (`print`/`rule`/`status`/`progress`) now respect JSON mode.

packages/reflex-base/src/reflex_base/constants/base.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import logging
 import platform
 from enum import Enum
 from importlib import metadata
@@ -248,6 +249,19 @@ def from_string(cls, level: str | None) -> LogLevel | None:
         except KeyError:
             return None
 
+    # The str mixin supplies alphabetical comparisons, so all four operators
+    # must be overridden to compare by verbosity rank instead.
+    def __lt__(self, other: LogLevel) -> bool:
+        """Compare log levels.
+
+        Args:
+            other: The other log level.
+
+        Returns:
+            True if the log level is less verbose than the other log level.
+        """
+        return _LOG_LEVEL_RANK[self] < _LOG_LEVEL_RANK[other]
+
     def __le__(self, other: LogLevel) -> bool:
         """Compare log levels.
 
@@ -257,8 +271,39 @@ def __le__(self, other: LogLevel) -> bool:
         Returns:
             True if the log level is less than or equal to the other log level.
         """
-        levels = list(LogLevel)
-        return levels.index(self) <= levels.index(other)
+        return _LOG_LEVEL_RANK[self] <= _LOG_LEVEL_RANK[other]
+
+    def __gt__(self, other: LogLevel) -> bool:
+        """Compare log levels.
+
+        Args:
+            other: The other log level.
+
+        Returns:
+            True if the log level is more verbose-restrictive than the other.
+        """
+        return _LOG_LEVEL_RANK[self] > _LOG_LEVEL_RANK[other]
+
+    def __ge__(self, other: LogLevel) -> bool:
+        """Compare log levels.
+
+        Args:
+            other: The other log level.
+
+        Returns:
+            True if the log level is greater than or equal to the other.
+        """
+        return _LOG_LEVEL_RANK[self] >= _LOG_LEVEL_RANK[other]
+
+    def to_logging_level(self) -> int:
+        """Map this level to a stdlib logging level number.
+
+        DEFAULT acts as a threshold equivalent to INFO.
+
+        Returns:
+            The stdlib logging level.
+        """
+        return _LOGGING_LEVELS[self]
 
     def subprocess_level(self):
         """Return the log level for the subprocess.
@@ -269,6 +314,17 @@ def subprocess_level(self):
         return self if self != LogLevel.DEFAULT else LogLevel.WARNING
 
 
+_LOG_LEVEL_RANK = {level: rank for rank, level in enumerate(LogLevel)}
+_LOGGING_LEVELS = {
+    LogLevel.DEBUG: logging.DEBUG,
+    LogLevel.DEFAULT: logging.INFO,
+    LogLevel.INFO: logging.INFO,
+    LogLevel.WARNING: logging.WARNING,
+    LogLevel.ERROR: logging.ERROR,
+    LogLevel.CRITICAL: logging.CRITICAL,
+}
+
+
 # Server socket configuration variables
 POLLING_MAX_HTTP_BUFFER_SIZE = 1000 * 1000
 

packages/reflex-base/src/reflex_base/environment.py

@@ -5,6 +5,7 @@
 import dataclasses
 import enum
 import importlib
+import logging
 import os
 from collections.abc import Sequence
 from functools import lru_cache
@@ -27,6 +28,8 @@
 from reflex_base.utils.exceptions import EnvironmentVarValueError
 from reflex_base.utils.types import GenericType, is_union, value_inside_optional
 
+logger = logging.getLogger(__name__)
+
 
 def get_default_value_for_field(field: dataclasses.Field) -> Any:
     """Get the default value for a field.
@@ -705,6 +708,9 @@ class EnvironmentVariables:
     # Enable full logging of debug messages to reflex user directory.
     REFLEX_ENABLE_FULL_LOGGING: EnvVar[bool] = env_var(False)
 
+    # Emit logs as machine-readable JSON records instead of rich console output.
+    REFLEX_LOG_JSON: EnvVar[bool] = env_var(False)
+
     # Whether to enable hot module replacement
     VITE_HMR: EnvVar[bool] = env_var(True)
 
@@ -781,13 +787,11 @@ def _load_dotenv_from_files(files: list[Path]):
     Args:
         files: A list of Path objects representing the environment variable files.
     """
-    from reflex_base.utils import console
-
     if not files:
         return
 
     if load_dotenv is None:
-        console.error(
+        logger.error(
             """The `python-dotenv` package is required to load environment variables from a file. Run `pip install "python-dotenv>=1.1.0"`."""
         )
         return

packages/reflex-base/src/reflex_base/utils/console.py

@@ -6,19 +6,21 @@
 import datetime
 import functools
 import inspect
-import os
 import shutil
 import sys
 import time
+from collections.abc import Sequence
 from pathlib import Path
 from types import FrameType, ModuleType
 
 from rich.console import Console
 from rich.progress import MofNCompleteColumn, Progress, TaskID, TimeElapsedColumn
 from rich.prompt import Prompt
+from rich.table import Table
 
 from reflex_base.constants import LogLevel
 from reflex_base.constants.base import Reflex
+from reflex_base.utils import log as _log
 from reflex_base.utils.decorator import once
 
 # Console for pretty printing.
@@ -58,19 +60,11 @@ def set_log_level(log_level: LogLevel | None):
 
     Args:
         log_level: The log level to set.
-
-    Raises:
-        TypeError: If the log level is a string.
     """
     if log_level is None:
         return
-    if not isinstance(log_level, LogLevel):
-        msg = f"log_level must be a LogLevel enum value, got {log_level} of type {type(log_level)} instead."
-        raise TypeError(msg)
+    _log.set_log_level(log_level)
     global _LOG_LEVEL
-    if log_level != _LOG_LEVEL:
-        # Set the loglevel persistenly for subprocesses.
-        os.environ["REFLEX_LOGLEVEL"] = log_level.value
     _LOG_LEVEL = log_level
 
 
@@ -91,6 +85,9 @@ def print(msg: str, *, dedupe: bool = False, **kwargs):
         dedupe: If True, suppress multiple console logs of print message.
         kwargs: Keyword arguments to pass to the print function.
     """
+    if _log.is_json_mode():
+        _log.emit_json_print(msg, dedupe=dedupe)
+        return
     if dedupe:
         if msg in _EMITTED_PRINTS:
             return
@@ -106,6 +103,9 @@ def _print_stderr(msg: str, *, dedupe: bool = False, **kwargs):
         dedupe: If True, suppress multiple console logs of print message.
         kwargs: Keyword arguments to pass to the print function.
     """
+    if _log.is_json_mode():
+        _log.emit_json_print(msg, dedupe=dedupe, stderr=True)
+        return
     if dedupe:
         if msg in _EMITTED_PRINTS:
             return
@@ -241,6 +241,8 @@ def rule(title: str, **kwargs):
         title: The title of the rule.
         kwargs: Keyword arguments to pass to the print function.
     """
+    if _log.is_json_mode():
+        return
     _console.rule(title, **kwargs)
 
 
@@ -417,6 +419,27 @@ def ask(
     )
 
 
+def print_table(
+    tabular_data: list[list[str]],
+    headers: Sequence[str] = (),
+) -> None:
+    """Print a table to the console.
+
+    Args:
+        tabular_data: The data to print in tabular format.
+        headers: The headers for the table.
+    """
+    table = Table()
+
+    for column in headers:
+        table.add_column(column)
+
+    for row in tabular_data:
+        table.add_row(*row)
+
+    _console.print(table)
+
+
 def progress():
     """Create a new progress bar.
 
@@ -427,6 +450,7 @@ def progress():
         *Progress.get_default_columns()[:-1],
         MofNCompleteColumn(),
         TimeElapsedColumn(),
+        disable=_log.is_json_mode(),
     )
 
 
@@ -440,6 +464,8 @@ def status(*args, **kwargs):
     Returns:
         A new status.
     """
+    if _log.is_json_mode():
+        return _log._quiet_console.status(*args, **kwargs)
     return _console.status(*args, **kwargs)