Lukas
94c53e9555
- Create logging infrastructure in src/infrastructure/logging/ - logger.py: Main logging setup with console and file handlers - uvicorn_config.py: Custom uvicorn logging configuration - __init__.py: Export public logging API - Update FastAPI application to use logging - Replace all print() statements with proper logger calls - Initialize logging during application startup - Add detailed startup/shutdown logging - Add startup scripts - run_server.py: Python script with uvicorn logging config - start_server.sh: Bash wrapper script - Add comprehensive documentation - docs/logging.md: User guide for logging system - docs/logging_implementation_summary.md: Technical implementation details Features: - Console logging with clean, readable format - File logging with timestamps to logs/fastapi_app.log - Configurable log level via LOG_LEVEL environment variable - Proper lazy formatting for performance - Captures all uvicorn, application, and module logs - Automatic log directory creation
156 lines
3.9 KiB
Markdown
156 lines
3.9 KiB
Markdown
# 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:
|
|
|
|
```bash
|
|
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)
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
./start_server.sh
|
|
```
|
|
|
|
### Option 3: Using uvicorn directly
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```python
|
|
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:
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
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)
|