Aniworld/docs/logging_implementation_summary.md

Logging Implementation Summary

What Was Implemented

1. Core Logging Infrastructure (src/infrastructure/logging/)

• logger.py: Main logging configuration module

  • setup_logging(): Configures both console and file handlers
  • get_logger(): Retrieves logger instances for specific modules
  • Follows Python logging best practices with proper formatters

• uvicorn_config.py: Uvicorn-specific logging configuration

  • Custom logging configuration dictionary for uvicorn
  • Ensures uvicorn logs are captured in both console and file
  • Configures multiple loggers (uvicorn, uvicorn.error, uvicorn.access, aniworld)

• __init__.py: Package initialization

  • Exports public API: setup_logging, get_logger, get_uvicorn_log_config

2. FastAPI Integration

Updated src/server/fastapi_app.py to:

• Import and use the logging infrastructure
• Call setup_logging() during application startup (in lifespan())
• Replace all print() statements with proper logger calls
• Use lazy formatting (logger.info("Message: %s", value))

3. Startup Scripts

• run_server.py: Python startup script

  • Uses the custom uvicorn logging configuration
  • Recommended way to start the server

• start_server.sh: Bash startup script

  • Wrapper around run_server.py
  • Made executable with proper shebang

4. Documentation

• docs/logging.md: Comprehensive logging guide
  • How to run the server
  • Log file locations
  • Log format examples
  • Troubleshooting guide
  • Programmatic usage examples

Log Outputs

Console Output

INFO:     Starting FastAPI application...
INFO:     Loaded anime_directory from config: /home/lukas/Volume/serien/
INFO:     Server running on http://127.0.0.1:8000
INFO:     API documentation available at http://127.0.0.1:8000/api/docs

File Output (logs/fastapi_app.log)

2025-10-25 17:31:19 - aniworld - INFO - ============================================================
2025-10-25 17:31:19 - aniworld - INFO - Logging configured successfully
2025-10-25 17:31:19 - aniworld - INFO - Log level: INFO
2025-10-25 17:31:19 - aniworld - INFO - Log file: /home/lukas/Volume/repo/Aniworld/logs/fastapi_app.log
2025-10-25 17:31:19 - aniworld - INFO - ============================================================
2025-10-25 17:31:19 - aniworld - INFO - Starting FastAPI application...
2025-10-25 17:31:19 - aniworld - INFO - Loaded anime_directory from config: /home/lukas/Volume/serien/
2025-10-25 17:31:19 - src.core.SeriesApp - INFO - Initializing SeriesApp...
2025-10-25 17:31:19 - src.core.SerieScanner - INFO - Initialized SerieScanner...
2025-10-25 17:31:19 - aniworld - INFO - SeriesApp initialized with directory: /home/lukas/Volume/serien/
2025-10-25 17:31:19 - aniworld - INFO - FastAPI application started successfully
2025-10-25 17:31:19 - aniworld - INFO - Server running on http://127.0.0.1:8000
2025-10-25 17:31:19 - aniworld - INFO - API documentation available at http://127.0.0.1:8000/api/docs

How to Use

Starting the Server

Recommended:

conda run -n AniWorld python run_server.py

Alternative:

./start_server.sh

View logs in real-time:

tail -f logs/fastapi_app.log

In Code

from src.infrastructure.logging import get_logger

logger = get_logger(__name__)

logger.info("Message: %s", value)
logger.warning("Warning: %s", warning_msg)
logger.error("Error occurred", exc_info=True)

Configuration

Set log level via environment variable or .env file:

export LOG_LEVEL=INFO  # or DEBUG, WARNING, ERROR

Features

✅ Console logging: Colored, easy-to-read format
✅ File logging: Detailed with timestamps and logger names
✅ Automatic log directory creation: logs/ created if missing
✅ Uvicorn integration: All uvicorn logs captured
✅ Multiple loggers: Different loggers for different modules
✅ Configurable log level: Via environment variable
✅ Proper formatting: Uses lazy formatting for performance
✅ Startup/shutdown logging: Clear application lifecycle logs
✅ Error tracebacks: Full exception context with exc_info=True

Files Created/Modified

Created:

• src/infrastructure/logging/logger.py
• src/infrastructure/logging/uvicorn_config.py
• src/infrastructure/logging/__init__.py
• run_server.py
• start_server.sh
• docs/logging.md
• docs/logging_implementation_summary.md (this file)

Modified:

• src/server/fastapi_app.py: Integrated logging throughout

Testing

The implementation has been tested and verified:

• ✅ Log file created at logs/fastapi_app.log
• ✅ Startup messages logged correctly
• ✅ Application configuration loaded and logged
• ✅ Uvicorn logs captured
• ✅ File watching events logged
• ✅ Shutdown messages logged

Next Steps

Consider adding:

1. Log rotation: Use RotatingFileHandler to prevent log files from growing too large
2. Structured logging: Use structlog for JSON-formatted logs
3. Log aggregation: Send logs to a centralized logging service
4. Performance monitoring: Add timing logs for slow operations
5. Request logging middleware: Log all HTTP requests/responses