# Awesome Audit Log for Django
[](https://pypi.org/project/awesome-audit-log-django/)
[](https://codecov.io/github/AmooAti/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. 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,
# 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):
```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.
## 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
```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
```
Raw data
{
"_id": null,
"home_page": "https://github.com/AmooAti/awesome-audit-log-django",
"name": "awesome-audit-log-django",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.14,>=3.10",
"maintainer_email": null,
"keywords": "django, audit, logging, audit-log, log, changes, databse-changes",
"author": "AmooAti",
"author_email": "adhamiamirhossein@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/60/39/adae0f7ccfe353535a2404ed0ee473e36883ae35468bb9738444bd9d1c8d/awesome_audit_log_django-1.2.0.tar.gz",
"platform": null,
"description": "# Awesome Audit Log for Django\n\n[](https://pypi.org/project/awesome-audit-log-django/)\n[](https://codecov.io/github/AmooAti/awesome-audit-log-django)\n\n\n\nThis is an awesome package to have your models logs in corresponding \\_log tables.\n\nHaving a single model/table as audit storage can cause heavy db operation and useless for large applications.\n\nWith 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.\n\nYou can choose between having logs table in your default database or adding a new backend db as logs db.\n\nSupported DBs to store logs:\n\n1. PostgreSQL\n2. MySQL\n3. SQLite\n\nThis package is in its early stage development and the following features will be added ASAP:\n\n1. Log rotation\n2. Mongo DB support\n3. Document page!\n\n## Compatible With\n\nThis package works on the below listed Django, Python versions and Databases.\n\n- **Django versions**: 4.2, 5.0, 5.1\n- **Python versions**: 3.10, 3.11, 3.12\n- **Databases**: SQLite, PostgreSQL, MySQL\n- **Celery**: Optional for Async logging\n\n## Installation\n\n1. Add App\n\n```python\nINSTALLED_APPS = [\n # ...\n 'awesome_audit_log.apps.AwesomeAuditLogConfig',\n]\n```\n\n2. Add Middleware\n\n```python\nMIDDLEWARE = [\n # ...\n \"awesome_audit_log.middleware.RequestEntryPointMiddleware\",\n]\n```\n\n3. Settings\n\n```python\nAWESOME_AUDIT_LOG = {\n \"ENABLED\": True,\n \"DATABASE_ALIAS\": \"default\",\n # PostgreSQL schema for audit tables (defaults to 'public')\n \"PG_SCHEMA\": None,\n # Enable async logging with Celery (requires Celery to be installed and configured)\n \"ASYNC\": False,\n # \"all\" or list like [\"app_label.ModelA\", \"app.ModelB\"]\n \"AUDIT_MODELS\": \"all\",\n # like AUDIT_MODELS but for opt-out, useful when AUDIT_MODELS set to all\n \"NOT_AUDIT_MODELS\": None,\n \"CAPTURE_HTTP\": True,\n # Capture context for management commands\n \"CAPTURE_COMMANDS\": True,\n # Capture context for Celery tasks\n \"CAPTURE_CELERY\": True,\n # set to False means if audit db is unavailable, silently skip logging (with a warning) instead of raising\n \"RAISE_ERROR_IF_DB_UNAVAILABLE\": False,\n # if audit alias missing/unavailable, use 'default' intentionally, this requires RAISE_ERROR_IF_DB_UNAVAILABLE is set to False\n \"FALLBACK_TO_DEFAULT\": False,\n}\n```\n\n## Async Logging with Celery\n\nThis 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.\n\n### Setup\n\n1. Install Celery (if not already installed):\n\n```bash\npip install celery\n```\n\n2. Configure Celery in your Django project (this package doesn't configure Celery for you):\n\n```python\n# settings.py\nCELERY_BROKER_URL = 'redis://localhost:6379/0' # or your preferred broker\nCELERY_RESULT_BACKEND = 'redis://localhost:6379/0'\n```\n\n3. Enable async logging:\n\n```python\nAWESOME_AUDIT_LOG = {\n \"ASYNC\": True, # Enable async logging\n # ... other settings\n}\n```\n\n### Notes\n\n- The package automatically detects if Celery is available and falls back to synchronous logging if not\n- Works with any Celery broker (Redis, RabbitMQ, database, etc.)\n- No additional configuration is required in this package - it uses your existing Celery setup\n- Async logging is disabled by default for backward compatibility\n- **Important**: Timestamps are captured at event time, not at database insert time, ensuring accurate audit logs even with async processing\n\n### Timestamp Accuracy\n\nThis 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.\n\nSee [MIGRATION_GUIDE.md](MIGRATION_GUIDE.md) if you're upgrading from a version prior to 1.0.0.\n\n## Entry Point Detection\n\nThis package automatically captures audit context from different entry points in your application:\n\n### Supported Entry Points\n\n- **HTTP Requests**: Automatically captured via middleware (when `CAPTURE_HTTP` is enabled)\n- **Management Commands**: Automatically captured for all Django management commands (when `CAPTURE_COMMANDS` is enabled)\n- **Celery Tasks**: Automatically captured for all Celery tasks and Celery Beat scheduled tasks (when `CAPTURE_CELERY` is enabled)\n\nEach audit log entry includes the `entry_point` field indicating the source:\n\n- `http` - HTTP requests\n- `management_command` - Django management commands\n- `celery_task` - Celery tasks and Celery Beat scheduled tasks\n\n## Development\n\n### Preparation\n\n```bash\n# Install dependencies\npoetry install\n```\n\n### Running Tests and Linter Locally\n\n```bash\n# Run tests\npoetry run pytest\n\n# Run linting\npoetry run ruff check awesome_audit_log tests\npoetry run ruff format --check awesome_audit_log tests\n```\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Per-model audit logs to TABLENAME_log with entry-point capture (HTTP/management/shell/celery)",
"version": "1.2.0",
"project_urls": {
"Homepage": "https://github.com/AmooAti/awesome-audit-log-django",
"Repository": "https://github.com/AmooAti/awesome-audit-log-django"
},
"split_keywords": [
"django",
" audit",
" logging",
" audit-log",
" log",
" changes",
" databse-changes"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "b19a597caf4692d9f46a8bace194954a5a9418f5a4fd1c41780c145d3f2ba45f",
"md5": "5de9b297ffb2f417460ecb0f0162eea9",
"sha256": "3684f869cbb7de3a0171b7f10b2ec2006ff7c95fa2d73872993e9f64e3c873a5"
},
"downloads": -1,
"filename": "awesome_audit_log_django-1.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5de9b297ffb2f417460ecb0f0162eea9",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.14,>=3.10",
"size": 16294,
"upload_time": "2025-11-01T15:18:52",
"upload_time_iso_8601": "2025-11-01T15:18:52.621327Z",
"url": "https://files.pythonhosted.org/packages/b1/9a/597caf4692d9f46a8bace194954a5a9418f5a4fd1c41780c145d3f2ba45f/awesome_audit_log_django-1.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "6039adae0f7ccfe353535a2404ed0ee473e36883ae35468bb9738444bd9d1c8d",
"md5": "b489e23877a531ad751c582f62ba3d0f",
"sha256": "94b8510488b60af0b443713c568bcf84dfc800f2e4cdf5d8210ff567d65dc7cf"
},
"downloads": -1,
"filename": "awesome_audit_log_django-1.2.0.tar.gz",
"has_sig": false,
"md5_digest": "b489e23877a531ad751c582f62ba3d0f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.14,>=3.10",
"size": 13760,
"upload_time": "2025-11-01T15:18:53",
"upload_time_iso_8601": "2025-11-01T15:18:53.494752Z",
"url": "https://files.pythonhosted.org/packages/60/39/adae0f7ccfe353535a2404ed0ee473e36883ae35468bb9738444bd9d1c8d/awesome_audit_log_django-1.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-11-01 15:18:53",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "AmooAti",
"github_project": "awesome-audit-log-django",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "awesome-audit-log-django"
}
JSON
