igny8/master-docs/50-infra/LOGGING-AND-MONITORING.md

Logging and Monitoring

Purpose

Explain runtime logging, request tracing, and resource tracking implemented in code, plus where logs are written.

Code Locations (exact paths)

• Django logging config: backend/igny8_core/settings.py (LOGGING, PUBLISH_SYNC_LOG_DIR)
• Request ID middleware: backend/igny8_core/middleware/request_id.py
• Resource tracking middleware: backend/igny8_core/middleware/resource_tracker.py
• Publish/sync logging categories: publish_sync, wordpress_api, webhooks loggers in settings.py

High-Level Responsibilities

• Attach request IDs to each request/response for traceability.
• Optionally track CPU/memory/I/O per request for authenticated admin/developer users.
• Persist publish/sync logs to rotating files and console.

Detailed Behavior

• Request ID:
  • RequestIDMiddleware assigns a UUID per request; adds header X-Request-ID (exposed via CORS x-resource-tracking-id).
• Resource tracking:
  • ResourceTrackingMiddleware measures CPU/memory/I/O deltas per request for authenticated admin/developer users; stores metrics in cache; can be toggled via custom header x-debug-resource-tracking.
• Logging configuration (settings.py):
  • Log directory: logs/publish-sync-logs (auto-created).
  • Handlers: console + rotating file handlers (10 MB, 10 backups) for publish_sync.log, wordpress-api.log, webhooks.log.
  • Formatters: verbose general formatter; publish_sync formatter with timestamp/level/message.
  • Loggers: publish_sync, wordpress_api, webhooks all INFO level, non-propagating.
• Static files and general Django logging fall back to default console (not customized beyond above).

Data Structures / Models Involved (no code)

• None; logging is operational.

Execution Flow

• Incoming request → RequestIDMiddleware → AccountContextMiddleware → ResourceTrackingMiddleware → view.
• Views/services log using standard logging.getLogger('publish_sync') etc.; output to console and rotating files.

Cross-Module Interactions

• WordPress integration and publish flows should log to wordpress_api/publish_sync to capture sync diagnostics.
• CORS exposes request ID header so frontend can correlate with logs.

State Transitions (if applicable)

• Log rotation occurs when files exceed 10 MB (backupCount 10).

Error Handling

• Logging failures fall back to console; middleware errors propagate via unified exception handler.

Tenancy Rules

• Request ID and resource tracking apply to all requests; data remains in application logs scoped by account within log content.

Billing Rules (if applicable)

• None.

Background Tasks / Schedulers (if applicable)

• Celery tasks can log using same loggers; no dedicated Celery handler configured beyond console.

Key Design Considerations

• Request ID early in middleware to ensure downstream logs include correlation ID.
• Resource tracking limited to privileged users to avoid overhead for all traffic.

How Developers Should Work With This Module

• Use named loggers (publish_sync, wordpress_api, webhooks) for relevant flows to keep logs organized.
• When adding new log domains, extend LOGGING in settings.py with dedicated handlers/formatters as needed.
• Surface request IDs in error responses to aid log correlation (already enabled via unified handler).