awesome-audit-log-django 1.2.1

Per-model audit logs to TABLENAME_log with entry-point capture (HTTP/management/shell/celery)

Awesome Audit Log for Django

This is an awesome package to have your models logs in corresponding _log tables.

Having a single model/table as audit storage can cause heavy db operation and useless for large applications.

With this package you will have each model log in a separate table which can be beneficial if you want to truncate a specific model logs or run a query on them.

You can choose between having logs table in your default database or adding a new backend db as logs db.

Supported DBs to store logs:

1. PostgreSQL
2. MySQL
3. SQLite

This package is in its early stage development and the following features will be added ASAP:

1. Log rotation
2. Mongo DB support
3. Document page!

Compatible With

This package works on the below listed Django, Python versions and Databases.

• Django versions: 4.2, 5.0, 5.1
• Python versions: 3.10, 3.11, 3.12
• Databases: SQLite, PostgreSQL, MySQL
• Celery: Optional for Async logging

Installation

1. Add App

INSTALLED_APPS = [
    # ...
    'awesome_audit_log.apps.AwesomeAuditLogConfig',
]

2. Add Middleware

MIDDLEWARE = [
    # ...
    "awesome_audit_log.middleware.RequestEntryPointMiddleware",
]

3. Settings

AWESOME_AUDIT_LOG = {
    "ENABLED": True,
    "DATABASE_ALIAS": "default",
    # PostgreSQL schema for audit tables (defaults to 'public')
    "PG_SCHEMA": None,
    # Enable async logging with Celery (requires Celery to be installed and configured)
    "ASYNC": False,
    # "all" or list like ["app_label.ModelA", "app.ModelB"]
    "AUDIT_MODELS": "all",
    # like AUDIT_MODELS but for opt-out, useful when AUDIT_MODELS set to all
    "NOT_AUDIT_MODELS": None,
    "CAPTURE_HTTP": True,
    # Capture context for management commands
    "CAPTURE_COMMANDS": True,
    # Capture context for Celery tasks
    "CAPTURE_CELERY": True,
    # set to False means if audit db is unavailable, silently skip logging (with a warning) instead of raising
    "RAISE_ERROR_IF_DB_UNAVAILABLE": False,
    # if audit alias missing/unavailable, use 'default' intentionally, this requires RAISE_ERROR_IF_DB_UNAVAILABLE is set to False
    "FALLBACK_TO_DEFAULT": False,
}

Async Logging with Celery

This package supports async audit logging using Celery. When ASYNC is set to True, audit logs will be inserted asynchronously using Celery tasks, which can improve performance for high-traffic applications.

Setup

1. Install Celery (if not already installed):

pip install celery

2. Configure Celery in your Django project (this package doesn't configure Celery for you):

# settings.py
CELERY_BROKER_URL = 'redis://localhost:6379/0'  # or your preferred broker
CELERY_RESULT_BACKEND = 'redis://localhost:6379/0'

3. Enable async logging:

AWESOME_AUDIT_LOG = {
    "ASYNC": True,  # Enable async logging
    # ... other settings
}

Notes

• The package automatically detects if Celery is available and falls back to synchronous logging if not
• Works with any Celery broker (Redis, RabbitMQ, database, etc.)
• No additional configuration is required in this package - it uses your existing Celery setup
• Async logging is disabled by default for backward compatibility
• Important: Timestamps are captured at event time, not at database insert time, ensuring accurate audit logs even with async processing

Timestamp Accuracy

This package ensures that audit log timestamps (created_at) accurately reflect when events occur, not when they're saved to the database. This is especially important for async logging where there may be a delay between the event and database insertion.

See MIGRATION_GUIDE.md if you're upgrading from a version prior to 1.0.0.

Entry Point Detection

This package automatically captures audit context from different entry points in your application:

Supported Entry Points

• HTTP Requests: Automatically captured via middleware (when CAPTURE_HTTP is enabled)
• Management Commands: Automatically captured for all Django management commands (when CAPTURE_COMMANDS is enabled)
• Celery Tasks: Automatically captured for all Celery tasks and Celery Beat scheduled tasks (when CAPTURE_CELERY is enabled)

Each audit log entry includes the entry_point field indicating the source:

• http - HTTP requests
• management_command - Django management commands
• celery_task - Celery tasks and Celery Beat scheduled tasks

Development

Preparation

# Install dependencies
poetry install

Running Tests and Linter Locally

# Run tests
poetry run pytest

# Run linting
poetry run ruff check awesome_audit_log tests
poetry run ruff format --check awesome_audit_log tests