Enhanced Logging System Implementation Guide

July 30, 2026 · View on GitHub

Version 1.0.0 · MythosMUD · 2026-07-30

AI READING INSTRUCTION

Read [SPEC] and [BUG] blocks for authoritative facts. Read [NOTE] only if additional context is needed. [?] blocks are unverified — treat with lower confidence.

1. Overview

[SPEC]

Canonical living logging guide for MythosMUD (consolidates former best-practices and quick-ref docs)
Import: from server.structured_logging.enhanced_logging_config import get_logger
Never use import logging / logging.getLogger() for server code
Prefer structured key-value fields; never f-string log messages

[NOTE] The MythosMUD server features an enhanced logging system that addresses anti-patterns and security issues from earlier logging. Former LOGGING_BEST_PRACTICES.md and LOGGING_QUICK_REFERENCE.md were archived; pointers remain at those paths.

2. 🔧 What Was Implemented

[SPEC]

High Priority Items (Completed)

1. Fixed Context Parameter Usage ✅

Problem: Incorrect usage of context= parameter in logger calls

Solution: Updated all 26 files to use proper structured logging

Migration: Automated migration script updated the entire codebase

2. Implemented MDC (Mapped Diagnostic Context) ✅

Location: server/logging/enhanced_logging_config.py

Features:

Context variables automatically included in all log entries
Request-scoped context binding
Thread-safe context management

3. Added Correlation IDs for Request Tracing ✅

Location: server/middleware/correlation_middleware.py

Features:

Automatic correlation ID generation
HTTP header support (X-Correlation-ID)
WebSocket correlation support
Request context propagation

4. Implemented Security Sanitization ✅

Location: server/logging/enhanced_logging_config.py

Features:

Automatic sensitive data redaction
Configurable sensitive key patterns
Recursive dictionary sanitization

Medium Priority Items (Completed)

5. Performance Optimization with Async Logging ✅

Location: server/monitoring/performance_monitor.py

Features:

Async log processing
Performance metrics collection
Background thread processing
Queue-based log handling

6. Enhanced Error Handling with Structured Logging ✅

Location: server/utils/enhanced_error_logging.py

Features:

Structured error logging
Enhanced context creation
Third-party exception wrapping
Performance metric logging

7. Log Aggregation and Centralized Collection ✅

Location: server/logging/log_aggregator.py

Features:

Centralized log collection
Real-time log processing
Export capabilities (JSON, CSV)
Statistics and analytics

8. Monitoring Integration with Metrics ✅

Location: server/monitoring/monitoring_dashboard.py

Features:

Comprehensive system health monitoring
Alert system with configurable thresholds
Performance metrics dashboard
System recommendations

Low Priority Items (Completed)

9. Error Tracking with 100% Exception Context ✅

Location: server/monitoring/exception_tracker.py

Features:

Complete exception tracking
Full context preservation
Exception statistics
Handler system for custom processing

3. 🚀 How to Use the Enhanced System

[NOTE]

Basic Usage

from server.logging.enhanced_logging_config import get_logger

# Get a logger (automatically includes MDC context)

logger = get_logger(__name__)

# Structured logging (no more context= parameter!)

logger.info("User action completed", user_id="123", action="login", success=True)
logger.error("Database connection failed", error=str(e), database="players")

Request Context Binding

from server.logging.enhanced_logging_config import bind_request_context, clear_request_context

# At the start of a request

bind_request_context(
    correlation_id="req-123",
    user_id="user-456",
    session_id="session-789"
)

# All subsequent log calls automatically include this context

logger.info("Processing request")  # Includes correlation_id, user_id, session_id

# At the end of the request

clear_request_context()

Enhanced Error Handling

from server.utils.enhanced_error_logging import log_and_raise_enhanced

# Enhanced error logging with full context

log_and_raise_enhanced(
    ValidationError,
    "Invalid player data provided",
    details={"field": "name", "value": player_name},
    user_friendly="Please provide a valid player name"
)

Performance Monitoring

from server.monitoring.performance_monitor import measure_performance

# Automatic performance measurement

with measure_performance("database_query", metadata={"table": "players"}):
    result = database.query("SELECT * FROM players")

Exception Tracking

from server.monitoring.exception_tracker import track_exception

# Track exceptions with full context

try:
    risky_operation()
except Exception as e:
    track_exception(
        e,
        user_id=current_user.id,
        correlation_id=request.correlation_id,
        severity="error",
        handled=True
    )

4. 🔧 Configuration

[NOTE]

Enhanced Logging Setup

