Django Celery Logs

Supported Python versions PyPI version License GitHub Actions status Coverage Documentation status Open Source? Yes!

Django Celery Logs is a reusable Django app that records Celery task successes and failures, stores structured results and traceback data, and exposes the records in Django admin.

It is designed for projects that want task observability without keeping Celery’s default result backend enabled. By running Celery with CELERY_TASK_IGNORE_RESULT = True, successful task payloads do not need to be stored by a result backend, which can reduce memory/storage pressure and speed up task processing. Django Celery Logs keeps the operational history you need in your Django database instead: task metadata, structured JSON results, failures, durations, queues, workers, and admin statistics.

Requirements

  • Python 3.10 or later

  • Django 4.2 or later

  • Celery 5.3 or later

Features

  • Logs successful and failed Celery task executions through Celery signals.

  • Stores task id, name, queue, worker, args, kwargs, result, error message, traceback, timestamp, and duration in seconds.

  • Captures rich failure tracebacks with frame-by-frame context and local variables to make debugging failed tasks faster.

  • Adds Django admin pages for log inspection and task re-run.

  • Adds an admin statistics module with charts and metrics for throughput, failures, queues, workers, periodic tasks, slow tasks, and common errors.

  • Adds auto-refresh and configurable pagination controls to the admin task log list for near real-time monitoring.

  • Includes a cleanup task named clear_celery_task_logs.

  • Includes acquire_lock_or_fail for cache-backed task de-duplication.

Installation

Install from PyPI:

pip install django-celery-logs

If you use uv:

uv pip install django-celery-logs

Install from source:

git clone git@github.com:rhenter/django-celery-logs.git
cd django-celery-logs
pip install .

If you use uv:

uv pip install .

Settings

Celery result settings

Django Celery Logs is intended to replace Celery result-backend storage for task inspection. Configure Celery to ignore the default result backend and serialize task data as JSON:

CELERY_TASK_IGNORE_RESULT = True
CELERY_RESULT_SERIALIZER = "json"

Do not enable other Celery result apps in INSTALLED_APPS for the same purpose. For example, remove django_celery_results if it is installed. Only django_celery_logs should be added, as shown in the Django app section below.

If these settings exist, remove them unless another part of your project really depends on them:

CELERY_RESULT_BACKEND = "..."
CELERY_CACHE_BACKEND = "..."

Django app

Add the app to INSTALLED_APPS:

INSTALLED_APPS = [
    ...
    "django_celery_logs",
    ...
]

Run migrations:

python manage.py migrate

Optionally configure how many days logs are retained by the cleanup task:

CELERY_TASK_LOGS_EXPIRES = 7

Admin

The package includes Django admin templates and static assets for:

  • Task log list with auto-refresh, collapsible filters, configurable page size, JSON result preview, and a shortcut to statistics.

  • Task log detail with a re-run action.

  • Task statistics with cards, charts, top tasks, slowest tasks, queue/worker distribution, periodic task distribution, and top error messages.

Failure tracebacks are stored as structured JSON and rendered interactively in the admin, including exception type, message, stack frames, and sanitized local variables from the frame context.

Auto-refresh

The task log list includes an auto-refresh control for operational monitoring. You can keep the admin open while workers are processing tasks and refresh the list every 5, 10, 30, or 60 seconds. The selected interval is saved in the browser, so the page keeps the same refresh behavior after reloads.

Usage

Once Django loads the app, Celery’s task_success and task_failure signals create TaskLog records automatically.

To remove old logs, schedule the bundled task in Celery beat or call it directly:

from django_celery_logs.tasks import clear_celery_task_logs

clear_celery_task_logs.delay()

To avoid logging an intentionally skipped successful task, return a dictionary with ignore_task_log:

return {"status": "skipped", "ignore_task_log": True}

Contributing

Pull requests are welcome.

Development

This project uses uv for local development commands. Install development dependencies with:

make deps

Run the test suite:

make test

Run Django’s system checks against the bundled test project:

make check

Build the source distribution and wheel:

make build

