z4j-django

The Django framework adapter for z4j.

Adds the z4j agent to a Django process as a single INSTALLED_APPS entry. The Django integration locates a configured Celery app when z4j-celery is installed, and z4j-celery separately bootstraps the agent in Celery worker processes. Installing an RQ, Dramatiq, Huey, arq, or TaskIQ adapter does not by itself activate that engine in Django; wire those worker processes through the engine-specific or framework-free integration.

Compatibility

• Django 4.2+ with no adapter upper cap
• Python 3.11+; choose a Python/Django combination supported by that Django release

Existing Django 4.2 and 5.2 applications can install the adapter without moving to Django 6. Current-framework tests also cover Django 6.1.1. The Celery/all-extras combination respects django-celery-beat's own Django<6.1 constraint.

This range describes integration API compatibility. Use supported Django release lines and current security patches for production; legacy compatibility does not certify an older host application as secure. Z4J's own audited deployment locks are maintained separately from the adapter's public requirements.

Pair with an engine adapter (z4j-celery, z4j-rq, z4j-dramatiq, z4j-huey, z4j-arq, z4j-taskiq); each engine adapter carries its own upstream floor.

Full per-adapter matrix at https://docs.z4j.com/reference/compatibility/.

What it ships

• One-line install, add "z4j_django" to INSTALLED_APPS; the agent starts when Django boots, no decorator on every task
• Celery discovery and worker bootstrap, locates the configured Celery app in Django processes and registers a separate engine-aware runtime inside Celery workers
• Schedule integration, pair with z4j-celerybeat to surface django-celery-beat schedules on the dashboard's Schedules page
• Per-task metadata from supporting engine adapters; z4j-celery, z4j-rq, and z4j-dramatiq expose @z4j_meta rather than this framework package defining one
• Service-user safe, auto-relocates the local outbound buffer to $TMPDIR/z4j-{uid} when $HOME is unwritable (gunicorn under www-data, nginx, etc.)

Install

pip install z4j-django z4j-celery z4j-celerybeat

Then in settings.py:

INSTALLED_APPS = [
    # ...
    "django_celery_beat",  # if you use celery-beat
    "z4j_django",
]

The agent reads its bearer token from Z4J_TOKEN, mandatory envelope-signing secret from Z4J_HMAC_SECRET, z4j URL from Z4J_BRAIN_URL, and project id from Z4J_PROJECT_ID. The Agents page shows the token and HMAC secret when the agent is minted; retain both values.

Reliability

• Agent startup and delivery failures are logged and isolated from Django request handlers, signals, and worker code; capture hooks make no brain network request inline.
• Engine event queues and the SQLite outbound buffer are bounded. Queue overflow drops new events and buffer pressure evicts oldest rows; both losses are logged.
• Agent reconnects on every transient failure with bounded backoff.

Documentation

Full docs at docs.z4j.com/frameworks/django/.

License

Apache-2.0, see LICENSE.

Links

• Homepage: https://z4j.com
• Documentation: https://docs.z4j.com
• PyPI: https://pypi.org/project/z4j-django/
• Issues: https://github.com/z4jdev/z4j-django/issues
• Changelog: CHANGELOG.md
• Security: [email protected] (see SECURITY.md)