Aniworld/tasks.md

Logging Audit & Improvement Tasks

This tasks list is written for an AI agent to systematically rework and add logging across the AniWorld codebase. Each task includes a specific file and the intended logging improvement.

📌 Goal: Improve log clarity, reduce noise, ensure consistent structured context, and add missing logs for important events and failures.

How to execute these tasks

1. For each file in the list, open it and locate existing logger.* calls.
2. Ask:
   • Is the message actionable and human-readable?
   • Does it include key context (ids, names, paths, operation results)?
   • Is the level correct (DEBUG/INFO/WARNING/ERROR/CRITICAL)?
   • Are exceptions logged using logger.exception(...) or exc_info=True?
   • Are we avoiding log spam (e.g., loops, repeated messages)?
3. Add or adjust logs by:
   • Moving noisy INFO logs to DEBUG unless they represent important state changes.
   • Adding INFO-level logs at boundary points (entry/exit of operations, request endpoints).
   • Including structured extra={...} fields where helpful.
   • Logging minimal useful object representations (e.g., series.id, file_path).
4. Validate that changes do not expose secrets or PII in logs.
5. Follow the project logging style in docs/InstructionsLogging.md when drafting or refactoring log calls.

---

1) Core Logging Infrastructure

• src/infrastructure/logging/logger.py

  • Ensure the project has a single, consistent logging entry point for all modules.
  • Validate that logger names are consistent and allow per-module filtering.
  • Confirm structured logging support (extra/context fields) is correctly implemented.

• src/server/config/logging_config.py

  • Verify log format templates are clear, consistent, and include timestamp + level + module.
  • Make sure log level configuration is reliable and respects env/config.
  • Confirm file rotation, log file creation, and log handlers are configured properly.

• src/server/utils/logging.py

  • Confirm helper utilities for creating loggers and configuring log levels are correct.
  • Ensure default logger levels (download, security, performance) are clear and non-spammy.

• src/server/utils/log_manager.py

  • Review any dynamic log level changes and confirm they are safe and properly logged.

---

2) Startup & Runtime Lifecycle Logging

• src/server/fastapi_app.py

  • Refactor startup/shutdown logs to ensure each major step (db init, service initialization, background tasks) is logged at an appropriate level.
  • Add missing context (e.g., which service or component is starting/stopping) in the messages.
  • Ensure exceptions are logged via logger.exception(...) where appropriate.

• src/server/services/initialization_service.py

  • Add logs for key initialization steps and failures.

• src/server/services/cache_service.py

  • Ensure cache hits/misses (if relevant) are logged at DEBUG and errors are logged at WARNING/ERROR.

• src/server/services/notification_service.py

  • Add logs for notification events and failures.

---

3) API / Controller Logging

• src/server/api/anime.py
• src/server/api/nfo.py
• src/server/api/config.py
• src/server/api/health.py
• src/server/api/scheduler.py
• src/server/api/logging.py
• src/server/api/websocket.py

For each API module:

• Ensure each endpoint logs at INFO when invoked (at least the route and key identifiers).
• Add DEBUG logs for important steps inside handlers (data validation, service calls, responses) without spamming.
• Ensure errors/exceptions are logged with stack traces.

---

4) Middleware and Error Handling

• src/server/middleware/error_handler.py

  • Make sure handled exceptions are logged appropriately.
  • Avoid logging the same error multiple times at the same level.

• src/server/middleware/security.py

  • Ensure security-related events (auth failures, suspicious activity) are logged at WARNING/ERROR with context.

---

5) Database & Transaction Logging

• src/server/database/connection.py

  • Log key connection lifecycle events and failures.

• src/server/database/init.py

  • Ensure DB initialization steps are logged.

• src/server/database/service.py

  • Review logs for CRUD operations on series and episodes.
  • Confirm that success logs include ids and key values.
  • Ensure exceptions are logged with full context.

• src/server/database/system_settings_service.py

  • Confirm logs for scan completion/reset are accurate and not noisy.

• src/server/database/transaction.py

  • Ensure transaction start/commit/rollback logs are DEBUG, and warnings/errors for failures are logged.
  • Confirm savepoint logs include savepoint names.