Useful Makefile targets:

  • make deps installs the project and development dependencies with uv sync --extra dev.

  • make test runs uv run --extra dev pytest.

  • make check runs django check with the test project settings.

  • make lint runs pre-commit hooks.

  • make docs builds the Sphinx documentation.

  • make clean removes build, cache, coverage, and bytecode files.

  • make build creates sdist and wheel with uv build.

  • make release tags the current version and uploads dist/* with twine.

License

MIT

Changelog

All notable changes to this project will be documented in this file.

The project follows semantic versioning while the public API stabilizes.

0.2.0

Released on 2026-09-19.

Added

  • Added PyPI-ready package metadata, project URLs, classifiers, and package data configuration.

  • Added uv-based development workflow with Makefile targets for dependencies, tests, Django checks, documentation, builds, and releases.

  • Added Sphinx documentation source with installation, settings, admin, usage, development, release, changelog, and API pages.

  • Added documentation dependencies for local docs development: sphinx-autobuild, sphinx-intl, and sphinxjp.themes.basicstrap.

  • Added badges for PyPI, supported Python versions, license, GitHub Actions, coverage, documentation, and open-source status.

  • Added English and Portuguese README files.

Changed

  • Improved README guidance for installing with both pip and uv.

  • Clarified required Celery settings: CELERY_TASK_IGNORE_RESULT = True and CELERY_RESULT_SERIALIZER = "json".

  • Clarified that other Celery result apps, such as django_celery_results, should not be enabled together with this app.

  • Clarified that CELERY_RESULT_BACKEND and CELERY_CACHE_BACKEND should be removed unless another part of the project explicitly requires them.

  • Removed duplicated INSTALLED_APPS examples from the README and settings documentation.

  • Documented that Django automatically loads django_celery_logs.apps.CeleryLogsConfig when django_celery_logs is added to INSTALLED_APPS.

Packaging

  • Removed legacy requirements-file workflow in favor of pyproject.toml and uv.lock.

  • Kept runtime dependencies in package metadata so installs from PyPI include Django, Celery, and boltons automatically.

0.1.0

Released on 2026-09-19.

Added

  • Added reusable Django app for storing Celery task execution logs.

  • Added Celery signal handlers for successful and failed task executions.

  • Added TaskLog model with task id, task name, queue, worker, args, kwargs, result, error message, traceback, timestamp, duration, periodic task flag, and traceback context data.

  • Added TaskConfig model for configuring task rerun behavior from Django admin.

  • Added Django admin task log list with filters, search, pagination controls, auto-refresh, and task rerun action.

  • Added task detail page with formatted JSON and traceback context.

  • Added statistics admin page with charts for throughput, failures, queues, workers, periodic tasks, slow tasks, and common errors.

  • Added clear_celery_task_logs cleanup task.

  • Added acquire_lock_or_fail helper for cache-backed task de-duplication.

  • Added test project and initial pytest coverage.

Project links

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.2.1)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for rhenter from gravatar.com rhenter

Credits

Data verified by PyPI on Sep 19, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI. Confirms that the provided email matches a verified, public email address on a PyPI user account associated with the project.

Author: Rafael Henter

License

MIT

Requires

Python >=3.10

Provides Extra

dev

Tags

django celery logs admin task monitoring

Classifiers

Report project as malware

Release files for django-celery-logs 0.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for django-celery-logs 0.2.0
File Size Uploaded
django_celery_logs-0.2.0.tar.gz 30.3 kB Details

Built distribution (wheel)

Table of built distributions (wheels) for django-celery-logs 0.2.0
File Interpreter ABI Platform
django_celery_logs-0.2.0-py3-none-any.whl 22.7 kB Python 3 none any Details

Total release size: 52.9 kB

Release files / django_celery_logs-0.2.0.tar.gz

Download URL django_celery_logs-0.2.0.tar.gz
Size 30.3 kB
Tags Source
SHA-256 checksum
How to use checksums 		946e70c0e1c06bd6a00b77e2457408af392bc795fd0331fb9938163d3e192fc1
BLAKE2b-256 checksum
How to use checksums 		d91f406fa74fcf923d5a82e4679ed10a048b995df4a4ada40df04ea13f321892
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing? 		No
Uploaded via twine/7.0.0 CPython/3.12.14

Release files / django_celery_logs-0.2.0-py3-none-any.whl

Download URL django_celery_logs-0.2.0-py3-none-any.whl
Size 22.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums 		dc74a59deb4d4129b9b3bfba62f42bd4dfc61d8b2397c1cd146d063e3110c1ef
BLAKE2b-256 checksum
How to use checksums 		31ba004c1f633778224c5615b77642ded786996e317120c2e4d262f3b6144fcb
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing? 		No
Uploaded via twine/7.0.0 CPython/3.12.14

Release history Release notifications | RSS feed

0.2.1

2 release files

This release

0.2.0 This release

2 release files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page