feat: Add comprehensive logging system with console and file output
- 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
This commit is contained in:
155
docs/logging.md
Normal file
155
docs/logging.md
Normal file
@@ -0,0 +1,155 @@
|
||||
# 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)
|
||||
169
docs/logging_implementation_summary.md
Normal file
169
docs/logging_implementation_summary.md
Normal file
@@ -0,0 +1,169 @@
|
||||
# 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:**
|
||||
|
||||
```bash
|
||||
conda run -n AniWorld python run_server.py
|
||||
```
|
||||
|
||||
**Alternative:**
|
||||
|
||||
```bash
|
||||
./start_server.sh
|
||||
```
|
||||
|
||||
**View logs in real-time:**
|
||||
|
||||
```bash
|
||||
tail -f logs/fastapi_app.log
|
||||
```
|
||||
|
||||
### In Code
|
||||
|
||||
```python
|
||||
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:
|
||||
|
||||
```bash
|
||||
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
|
||||
Reference in New Issue
Block a user