---

6) Background Services & Worker Logging

• src/server/services/background_loader_service.py

  • Add/info logs for job start/completion, and any batch summaries.

• src/server/services/scheduler_service.py

  • Ensure job scheduling, execution, and failure are logged.

• src/server/services/download_service.py

  • Add informative logs for downloads (start, success, failure, retry).

• src/server/services/queue_repository.py

  • Ensure queue operations are logged at suitable levels (DEBUG for enqueue/dequeue, WARNING for errors).

• src/server/services/progress_service.py

  • Add logs for progress updates and any errors.

• src/server/services/scan_service.py

  • Add logs for scan start/completion, skipped items, and failures.

• src/server/services/anime_service.py

  • Ensure high-level operations (create/update/delete) are logged with identifiers.

• src/server/services/websocket_service.py

  • Add logs for connection/disconnection events and key message paths.

---

7) Server Utilities & Helpers

• src/server/utils/dependencies.py

  • Ensure dependency injections and resource retrievals are logged at DEBUG when there is failure.

• src/server/utils/error_tracking.py

  • Verify errors are logged with context and stack trace.

• src/server/utils/metrics.py

  • Ensure metrics collection failures are logged appropriately.

• src/server/utils/system.py

  • Add logs for system-level operations (memory, disk checks) if missing.

• src/server/utils/template_helpers.py

  • Add logs for template rendering errors.

---

8) Core Application Logging

• src/core/SeriesApp.py
• src/core/SerieScanner.py

For core application logic:

• Ensure key events (scan start/end, errors, decisions) are logged at correct level, and logs are not too noisy when scanning large directories.

---

9) Providers / Integration Logging

• src/core/providers/aniworld_provider.py
• src/core/providers/enhanced_provider.py
• src/core/providers/monitored_provider.py
• src/core/providers/failover.py
• src/core/providers/config_manager.py
• src/core/providers/health_monitor.py

For provider modules:

• Ensure failures / retries / fallbacks are logged at WARNING or ERROR with context.
• Log important state changes at INFO (e.g., provider enabled/disabled).

---

10) Core Services / Utility Logging

• src/core/services/nfo_service.py
• src/core/services/nfo_factory.py
• src/core/services/nfo_repair_service.py
• src/core/services/series_manager_service.py
• src/core/services/tmdb_client.py

Ensure all operations that can fail or produce important output are logged with enough context (series id/name, operation result, duration).

• src/core/utils/nfo_generator.py
• src/core/utils/nfo_mapper.py
• src/core/utils/image_downloader.py

Ensure any external calls (HTTP, file I/O) and failures are logged with reasons.

---

11) CLI & Scripts

• src/cli/nfo_cli.py

  • Ensure startup logs are concise; reduce repetitive output; group statistics.

• Docker/test_vpn.py

  • Ensure logging is clear and not too verbose (especially in loops).

---

12) Tests (Verify Logging Behavior)

• tests/unit/test_infrastructure_logger.py
• tests/unit/test_logging.py
• tests/unit/test_nfo_update_parsing.py
• tests/unit/test_parallel_anime_add.py
• tests/api/test_concurrent_anime_add.py
• tests/performance/test_nfo_batch_performance.py
• tests/performance/test_websocket_load.py
• tests/security/test_encryption_security.py

Tasks:

• Ensure log capture/formatting tests are up to date.
• Add tests to validate that key operations log at expected levels (INFO/DEBUG/ERROR) and include required context.

---

13) Follow-up Tasks (Post-Refactor)

1. Run the full test suite to confirm logging changes do not break assertions.
2. Verify logs during normal runs are not overly noisy; tune log levels accordingly.
3. Ensure deployment/production log behavior matches expectations (rotate logs, preserve errors, and hide debug output).

---

14) Full Python File Inventory (excluding tests)

Below is the complete list of all .py files in the repo (excluding anything under tests/).

14a) Mutable logging tasks (edit these files)

These are files where logging should be added/updated as part of the audit.

