Enhance MelleaLogger with additional logging handlers for flexible log routing to multiple destinations: stdout (console), file, OTLP logs endpoint, and HTTP webhooks

[psschwei]

Description:
Enhance MelleaLogger with additional logging handlers for flexible log routing to multiple destinations: stdout (console), file, OTLP logs endpoint, and HTTP webhooks.

Detailed Requirements:

1. Add new handlers to MelleaLogger in mellea/core/utils.py:
   • RotatingFileHandler - File output with rotation (use stdlib logging.handlers)
   • OTLPLogHandler - OpenTelemetry Logs Protocol exporter (custom handler)
   • Keep existing RESTHandler for webhook support
2. Create handler configuration function:
   • configure_logging() - Set up handlers based on environment
   • Called automatically on first get_logger() call
3. Configuration via environment variables:
   • MELLEA_LOG_CONSOLE=true/false (default: true)
   • MELLEA_LOG_FILE=/path/to/logs/mellea.log
   • MELLEA_LOG_FILE_MAX_BYTES=10485760 (default: 10MB)
   • MELLEA_LOG_FILE_BACKUP_COUNT=5 (default: 5)
   • MELLEA_LOG_OTLP=true/false
   • MELLEA_LOG_WEBHOOK=http://endpoint (replaces FLOG env var)
4. Support JSON and human-readable formats per handler
5. Ensure all handlers receive trace context and Mellea context via filters

Files to Modify:

• mellea/core/utils.py - Add handlers and configuration function

Acceptance Criteria:

• Console handler with colored and JSON output options
• File handler with rotation support
• OTLP handler sends structured logs to collector
• Multiple handlers can be active simultaneously
• All handlers receive trace and context data via filters
• Handlers configurable via environment variables

[ajbozarth]

In order to get an MVP of OTLP logs in time for our next release I will be picking up this sub-issue first and only partially implementing it. I've asked Bob to detail out what work will be remaining after I finish my MVP implementation, that work would then be handled after the other sub-issues:

Implementation Split: MVP vs. Full Feature

This issue is being implemented in two phases to deliver value incrementally.

Phase 1: MVP - OTLP Export ✅ (Current Work)

What's being implemented:

• ✅ OTLPLogHandler - Export logs via OpenTelemetry Protocol
• ✅ Environment-based configuration (MELLEA_LOGS_ENABLED, MELLEA_LOGS_OTLP, MELLEA_LOGS_CONSOLE)
• ✅ Console handler control (enable/disable)
• ✅ Integration with existing FancyLogger
• ✅ Graceful degradation when OpenTelemetry not installed

Environment Variables (MVP):

MELLEA_LOGS_ENABLED=true          # Master switch
MELLEA_LOGS_OTLP=true             # Enable OTLP export
MELLEA_LOGS_CONSOLE=false         # Disable console (default: true)
OTEL_EXPORTER_OTLP_LOGS_ENDPOINT  # Logs-specific endpoint (optional)
OTEL_EXPORTER_OTLP_ENDPOINT       # Shared endpoint (fallback)
OTEL_SERVICE_NAME=mellea          # Service name

Rationale: Solves primary user pain point (logs buried in console). Users can search/filter logs in observability UI.

Phase 2: Enhanced Handlers & Configuration ⏸️ (Deferred)

Remaining features from original issue:

1. RotatingFileHandler - File output with rotation

   • Environment variables:
     • MELLEA_LOG_FILE=/path/to/logs/mellea.log
     • MELLEA_LOG_FILE_MAX_BYTES=10485760 (default: 10MB)
     • MELLEA_LOG_FILE_BACKUP_COUNT=5 (default: 5)

2. Enhanced configure_logging() function

   • Centralized configuration
   • Multiple simultaneous handlers
   • Per-handler format configuration (JSON vs human-readable)

3. Enhanced webhook handler

   • Replace FLOG env var with MELLEA_LOG_WEBHOOK=http://endpoint
   • Retry logic and batch sending

4. Trace context and Mellea context integration (blocked by Create a custom logging.Filter that automatically extracts the current OpenTelemetry trace context and injects trace_id and span_id into every log record #458 and Implement a contextvars-based system to carry session_id, request_id, model_id, and sampling_iteration through async flows #459)

   • Automatic trace_id/span_id injection (requires Create a custom logging.Filter that automatically extracts the current OpenTelemetry trace context and injects trace_id and span_id into every log record #458)
   • Session/request/model context propagation (requires Implement a contextvars-based system to carry session_id, request_id, model_id, and sampling_iteration through async flows #459)
   • All handlers receive trace and context data via filters

Why deferred:

• MVP solves primary user need (logs in observability backend)
• File rotation not critical for initial release
• Trace/context integration blocked by prerequisite issues Create a custom logging.Filter that automatically extracts the current OpenTelemetry trace context and injects trace_id and span_id into every log record #458 and Implement a contextvars-based system to carry session_id, request_id, model_id, and sampling_iteration through async flows #459
• Can be added incrementally without breaking changes

Phase 2 Acceptance Criteria:

• File handler with rotation support
• Multiple handlers active simultaneously
• Per-handler format configuration
• Enhanced webhook handler with MELLEA_LOG_WEBHOOK
• All handlers receive trace context (after Create a custom logging.Filter that automatically extracts the current OpenTelemetry trace context and injects trace_id and span_id into every log record #458)
• All handlers receive Mellea context (after Implement a contextvars-based system to carry session_id, request_id, model_id, and sampling_iteration through async flows #459)

[ajbozarth]

I have the MVP work done and ready locally, but due to issues with the docs being built on top of #610 I was not able to commit it to main without lots of git conflict issues. So I will open a PR once that PR is merged and I can rebase the branch

[ajbozarth]

#635 has merged including the Phase 1 MVP. I will come back to this for Phase 2 once I've finished the previous sub-issues.