e1.6.1 Configurable internal errors, minor documentation and code fixes.

doc/compatibility-adapters.md

@@ -177,7 +177,7 @@ adapter := compat.NewFastHTTPAdapter(logger,
         if strings.Contains(msg, "performance") {
             return log.LevelWarn
         }
-        // Return 0 to use default detection
+        // Return 0 to use the adapter's default log level (log.LevelInfo by default)
         return 0
     }),
 )

doc/configuration.md

@@ -57,13 +57,14 @@ heartbeat_interval_s = 300
 
 ### Basic Settings
 
-| Parameter | Type | Description | Default |
-|-----------|------|-------------|---------|
-| `level` | `int64` | Minimum log level (-4=Debug, 0=Info, 4=Warn, 8=Error) | `0` |
-| `name` | `string` | Base name for log files | `"log"` |
+| Parameter | Type | Description | Default    |
+|-----------|------|-------------|------------|
+| `level` | `int64` | Minimum log level (-4=Debug, 0=Info, 4=Warn, 8=Error) | `0`        |
+| `name` | `string` | Base name for log files | `"log"`    |
 | `directory` | `string` | Directory to store log files | `"./logs"` |
-| `format` | `string` | Output format: `"txt"` or `"json"` | `"txt"` |
-| `extension` | `string` | Log file extension (without dot) | `"log"` |
+| `format` | `string` | Output format: `"txt"` or `"json"` | `"txt"`    |
+| `extension` | `string` | Log file extension (without dot) | `"log"`    |
+| `internal_errors_to_stderr` | `bool` | Write logger's internal errors to stderr | `false`    |
 
 ### Output Control
 
@@ -158,6 +159,7 @@ logger.InitWithDefaults(
     "format=json",           // Structured for log aggregators
     "level=0",               // Info level
     "show_timestamp=true",   // Include timestamps
+    "internal_errors_to_stderr=false", // Suppress internal errors
 )
 ```
 

doc/logging-guide.md

@@ -286,6 +286,50 @@ logger.Info("Batch processing",
 )
 ```
 
+## Internal Error Handling
+
+The logger may encounter internal errors during operation (e.g., file rotation failures, disk space issues). By default, writing these errors to stderr is disabled, but can be enabled in configuration for diagnostic purposes.
+
+### Controlling Internal Error Output
+
+For applications requiring clean stderr output, keep internal error messages disabled:
+
+```go
+logger.InitWithDefaults(
+    "internal_errors_to_stderr=false",  // Suppress internal diagnostics
+)
+```
+
+### When to Keep Internal Errors Disabled
+
+Consider disabling internal error output for:
+
+- CLI tools producing structured output
+- Daemons with strict stderr requirements
+- Applications with custom error monitoring
+- Container environments with log aggregation
+
+### Monitoring Without stderr
+
+When internal errors are disabled, monitor logger health using:
+
+1. **Heartbeat monitoring**: Detect issues via heartbeat logs
+   ```go
+   logger.InitWithDefaults(
+       "internal_errors_to_stderr=false",
+       "heartbeat_level=2",  // Include disk stats
+       "heartbeat_interval_s=60",
+   )
+   ```
+
+2. **Check for dropped logs**: The logger tracks dropped messages
+   ```go
+   // Dropped logs appear in regular log output when possible
+   // Look for: "Logs were dropped" messages
+   ```
+
+3. **External monitoring**: Monitor disk space and file system health independently
+
 ## Logging Patterns
 
 ### Request Lifecycle