Metadata-Version: 2.4
Name: awesome-audit-log-django
Version: 1.1.1
Summary: Per-model audit logs to TABLENAME_log with entry-point capture (HTTP/management/shell/celery)
License: MIT
License-File: LICENSE
Keywords: django,audit,logging,audit-log,log,changes,databse-changes
Author: AmooAti
Author-email: adhamiamirhossein@gmail.com
Requires-Python: >=3.10,<3.14
Classifier: Framework :: Django
Classifier: Framework :: Django :: 4.2
Classifier: Framework :: Django :: 5
Classifier: Framework :: Django :: 5.0
Classifier: Framework :: Django :: 5.1
Classifier: Framework :: Django :: 5.2
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3 :: Only
Requires-Dist: Django (>=4.2)
Project-URL: Homepage, https://github.com/AmooAti/awesome-audit-log-django
Project-URL: Repository, https://github.com/AmooAti/awesome-audit-log-django
Description-Content-Type: text/markdown

# Awesome Audit Log for Django

[![PyPI version](https://img.shields.io/pypi/v/awesome-audit-log-django)](https://pypi.org/project/awesome-audit-log-django/)
[![codecov](https://codecov.io/github/AmooAti/awesome-audit-log-django/graph/badge.svg?token=D5SCFRSM7H)](https://codecov.io/github/AmooAti/awesome-audit-log-django)
![Python versions](https://img.shields.io/pypi/pyversions/awesome-audit-log-django)
![License](https://img.shields.io/pypi/l/awesome-audit-log-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. Add management, shell, celery as entry point of logs
4. 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

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

2. Add Middleware

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

3. Settings

```python
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,
    # 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):

```bash
pip install celery
```

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

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

3. Enable async logging:

```python
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](MIGRATION_GUIDE.md) if you're upgrading from a version prior to 1.0.0.

## Development

### Preparation

```bash
# Install dependencies
poetry install
```

### Running Tests and Linter Locally

```bash
# Run tests
poetry run pytest

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

