Aniworld/docs/logging.md

Logging Configuration

This document describes the logging setup for the Aniworld FastAPI application.

Overview

The application uses Python's built-in logging module with both console and file output. All logs are written to:

• Console: Colored output for development
• Log File: logs/fastapi_app.log with detailed timestamps

Log Levels

By default, the application logs at INFO level. You can change this by setting the LOG_LEVEL environment variable:

export LOG_LEVEL=DEBUG  # More verbose
export LOG_LEVEL=INFO   # Default
export LOG_LEVEL=WARNING  # Less verbose
export LOG_LEVEL=ERROR  # Errors only

Or in your .env file:

LOG_LEVEL=INFO

Running the Server

Option 1: Using the run_server.py script (Recommended)

conda run -n AniWorld python run_server.py

This script uses the custom uvicorn logging configuration that ensures proper console and file logging.

Option 2: Using the shell script

./start_server.sh

Option 3: Using uvicorn directly

conda run -n AniWorld python -m uvicorn src.server.fastapi_app:app --host 127.0.0.1 --port 8000 --reload

Note: When using conda run, console output may not be visible in real-time. The logs will still be written to the file.

Log File Location

All logs are written to: logs/fastapi_app.log

To view logs in real-time:

tail -f logs/fastapi_app.log

Log Format

Console Output

INFO:     Starting FastAPI application...
INFO:     Server running on http://127.0.0.1:8000

File Output

2025-10-25 17:31:19 - aniworld - INFO - Starting FastAPI application...
2025-10-25 17:31:19 - aniworld - INFO - Server running on http://127.0.0.1:8000

What Gets Logged

The application logs:

• Startup/Shutdown: Application lifecycle events
• Configuration: Loaded settings and configuration
• HTTP Requests: Via uvicorn.access logger
• Errors: Exception tracebacks with full context
• WebSocket Events: Connection/disconnection events
• Download Progress: Progress updates for anime downloads
• File Operations: File creation, deletion, scanning

Logger Names

Different parts of the application use different logger names:

• aniworld: Main application logger
• uvicorn.error: Uvicorn server errors
• uvicorn.access: HTTP request logs
• src.core.SeriesApp: Core anime logic
• src.core.SerieScanner: File scanning operations
• src.server.*: Web API endpoints and services

Programmatic Usage

To use logging in your code:

from src.infrastructure.logging import get_logger

logger = get_logger(__name__)

logger.info("This is an info message")
logger.warning("This is a warning")
logger.error("This is an error", exc_info=True)  # Includes traceback

Log Rotation

Log files can grow large over time. Consider implementing log rotation:

# Archive old logs
mkdir -p logs/archived
mv logs/fastapi_app.log logs/archived/fastapi_app_$(date +%Y%m%d_%H%M%S).log

Or use Python's RotatingFileHandler (can be added to src/infrastructure/logging/logger.py).

Troubleshooting

No console output when using conda run

This is a known limitation of conda run. The logs are still being written to the file. To see console output:

1. Use the log file: tail -f logs/fastapi_app.log
2. Or run without conda: python run_server.py (after activating environment with conda activate AniWorld)

Log file not created

• Check that the logs/ directory exists (it's created automatically)
• Verify write permissions on the logs/ directory
• Check the LOG_LEVEL environment variable

Too much logging

Set a higher log level:

export LOG_LEVEL=WARNING

Missing logs

• Check that you're using the logger, not print()
• Verify the log level is appropriate for your messages
• Ensure the logger is properly configured (should happen automatically on startup)