django-celery-logs 0.2.0__tar.gz

django_celery_logs-0.2.0/CHANGES.rst

@@ -0,0 +1,76 @@
+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.

django_celery_logs-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rafael Henter
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

django_celery_logs-0.2.0/MANIFEST.in

@@ -0,0 +1,6 @@
+include LICENSE
+include README.rst
+include README.pt.rst
+include CHANGES.rst
+recursive-include django_celery_logs *.py *.html *.css *.js
+recursive-include docs_src *.rst *.py *.bat Makefile

django_celery_logs-0.2.0/PKG-INFO

@@ -0,0 +1,380 @@
+Metadata-Version: 2.4
+Name: django-celery-logs
+Version: 0.2.0
+Summary: Reusable Django app to store and inspect Celery task logs in Django admin.
+Home-page: https://github.com/rhenter/django-celery-logs
+Author: Rafael Henter
+Author-email: rafael@henter.com.br
+License: MIT
+Project-URL: Source, https://github.com/rhenter/django-celery-logs
+Project-URL: Issues, https://github.com/rhenter/django-celery-logs/issues
+Keywords: django celery logs admin task monitoring
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 4.2
+Classifier: Framework :: Django :: 5.0
+Classifier: Framework :: Django :: 5.1
+Classifier: Framework :: Django :: 5.2
+Classifier: Intended Audience :: Developers
+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: Topic :: Software Development :: Libraries
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/x-rst
+License-File: LICENSE
+Requires-Dist: boltons>=24.0
+Requires-Dist: celery>=5.3
+Requires-Dist: django>=4.2
+Provides-Extra: dev
+Requires-Dist: build; extra == "dev"
+Requires-Dist: pre-commit; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: pytest-django; extra == "dev"
+Requires-Dist: setuptools>=64; extra == "dev"
+Requires-Dist: sphinx; extra == "dev"
+Requires-Dist: sphinx-autobuild; extra == "dev"
+Requires-Dist: sphinx-intl; extra == "dev"
+Requires-Dist: sphinxjp.themes.basicstrap; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Requires-Dist: wheel; extra == "dev"
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: license
+Dynamic: license-file
+Dynamic: project-url
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+Django Celery Logs
+==================
+
+|PyPI latest| |PyPI Version| |PyPI License| |GitHub Actions Status| |Coverage| |Docs| |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:
+
+.. code-block:: bash
+
+    pip install django-celery-logs
+
+If you use ``uv``:
+
+.. code-block:: bash
+
+    uv pip install django-celery-logs
+
+Install from source:
+
+.. code-block:: bash
+
+    git clone git@github.com:rhenter/django-celery-logs.git
+    cd django-celery-logs
+    pip install .
+
+If you use ``uv``:
+
+.. code-block:: bash
+
+    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:
+
+.. code-block:: python
+
+    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:
+
+.. code-block:: python
+
+    CELERY_RESULT_BACKEND = "..."
+    CELERY_CACHE_BACKEND = "..."
+
+Django app
+~~~~~~~~~~
+
+Add the app to ``INSTALLED_APPS``:
+
+.. code-block:: python
+
+    INSTALLED_APPS = [
+        ...
+        "django_celery_logs",
+        ...
+    ]
+
+Run migrations:
+
+.. code-block:: bash
+
+    python manage.py migrate
+
+Optionally configure how many days logs are retained by the cleanup task:
+
+.. code-block:: python
+
+    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:
+
+.. code-block:: python
+
+    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``:
+
+.. code-block:: python
+
+    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:
+
+.. code-block:: bash
+
+    make deps
+
+Run the test suite:
+
+.. code-block:: bash
+
+    make test
+
+Run Django's system checks against the bundled test project:
+
+.. code-block:: bash
+
+    make check
+
+Build the source distribution and wheel:
+
+.. code-block:: bash
+
+    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
+
+.. |PyPI latest| image:: https://img.shields.io/pypi/pyversions/django-celery-logs.svg
+   :target: https://pypi.org/project/django-celery-logs/
+   :alt: Supported Python versions
+
+.. |PyPI Version| image:: https://img.shields.io/pypi/v/django-celery-logs.svg
+   :target: https://pypi.org/project/django-celery-logs/
+   :alt: PyPI version
+
+.. |PyPI License| image:: https://img.shields.io/pypi/l/django-celery-logs.svg
+   :target: https://pypi.org/project/django-celery-logs/
+   :alt: License
+
+.. |GitHub Actions Status| image:: https://github.com/rhenter/django-celery-logs/actions/workflows/tests.yml/badge.svg
+   :target: https://github.com/rhenter/django-celery-logs/actions
+   :alt: GitHub Actions status
+
+.. |Coverage| image:: https://codecov.io/gh/rhenter/django-celery-logs/branch/main/graph/badge.svg
+   :target: https://codecov.io/gh/rhenter/django-celery-logs
+   :alt: Coverage
+
+.. |Docs| image:: https://readthedocs.org/projects/django-celery-logs/badge/?version=latest
+   :target: https://django-celery-logs.readthedocs.io/en/latest/
+   :alt: Documentation status
+
+.. |Open Source? Yes!| image:: https://badgen.net/badge/Open%20Source%3F/Yes%21/blue
+   :target: https://github.com/rhenter/django-celery-logs
+   :alt: Open Source? Yes!
+
+
+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.

django_celery_logs-0.2.0/README.pt.rst

@@ -0,0 +1,68 @@
+Django Celery Logs
+==================
+
+Django Celery Logs e uma app Django reutilizavel para registrar execucoes do
+Celery, guardar resultados e tracebacks estruturados, e consultar tudo pelo
+Django admin.
+
+A biblioteca foi pensada para observar tarefas sem manter o result backend
+padrao do Celery. Use ``CELERY_TASK_IGNORE_RESULT = True`` para reduzir uso de
+memoria/storage e manter o historico operacional no banco da aplicacao.
+
+Funcionalidades
+---------------
+
+* Registro automatico de sucessos e falhas via signals do Celery.
+* Stacktrace estruturado das falhas, com frames e variaveis locais sanitizadas.
+* Admin com listagem de logs, preview JSON, re-execucao de tasks e paginacao configuravel.
+* Auto refresh na listagem com intervalos de 5, 10, 30 e 60 segundos.
+* Modulo de estatisticas com cards, graficos, top tasks, tasks lentas, filas, workers e erros comuns.
+
+Instalacao
+----------
+
+.. code-block:: bash
+
+    pip install django-celery-logs
+
+Se voce usa ``uv``:
+
+.. code-block:: bash
+
+    uv pip install django-celery-logs
+
+Configuracao
+------------
+
+Configure o Celery para ignorar o backend padrao de resultados:
+
+.. code-block:: python
+
+    CELERY_TASK_IGNORE_RESULT = True
+    CELERY_RESULT_SERIALIZER = "json"
+
+Nao use apps concorrentes de resultado do Celery, como ``django_celery_results``,
+junto com esta biblioteca. Se existirem e nao forem exigidas por outra parte do
+projeto, remova tambem:
+
+.. code-block:: python
+
+    CELERY_RESULT_BACKEND = "..."
+    CELERY_CACHE_BACKEND = "..."
+
+.. code-block:: python
+
+    INSTALLED_APPS = [
+        ...
+        "django_celery_logs",
+        ...
+    ]
+
+Depois execute:
+
+.. code-block:: bash
+
+    python manage.py migrate
+
+A configuracao opcional ``CELERY_TASK_LOGS_EXPIRES`` define por quantos dias os
+logs serao mantidos pela task de limpeza.