Add dynamic log level control with LoggerFilter and LoggerProcessor (#15)

* Update protos (and script)

* Add dynamic log level control with LoggerFilter and LoggerProcessor

Implements configurable log level management through Reforge configuration,
allowing real-time control of logging verbosity without application restarts.

Key features:
- LogLevel enum mapping to Python logging levels
- get_log_level() method with context-based evaluation
- logger_key option (default: "log-levels.default")
- LoggerFilter for standard Python logging integration
- LoggerProcessor for structlog integration (optional dependency)
- Evaluates LOG_LEVEL_V2 config type with reforge-sdk-logging context
- Returns DEBUG as default when config not found
- No telemetry/record_log functionality

Includes comprehensive tests and examples for both standard logging
and structlog integrations.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* Bump version to 1.1.0

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* Fix Python 3.9 compatibility: add __future__ annotations import

Adds 'from __future__ import annotations' to test_logging.py to enable
subscriptable types like logging.StreamHandler[Any] in Python 3.9.

Fixes: TypeError: 'type' object is not subscriptable

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* Add structlog to dev dependencies for testing

Makes structlog available in the test environment so LoggerProcessor tests
can run without being skipped. Structlog remains optional for end users
via the extras mechanism.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* Update field exclusions in context shape test

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: jkebinger

compile_protos.sh

@@ -1,6 +1,14 @@
 #!/usr/bin/env bash
 
+
+#!/usr/bin/env bash
+
+set -e
+
+PROTO_ROOT="${PROTO_ROOT:-..}"
+
+
 # https://buf.build/docs/installation
 
-cp ../prefab-cloud/prefab.proto .
+cp $PROTO_ROOT/prefab-cloud/prefab.proto .
 buf generate

examples/standard-logging/README.md

@@ -0,0 +1,71 @@
+## Standard Logging Example
+
+This example demonstrates how to use Reforge's `LoggerFilter` to dynamically control log levels for standard Python logging.
+
+### Features
+
+- Dynamic log level control through Reforge configuration
+- No application restart required to change log levels
+- Works with standard Python `logging` module
+- Can target specific loggers by name using context-based rules
+
+### Setup
+
+1. Install dependencies:
+
+   ```bash
+   poetry install --no-root
+   ```
+
+2. Set your Reforge SDK key (or use local-only mode as in the example):
+
+   ```bash
+   export REFORGE_SDK_KEY=your-sdk-key-here
+   ```
+
+3. Create a log level config in your Reforge dashboard:
+   - Config key: `log-levels.default`
+   - Type: `LOG_LEVEL_V2`
+   - Default value: `INFO` (or your preferred level)
+
+### Running the Example
+
+```bash
+poetry run python standard_logging_example.py
+```
+
+The example will log messages at all levels (DEBUG, INFO, WARNING, ERROR) every second.
+
+### Dynamic Control
+
+While the example is running, you can:
+
+1. Change the log level in your Reforge dashboard
+2. See the output change in real-time without restarting the application
+3. Use context-based rules to set different levels for different loggers
+
+For example, you could create rules like:
+
+- Set `DEBUG` level for `reforge.python.*` loggers
+- Set `ERROR` level for all other loggers
+- Set `INFO` level during business hours, `DEBUG` level at night
+
+### How It Works
+
+The `LoggerFilter` integrates with Python's standard logging by:
+
+1. Implementing the `logging.Filter` interface
+2. Querying Reforge config for the log level on each log message
+3. Returning `True` (allow) or `False` (block) based on the configured level
+4. Using a context containing the logger name for targeted rules
+
+### Advanced Usage
+
+You can customize the logger name lookup by subclassing `LoggerFilter`:
+
+```python
+class CustomLoggerFilter(LoggerFilter):
+    def logger_name(self, record: logging.LogRecord) -> str:
+        # Custom logic to derive logger name
+        return record.name.replace("myapp", "mycompany")
+```

examples/standard-logging/pyproject.toml

@@ -0,0 +1,14 @@
+[tool.poetry]
+name = "standard-logging-example"
+version = "0.1.0"
+description = "Example demonstrating Reforge SDK with standard Python logging"
+authors = ["Reforge"]
+package-mode = false
+
+[tool.poetry.dependencies]
+python = "^3.9"
+sdk-reforge = {path = "../../", develop = true}
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"

examples/standard-logging/standard_logging_example.py

@@ -0,0 +1,69 @@
+"""
+Example demonstrating dynamic log level control with standard Python logging.
+
+This example shows how to use the LoggerFilter to dynamically control log levels
+based on Reforge configuration. The log level can be changed in real-time through
+the Reforge dashboard without restarting the application.
+"""
+
+import logging
+import sys
+import time
+import os
+
+from sdk_reforge import ReforgeSDK, Options, LoggerFilter
+
+
+def main():
+    # Set up the root logger with a stdout handler
+    root_logger = logging.getLogger()
+    handler = logging.StreamHandler(sys.stdout)
+    handler.setFormatter(
+        logging.Formatter("%(asctime)s - %(name)s - %(levelname)s - %(message)s")
+    )
+    root_logger.addHandler(handler)
+    root_logger.setLevel(logging.DEBUG)
+
+    # Configure SDK to run in local-only mode for this example
+    # In production, you would set your REFORGE_SDK_KEY instead
+    os.environ["REFORGE_DATASOURCES"] = "LOCAL_ONLY"
+
+    def configure_logger():
+        """Add the Reforge LoggerFilter after SDK is ready"""
+        handler.addFilter(LoggerFilter())
+        print("✓ Logger filter configured - log levels now controlled by Reforge\n")
+
+    # Create SDK with on_ready_callback to add the filter when ready
+    options = Options(
+        x_datafile="test.datafile.json",  # In production, omit this for remote config
+        on_ready_callback=configure_logger,
+        logger_key="log-levels.default",  # Config key that controls log levels
+    )
+
+    sdk = ReforgeSDK(options)
+
+    # Create a test logger
+    logger = logging.getLogger("reforge.python.example")
+
+    print("Logging at all levels every second...")
+    print("Try changing the 'log-levels.default' config in Reforge dashboard")
+    print("to see log output change dynamically!\n")
+
+    # Log messages at different levels in a loop
+    try:
+        for i in range(60):  # Run for 60 seconds
+            logger.debug(f"[{i}] Debug message - only visible when level is DEBUG")
+            logger.info(f"[{i}] Info message - visible when level is INFO or below")
+            logger.warning(
+                f"[{i}] Warning message - visible when level is WARN or below"
+            )
+            logger.error(f"[{i}] Error message - visible when level is ERROR or below")
+            time.sleep(1)
+    except KeyboardInterrupt:
+        print("\nShutting down...")
+
+    sdk.close()
+
+
+if __name__ == "__main__":
+    main()

examples/structlog/README.md

@@ -0,0 +1,91 @@
+## Structlog Example
+
+This example demonstrates how to use Reforge's `LoggerProcessor` to dynamically control log levels for structlog.
+
+### Features
+
+- Dynamic log level control through Reforge configuration
+- No application restart required to change log levels
+- Works with structlog's processor pipeline
+- Can target specific loggers by name using context-based rules
+- Integrates seamlessly with structlog's structured logging features
+
+### Setup
+
+1. Install dependencies:
+
+   ```bash
+   poetry install --no-root
+   ```
+
+2. Set your Reforge SDK key (or use local-only mode as in the example):
+
+   ```bash
+   export REFORGE_SDK_KEY=your-sdk-key-here
+   ```
+
+3. Create a log level config in your Reforge dashboard:
+   - Config key: `log-levels.default`
+   - Type: `LOG_LEVEL_V2`
+   - Default value: `INFO` (or your preferred level)
+
+### Running the Example
+
+```bash
+poetry run python structlog_example.py
+```
+
+The example will log messages at all levels (DEBUG, INFO, WARNING, ERROR) every second.
+
+### Dynamic Control
+
+While the example is running, you can:
+
+1. Change the log level in your Reforge dashboard
+2. See the output change in real-time without restarting the application
+3. Use context-based rules to set different levels for different modules
+
+For example, you could create rules like:
+
+- Set `DEBUG` level for `myapp.database` module
+- Set `ERROR` level for all other modules
+- Set `INFO` level during business hours, `DEBUG` level at night
+
+### How It Works
+
+The `LoggerProcessor` integrates with structlog by:
+
+1. Implementing a processor in the structlog pipeline
+2. Querying Reforge config for the log level on each log event
+3. Raising `DropEvent` to filter messages below the configured level
+4. Using a context containing the logger name for targeted rules
+
+**Important**: The `LoggerProcessor` must come **after** `structlog.stdlib.add_log_level` in the processor pipeline, as it depends on the level information added by that processor.
+
+### Advanced Usage
+
+You can customize the logger name lookup by subclassing `LoggerProcessor`:
+
+```python
+class CustomLoggerNameProcessor(LoggerProcessor):
+    def logger_name(self, logger, event_dict: dict) -> str:
+        # Use module name as logger name
+        return event_dict.get("module", "unknown")
+```
+
+This allows you to create log level rules based on module names, file names, or any other field in the event dictionary.
+
+### Structlog Installation
+
+Structlog is an optional dependency. To install the SDK with structlog support:
+
+```bash
+pip install sdk-reforge[structlog]
+```
+
+Or in your `pyproject.toml`:
+
+```toml
+[tool.poetry.dependencies]
+sdk-reforge = {version = "^1.0", extras = ["structlog"]}
+```

examples/structlog/pyproject.toml

@@ -0,0 +1,14 @@
+[tool.poetry]
+name = "structlog-example"
+version = "0.1.0"
+description = "Example demonstrating Reforge SDK with structlog"
+authors = ["Reforge"]
+package-mode = false
+
+[tool.poetry.dependencies]
+python = "^3.9"
+sdk-reforge = {path = "../../", develop = true, extras = ["structlog"]}
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"

examples/structlog/structlog_example.py

@@ -0,0 +1,112 @@
+"""
+Example demonstrating dynamic log level control with structlog.
+
+This example shows how to use the LoggerProcessor to dynamically control log levels
+based on Reforge configuration. The log level can be changed in real-time through
+the Reforge dashboard without restarting the application.
+"""
+
+import time
+import os
+import structlog
+from sdk_reforge import ReforgeSDK, Options, LoggerProcessor
+
+
+class CustomLoggerNameProcessor(LoggerProcessor):
+    """
+    Custom processor that extracts the logger name from the module field.
+
+    This demonstrates how to customize the logger name lookup for more
+    sophisticated log level rules based on module names.
+    """
+
+    def logger_name(self, logger, event_dict: dict) -> str:
+        # Use the module name as the logger name for Reforge evaluation
+        return event_dict.get("module") or "unknown"
+
+
+def main():
+    """
+    Configure structlog with Reforge dynamic log level control.
+    """
+    # Configure structlog with our processor
+    # Note: The LoggerProcessor must come after add_log_level
+    structlog.configure(
+        processors=[
+            structlog.processors.TimeStamper(fmt="iso"),
+            structlog.stdlib.add_log_level,  # Must come before LoggerProcessor
+            structlog.processors.CallsiteParameterAdder(
+                {
+                    structlog.processors.CallsiteParameter.THREAD_NAME,
+                    structlog.processors.CallsiteParameter.FILENAME,
+                    structlog.processors.CallsiteParameter.FUNC_NAME,
+                    structlog.processors.CallsiteParameter.LINENO,
+                    structlog.processors.CallsiteParameter.PROCESS,
+                    structlog.processors.CallsiteParameter.MODULE,
+                }
+            ),
+            CustomLoggerNameProcessor().processor,  # Add Reforge log level control
+            structlog.dev.ConsoleRenderer(pad_event=25),
+        ]
+    )
+
+    logger = structlog.getLogger()
+
+    # Configure SDK to run in local-only mode for this example
+    # In production, you would set your REFORGE_SDK_KEY instead
+    os.environ["REFORGE_DATASOURCES"] = "LOCAL_ONLY"
+
+    def on_ready():
+        """Called when SDK is ready"""
+        logger.info("✓ SDK ready - log levels now controlled by Reforge")
+
+    # Create SDK
+    options = Options(
+        x_datafile="test.datafile.json",  # In production, omit this for remote config
+        on_ready_callback=on_ready,
+        logger_key="log-levels.default",  # Config key that controls log levels
+    )
+
+    sdk = ReforgeSDK(options)
+
+    logger.info("Starting structlog example")
+    logger.info(
+        "Try changing the 'log-levels.default' config in Reforge dashboard "
+        "to see log output change dynamically!"
+    )
+
+    # Log messages at different levels in a loop
+    try:
+        for i in range(60):  # Run for 60 seconds
+            # Get a config value to show SDK is working
+            config_value = sdk.get("example-config", default="default-value")
+
+            logger.debug(
+                f"[{i}] Debug message",
+                config_value=config_value,
+                level_hint="Only visible when level is DEBUG",
+            )
+            logger.info(
+                f"[{i}] Info message",
+                config_value=config_value,
+                level_hint="Visible when level is INFO or below",
+            )
+            logger.warning(
+                f"[{i}] Warning message",
+                config_value=config_value,
+                level_hint="Visible when level is WARN or below",
+            )
+            logger.error(
+                f"[{i}] Error message",
+                config_value=config_value,
+                level_hint="Visible when level is ERROR or below",
+            )
+            time.sleep(1)
+    except KeyboardInterrupt:
+        logger.info("Shutting down...")
+
+    sdk.close()
+
+
+if __name__ == "__main__":
+    main()