from server.logging.enhanced_logging_config import setup_enhanced_logging

# Configure enhanced logging

config = {
    "logging": {
        "environment": "production",
        "level": "INFO",
        "enable_async": True,
        "log_base": "logs"
    }
}

setup_enhanced_logging(config)

ℹ️ Idempotent setup – setup_enhanced_logging configures handlers once per process. Subsequent calls are ignored unless you pass force_reconfigure=True.

Logging Exceptions Only Once

Use log_exception_once to avoid duplicate log entries when exceptions are re-raised through the catacombs of control flow:

from server.logging.enhanced_logging_config import get_logger, log_exception_once

logger = get_logger("server.combat.resolver")

try:
    resolve_combat_round()
except MythosMUDError as exc:
    log_exception_once(
        logger,
        "error",
        "Combat round failed",
        exc=exc,
        encounter_id=encounter.id,
    )
    raise

Monitoring Dashboard

from server.monitoring.monitoring_dashboard import get_monitoring_dashboard

# Get system health

dashboard = get_monitoring_dashboard()
health = dashboard.get_system_health()
print(f"System status: {health.status}")
print(f"Performance score: {health.performance_score}")

5. 📊 Monitoring Endpoints

[SPEC] The enhanced system provides several monitoring endpoints:

/health - System health check
/metrics - System metrics export
/monitoring/summary - Comprehensive monitoring summary
/monitoring/alerts - System alerts
/monitoring/alerts/{alert_id}/resolve - Resolve alerts

6. 🔒 Security Features

[NOTE]

Automatic Data Sanitization

The system automatically redacts sensitive information:

# This will be automatically sanitized

logger.info("User login", password="secret123", token="abc123")
# Output: User login password=[REDACTED] token=[REDACTED]

Configurable Sensitive Keys

# Add custom sensitive keys

sensitive_keys = [
    'password', 'token', 'secret', 'key', 'credential', 'auth',
    'jwt', 'api_key', 'private_key', 'session_token', 'access_token'
]

7. 📈 Performance Benefits

[SPEC] Async Processing: Background log processing reduces I/O blocking

Context Variables: Efficient context propagation without parameter overhead

Structured Data: Better parsing and analysis capabilities

Correlation IDs: Easy request tracing and debugging

Aggregation: Centralized log collection and analysis

8. 🧪 Testing

[NOTE]

Running Tests

# Test the enhanced logging system

python -m pytest server/tests/test_enhanced_logging.py

# Test monitoring components

python -m pytest server/tests/test_monitoring.py

Migration Verification

# Verify migration was successful

python server/scripts/migrate_to_enhanced_logging.py

9. 🚨 Migration Notes

[SPEC]

Breaking Changes

Context Parameter: The context= parameter is no longer supported
Import Changes: Some logging imports have been updated
Logger Creation: Use get_logger() from enhanced_logging_config

Backward Compatibility

Old log files remain readable

Existing log formats are preserved
Gradual migration is supported

10. 🔮 Future Enhancements

[SPEC]

Planned Features

Log Shipping: Integration with external log aggregation services
Advanced Analytics: Machine learning-based log analysis
Real-time Dashboards: Web-based monitoring interfaces
Custom Processors: Domain-specific log processing
Compliance Features: GDPR/COPPA compliance logging

Integration Opportunities

Prometheus: Metrics export for Prometheus monitoring
Grafana: Dashboard integration for visualization
ELK Stack: Elasticsearch, Logstash, Kibana integration
Sentry: Error tracking and alerting integration

11. 📚 Documentation References

[SPEC] Structlog Documentation

12. 🤝 Contributing

[SPEC] When contributing to the logging system:

Use structured logging with proper context
Include correlation IDs in all log entries
Follow the security sanitization guidelines
Add performance monitoring where appropriate
Update tests for any logging changes

13. 🆘 Troubleshooting

[NOTE]

Common Issues

Import Errors: Ensure you're importing from enhanced_logging_config
Context Issues: Use bind_request_context() for request-scoped logging
Performance: Enable async logging for better performance
Memory Usage: Monitor log aggregation memory usage

Debug Mode

# Enable debug logging

config = {
    "logging": {
        "level": "DEBUG",
        "enable_async": False  # Disable async for debugging
    }
}

As noted in the Pnakotic Manuscripts, proper documentation and understanding of our systems is essential for maintaining their stability and observability. The enhanced logging system provides the foundation for comprehensive system monitoring and debugging.

14. Changelog

[SPEC]

Version	Date	Change
1.0.0	2026-07-30	Initial HADS structural conversion