• Docker/test_vpn.py – Review logging clarity, avoid verbose loops, and ensure errors are logged with context.
• run_server.py – Ensure server startup logs (and any error paths) have clear context and use proper log levels.
• src/cli/nfo_cli.py – Confirm CLI output is logged appropriately with summary reporting.
• src/config/settings.py – Ensure config parsing failures are logged and invalid values are handled or reported.
• src/core/entities/nfo_models.py – Add logs for model validation errors or unexpected data.
• src/core/entities/SerieList.py – Ensure list operations and conversions log useful identifiers.
• src/core/entities/series.py – Log key series state changes and validation failures.
• src/core/error_handler.py – Ensure caught errors are logged and propagated correctly.
• src/core/exceptions/Exceptions.py – Validate exception definitions support useful logging messages.
• src/core/interfaces/callbacks.py – Log callback errors or unexpected callback payloads.
• src/core/interfaces/providers.py – Ensure provider interface errors are logged clearly.
• src/core/providers/aniworld_provider.py – Add logs for API calls, retries, and failure reasons.
• src/core/providers/base_provider.py – Ensure base provider logs setup and teardown.
• src/core/providers/config_manager.py – Log config load/refresh and validation errors.
• src/core/providers/enhanced_provider.py – Review logging for error reporting and rate limiting.
• src/core/providers/failover.py – Ensure failover decisions and switchovers are logged.
• src/core/providers/health_monitor.py – Add logs for health-check results and degraded state.
• src/core/providers/monitored_provider.py – Ensure monitored provider metrics and errors are logged.
• src/core/providers/provider_config.py – Log config validation and defaulting behavior.
• src/core/providers/provider_factory.py – Ensure factory creation errors are logged with context.
• src/core/providers/streaming/Provider.py – Add logs for stream start/stop and errors.
• src/core/providers/streaming/voe.py – Log VOE fetch attempts and failures.
• src/core/SeriesApp.py – Confirm app lifecycle events and errors are logged.
• src/core/SerieScanner.py – Ensure scan start/end, skipped items, and errors are logged.
• src/core/services/nfo_factory.py – Log NFO generation steps and failures.
• src/core/services/nfo_repair_service.py – Ensure repair actions and failures are logged.
• src/core/services/nfo_service.py – Add logs for NFO operations and exceptions.
• src/core/services/series_manager_service.py – Log series management actions and key identifiers.
• src/core/services/tmdb_client.py – Ensure external API calls and failures are logged.
• src/core/utils/image_downloader.py – Add logs for download attempts, successes, and errors.
• src/core/utils/nfo_generator.py – Ensure generation steps and failures are logged.
• src/core/utils/nfo_mapper.py – Add logs for mapping failures and questionable data.
• src/infrastructure/logging/logger.py – Validate centralized logger behavior and structured logging support.
• src/infrastructure/logging/uvicorn_config.py – Ensure Uvicorn logging config is correct and includes context.
• src/infrastructure/security/config_encryption.py – Log encryption/decryption failures and warnings.
• src/infrastructure/security/database_integrity.py – Add logs for integrity check results and failures.
• src/infrastructure/security/file_integrity.py – Ensure file integrity checks log results and errors.
• src/server/api/anime.py – Confirm endpoints log requests, key params, and errors.
• src/server/api/auth.py – Ensure auth failures and token operations are logged.
• src/server/api/config.py – Add logs for config read/write and validation.
• src/server/api/download.py – Log download request lifecycle and errors.
• src/server/api/health.py – Ensure health checks log status and failure reasons.
• src/server/api/logging.py – Ensure log endpoint behavior is clear and properly logged.
• src/server/api/nfo.py – Add logs for NFO endpoint actions and errors.
• src/server/api/scheduler.py – Log scheduling actions, triggers, and failures.
• src/server/api/websocket.py – Ensure websocket connect/disconnect and message errors are logged.
• src/server/controllers/error_controller.py – Add logs for handled errors.
• src/server/controllers/page_controller.py – Add logs for page rendering errors.
• src/server/database/base.py – Ensure base DB operations log unexpected issues.
• src/server/database/connection.py – Add connection lifecycle and error logs.
• src/server/database/init.py – Ensure DB init steps are logged.
• src/server/database/models.py – Validate model validation errors are logged.
• src/server/database/service.py – Confirm CRUD operations log with context.
• src/server/database/system_settings_service.py – Ensure system settings actions log correctly.
• src/server/database/transaction.py – Verify transaction start/commit/rollback logging.
• src/server/fastapi_app.py – Review startup/shutdown and error logging.
• src/server/middleware/auth.py – Ensure auth middleware logs auth events and failures.
• src/server/middleware/error_handler.py – Confirm error handling logs exceptions clearly.
• src/server/middleware/security.py – Ensure security events are logged with context.
• src/server/middleware/setup_redirect.py – Add logs for redirect behavior and errors.
• src/server/models/anime.py – Ensure model validation errors are logged.
• src/server/models/auth.py – Confirm auth model logging for invalid data.
• src/server/models/config.py – Add logs for config model validation.
• src/server/models/download.py – Ensure download model failures are logged.
• src/server/models/nfo.py – Ensure NFO model issues are logged.
• src/server/models/websocket.py – Confirm websocket model errors are logged.
• src/server/services/anime_service.py – Ensure operations log relevant ids and results.
• src/server/services/auth_service.py – Add logs for auth operations and failures.
• src/server/services/background_loader_service.py – Ensure background jobs log start/stop and errors.
• src/server/services/cache_service.py – Confirm caching logs are sane and useful.
• src/server/services/config_service.py – Ensure config updates and errors are logged.
• src/server/services/download_service.py – Add download lifecycle logs.
• src/server/services/initialization_service.py – Confirm initialization steps are logged.
• src/server/services/notification_service.py – Ensure notification dispatch/failure logs exist.
• src/server/services/progress_service.py – Add progress update logs.
• src/server/services/queue_repository.py – Ensure queue operations are logged.
• src/server/services/scan_service.py – Confirm scan lifecycle and failure logging.
• src/server/services/scheduler_service.py – Ensure scheduler actions and failures are logged.
• src/server/services/websocket_service.py – Confirm websocket lifecycle and message errors are logged.
• src/server/utils/dependencies.py – Ensure dependency errors are logged.
• src/server/utils/error_tracking.py – Verify error tracking logs contain context.
• src/server/utils/filesystem.py – Add filesystem operation logs and errors.
• src/server/utils/logging.py – Ensure helper logging utilities behave as expected.
• src/server/utils/log_manager.py – Review dynamic log-level changes and logs.
• src/server/utils/media.py – Add logs for media operations and failures.
• src/server/utils/metrics.py – Ensure metric collection/logging failures are captured.
• src/server/utils/system.py – Add system-level operation logs and error handling.
• src/server/utils/template_helpers.py – Ensure template rendering errors are logged.
• src/server/utils/templates.py – Add logs for template loading and render errors.
• src/server/utils/validators.py – Ensure validation failures are logged appropriately.
• src/server/web/middleware/__init__.py – Verify middleware initialization logging.

14b) Reference / low-touch files (review only)

• src/core/__init__.py – Verify any module-level logging is appropriate.
• src/core/providers/__init__.py – Verify module-level logging is appropriate.
• src/infrastructure/logging/__init__.py – Confirm module exports and initialization logs are appropriate.
• src/infrastructure/security/__init__.py – Verify module-level logging is appropriate.
• src/server/api/__init__.py – Verify any module setup logging.
• src/server/config/__init__.py – Verify config initialization logging.
• src/server/controllers/__init__.py – Verify module import logging is non-spammy.
• src/server/database/__init__.py – Confirm any initialization logs.
• src/server/exceptions/__init__.py – Confirm module-level logging is appropriate.
• src/server/models/__init__.py – Verify any module init logs.
• src/server/utils/__init__.py – Confirm initialization logging is appropriate.
• src/server/web/middleware/__init__.py – Verify middleware initialization logging.

---

✅ Done: This tasks.md file enumerates each relevant source file and a clear instruction for how to improve or add logging in that file.