# 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)