Update docs/modules/usage/logging.md

docs/modules/usage/logging.md

@@ -0,0 +1,120 @@
+# Logging in OpenHands
+
+OpenHands provides a robust and configurable logging system that helps developers track application behavior, debug issues, and monitor LLM interactions. This guide covers the key aspects of OpenHands' logging functionality.
+
+## Environment Variables
+
+OpenHands' logging behavior can be customized through several environment variables:
+
+### Core Logging Controls
+
+- `LOG_LEVEL`: Sets the logging level (default: 'INFO')
+  - Valid values: DEBUG, INFO, WARNING, ERROR, CRITICAL
+  - Debug level can also be enabled by setting `DEBUG=true` or `DEBUG=1`
+
+- `LOG_TO_FILE`: Enables file-based logging (default: false)
+  - When enabled, logs are written to `logs/openhands_YYYY-MM-DD.log` in the project directory
+  - Automatically enabled when in DEBUG mode
+
+### JSON Logging
+
+- `LOG_JSON`: Enables structured JSON logging (default: false)
+  - When enabled, logs are output in JSON format for better machine readability
+  - Useful for log aggregation and analysis systems
+
+- `LOG_JSON_LEVEL_KEY`: Customizes the key name for log levels in JSON output (default: 'level')
+  - Example: `{"timestamp": "2025-04-07 10:00:00", "level": "INFO", "message": "..."}`
+
+### Debug Options
+
+- `DEBUG`: Enables debug mode (default: false)
+  - Sets LOG_LEVEL to DEBUG
+  - Enables stack traces for errors
+  - Automatically enables file logging
+
+- `DEBUG_LLM`: Enables detailed LLM interaction logging (default: false)
+  - **WARNING**: May expose sensitive information like API keys
+  - Requires explicit confirmation when enabled
+  - Should never be enabled in production
+
+- `DEBUG_RUNTIME`: Enables runtime environment debugging (default: false)
+  - Streams Docker container logs
+  - Useful for debugging sandbox environments
+
+### Event Logging
+
+- `LOG_ALL_EVENTS`: Enables verbose event logging (default: false)
+  - Logs all events with additional context
+  - Useful for debugging agent behavior
+
+## Log File Structure
+
+When file logging is enabled (`LOG_TO_FILE=true`), logs are organized as follows:
+
+```
+logs/
+├── openhands_YYYY-MM-DD.log    # Main application log
+└── llm/                        # LLM interaction logs
+    └── [session]/              # Session-specific logs
+        ├── prompt_001.log      # LLM prompts
+        └── response_001.log    # LLM responses
+```
+
+- Session directories are named:
+  - In debug mode: `YY-MM-DD_HH-MM`
+  - Otherwise: `default`
+
+## Security Features
+
+### Sensitive Data Protection
+
+OpenHands provides two complementary approaches to protect sensitive data in logs:
+
+1. **SensitiveDataFilter (Pattern-Based)**
+   - Automatically masks values based on patterns
+   - Primarily used for environment variables and known formats:
+     - SECRET, _KEY, _CODE, _TOKEN in variable names
+     - Common patterns like API keys, tokens, credentials
+   - Example:
+     ```python
+     # Original: "API key: sk-1234567890"
+     # Filtered: "API key: ******"
+     ```
+
+2. **Secret Management (Explicit)**
+   - Uses `set_secrets()` and `update_secrets()` to track specific values
+   - Replaces exact matches of secret values with `<secret_hidden>`
+   - More precise than pattern matching
+   - Usage:
+     ```python
+     from openhands.events.stream import EventStream
+
+     stream = EventStream(...)
+     stream.set_secrets({
+         "github_token": "ghp_actual_token",
+         "api_key": "sk_live_123456"
+     })
+     # All occurrences of these exact values will be replaced
+     ```
+
+Choose the appropriate method based on your needs:
+- Use `SensitiveDataFilter` for general protection against accidental exposure
+- Use `set_secrets()` when you need precise control over specific secret values
+
+## Best Practices
+
+1. **Production Settings**
+   - Keep `DEBUG` and `DEBUG_LLM` disabled
+   - Consider enabling `LOG_JSON` for structured logging
+   - Use appropriate `LOG_LEVEL` (INFO or WARNING recommended)
+
+2. **Development Settings**
+   - Enable `DEBUG` for detailed logging
+   - Use `LOG_TO_FILE` to persist logs
+   - Enable `LOG_ALL_EVENTS` when debugging agent behavior
+
+3. **Security Considerations**
+   - Never enable `DEBUG_LLM` in production
+   - Regularly review logs for accidentally exposed sensitive data
+   - Use `SensitiveDataFilter` for custom logging implementations
+

docs/sidebars.ts

@@ -211,6 +211,11 @@ const sidebars: SidebarsConfig = {
           label: 'Custom Sandbox',
           id: 'usage/how-to/custom-sandbox-guide',
         },
+        {
+          type: 'doc',
+          label: 'Logging',
+          id: 'usage/logging',
+        },
       ],
     },
     {