Skip to content

Logging

This section explains how logging works , where logs go , what gets logged , and how to debug production issues safely in Replimatic.

1. Logging Philosophy

Replimatic follows these principles:

  1. Application-level logging first (Django + Celery)
  2. Structured, readable logs (timestamps, level, source, line number)
  3. File-based logs inside container
  4. Docker handles rotation at infra level
  5. No sensitive data logged
  6. Errors are always logged with traceback

2. Logging Layers Overview

Layer Purpose
Django Logging Business logic, requests, errors
Celery Logging Background jobs, retries, failures
Payment Logs Payment success/failure tracking
Support Logs Support workflow visibility
Infrastructure Logs Container & Nginx level

3. Django Logging Configuration

Defined in:

replimatic/settings/base.py

Active Loggers

  • root logger → captures most logs
  • celery logger → Celery-specific logs

Log Format

[2026-01-05 12:30:22] INFO users.views 134 Profile updated

Includes:

  • Timestamp
  • Log level
  • Module name
  • Line number
  • Message

4. Log Handlers

4.1 Main Application Log

File

logs/django.log

Purpose

  • Request lifecycle
  • Business logic logs
  • Celery info logs
  • Payment processing logs

Rotation

  • Max size: 5 MB
  • Backup files: 3
  • Old logs auto-rotated

4.2 Error Log

File

logs/errors.log

Purpose

  • Unhandled exceptions
  • Payment failures
  • Webhook verification failures
  • Celery task crashes

Rotation

  • Max size: 5 MB
  • Backup files: 4

5. What Is Logged (By Category)

5.1 Authentication & User Actions

Logged:

  • Login attempts (success/failure)
  • Password changes
  • Email verification events

Not logged:

  • Passwords
  • Tokens
  • OAuth secrets

5.2 Payments (Critical)

Logged events:

  • Order creation
  • Payment success
  • Payment failure
  • Webhook verification failure
  • Refund processing

Example:

INFO Payment processed successfully
ERROR Failed to generate S3 signed download URL

This is intentionally verbose to help with financial audits.

5.3 Support System

Logged:

  • Support request creation
  • Status transitions
  • Telegram notification failures

Why:

Support workflows are multi-step and asynchronous , so logs act as an audit trail.

5.4 Celery Tasks

Logged:

  • Task start
  • Retry attempts
  • Final success/failure

Examples:

  • Database backup task
  • Email sending task
  • Telegram notification task

Retries are automatically logged by Celery.

6. Celery Logging Behavior

Celery uses the same logging system as Django.

Worker Logs

make prod-celery-logs

Beat Logs

make prod-celery-beat-logs

Celery respects:

CELERY_WORKER_HIJACK_ROOT_LOGGER = False

This prevents Celery from breaking Django log formatting.

7. Docker & Log Access

View Django logs

make prod-logs

View container logs directly

docker logs replimatic_app

Tail error logs

docker exec -it replimatic_app tail -f logs/errors.log

8. Nginx Logging

Handled outside Django .

Default:

/var/log/nginx/access.log /var/log/nginx/error.log

Used for:

  • Traffic analysis
  • SSL issues
  • Proxy failures

Application errors do NOT rely on Nginx logs .

9. What Is Intentionally NOT Logged

For security & compliance:

  • Passwords
  • OAuth tokens
  • Payment card details
  • API secrets
  • Session cookies
  • Raw webhook payloads

Only metadata is logged.

10. Production Debugging Workflow

Scenario: Payment Failed

  1. Check errors.log
  2. Check webhook logs
  3. Check Celery worker logs
  4. Verify provider dashboard

Scenario: Background task not running

  1. Check Celery worker container
  2. Check Redis connectivity
  3. Check errors.log
  4. Check retry exhaustion

Scenario: File download broken

  1. Check S3 signed URL generation logs
  2. Verify bucket permissions
  3. Check settings.DEBUG

11. Log Retention Strategy

Current:

  • File rotation inside container
  • Docker handles container lifecycle

Recommended for scale:

  • Ship logs to external service (optional)
  • Centralized log aggregation

Not required for MVP / early SaaS.

12. Safe Logging Guidelines (For Customization)

When adding logs:

logger.info("Meaningful message", extra={...})

Never:

logger.info(user.password)

Always:

  • Log intent
  • Log identifiers (IDs)
  • Log failures with traceback

13. Logging Summary

Area Status
Django logs ✅ Enabled
Error logs ✅ Separate
Celery logs ✅ Integrated
Rotation ✅ Enabled
Sensitive data ❌ Not logged
Production ready ✅ Yes