# Logging Instructions

This document describes how to write and refactor logging across the AniWorld codebase to make logs **human-readable**, **debug-friendly**, and **noise-free**.

> ✅ Goal: Logs should help a developer understand what happened, why it happened, and what to inspect next — without overwhelming them with duplicates or irrelevant details.

---

## 1. Principles for Great Logs

### 1.1 Use the Right Log Level

- `DEBUG`: Detailed internal state useful when debugging a specific issue (e.g., decision points, returned values, request/response payloads). Not for normal operation.
- `INFO`: High-level events that represent what the system is doing (e.g., "Import started", "New series added", "Config reloaded"). Use sparingly.
- `WARNING`: Something unexpected happened, but the system can continue (e.g., missing optional file, fallback behavior).
- `ERROR`: An operation failed and needs attention (e.g., exception caught, failed database write).
- `CRITICAL`: The system is in an unusable state (e.g., config corruption, failed startup).

### 1.2 Keep Logs Human-Readable

- Write messages in a clear, descriptive sentence-style format.
- Avoid cryptic codes or single-word log messages.
- Prefer `logger.debug("... %s", value)`-style formatting over f-strings to avoid unnecessary work when the log level is disabled.

### 1.3 Avoid Log Spam

- Don’t log inside hot loops unless you explicitly aggregate and log a summary (e.g., "Processed 124 files, 3 failures").
- Avoid repeated/logging the same event at the same level (e.g., do not log "Retrying" 10 times at INFO; log once at INFO and then use DEBUG for each retry).
- Use rate limiting or debounce patterns for logs that can fire rapidly (e.g., external service health checks).
- Prefer a single higher-level log with context rather than many low-level logs that clutter output.

### 1.4 Log Objects Usefully

- When logging objects, log the minimal useful representation (e.g., ID, name, status) rather than the full object or its memory address.
- If an object has a `.dict()`, `.to_dict()`, or `.as_dict()` helper (common in Pydantic models), log that rather than relying on `repr()`.
- Add a `__repr__` or `__str__` implementation to domain models that returns a helpful, concise string with key identifiers.
- Use structured logging (e.g., `logger.info("Series added", extra={"series_id": series.id, "title": series.title})`) where supported.
- For exceptions, prefer `logger.exception("Failed to ...")` to capture stack traces.

---

## 2. Refactoring Existing Logs

When improving or refactoring existing log statements, aim to make them:

- **Actionable**: A developer reading the log should know what happened and what to check next.
- **Non-redundant**: Remove duplicates and ensure only one log records the same high-level event at a given level.
- **Context-rich**: Include identifiers (e.g., `series_id`, `file_path`, `user_id`) and key state that explains why a decision was made.
- **Level-appropriate**: Downgrade noisy INFO logs to DEBUG, and elevate critical failures to ERROR/CRITICAL.

### 2.1 Refactor Checklist

1. **Locate noisy logs**: Search for repeated messages (e.g., "Start", "Done") and determine whether they should be DEBUG or removed.
2. **Replace ad-hoc prints**: Remove `print()` statements or `print(obj)` and replace with `logger.*` calls.
3. **Use structured context**: If a function logs multiple related messages, include the same context in each (e.g., `extra={"series_id": series.id}`) or use a context manager that attaches it.
4. **Validate object output**: Ensure any logged object produces a useful representation (add methods or translate to dict). If not, log the key fields explicitly.
5. **Batch repetitive events**: If a loop logs per item, consider collecting stats and logging a summary at the end.

## 3. Adding New Logs

When adding logs to new code paths:

- Log **important state transitions** (e.g., "Queue started", "Download completed", "Config reloaded").
- For error paths, include what failed and why (e.g., "Could not load config from X: {exc}").
- Prefer logging at the boundaries of operations, not deep inside utility functions unless it aids debugging.
- Write logs in full sentences, with a clear subject, verb, and object.

---

## 4. Example Patterns

```python
logger.info("Import completed", extra={"series_id": series.id, "count": len(imported)})

logger.debug(
    "Fetched feed items",
    extra={"feed_url": feed.url, "item_count": len(items)},
)

try:
    result = download_episode(episode)
except Exception:
    logger.exception("Failed to download episode %s", episode.id)
```

> 💡 When in doubt, favor **fewer, richer logs** over many noisy logs.

---

## 5. Logging Audit Task List

For a guided checklist of files and logging improvements, see **`docs/tasks.md`**. This is where we track which files have been reviewed and which logging items still need attention.

> ✅ After applying the guidelines above, update `docs/tasks.md` to indicate which tasks are complete.