z4j-flask

The Flask framework adapter for z4j.

Adds the z4j agent into your Flask app via a one-line Z4J(app) initializer. It registers installed engine adapters only when their required native handles are configured on the Flask app (CELERY_APP, RQ_APP or RQ_REDIS_URL, ARQ_REDIS_SETTINGS, HUEY, or TASKIQ_BROKER). Dramatiq can instead use a process-global broker that already has registered actors.

Compatibility

• Flask 2.3.3+ (no upper cap)
• Python 3.11+

The range describes integration API compatibility. Flask 3.1.3 or a newer security-patched release is recommended for production; installing the adapter does not certify the host application's dependency security or force its feature-version upgrade.

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, Z4J(app) and the agent connects on the next worker boot
• Configured engine discovery, supports multiple installed adapters when each adapter's required native handle is present in Flask config
• TaskIQ middleware discovery, TASKIQ_BROKER attaches z4j capture without guessing an event loop; TaskIQ broker startup binds its actual owner loop
• 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

Install

pip install z4j-flask z4j-celery z4j-celerybeat

Wire it into your app:

from flask import Flask
from myproject.celery import app as celery_app
from z4j_flask import Z4J

app = Flask(__name__)
app.config["CELERY_APP"] = celery_app
Z4J(app)  # reads Z4J_TOKEN, Z4J_HMAC_SECRET, Z4J_BRAIN_URL, Z4J_PROJECT_ID

Mint the agent from the dashboard's Agents page and retain both values it shows: the bearer token and the HMAC secret.

For TASKIQ_BROKER, initialize Z4J(app) before the component that starts the broker. Flask discovery attaches the middleware, and TaskIQ's real broker startup binds its owner loop. A separate TaskIQ worker process still needs its own agent and must attach before the TaskIQ CLI starts the broker.

Scope and worker processes

This package connects the web process and its configured queue handles. Task execution still happens in the queue's worker process, which needs its own engine adapter and agent configuration. It does not provide HTTP request tracing or automatically capture arbitrary threads started by Flask handlers. Use a supported queue engine for the task lifecycle and controls shown in z4j.

Reliability

• Agent startup and delivery failures are logged and isolated from Flask request handlers and worker code; capture hooks make no brain network request inline.
• Engine event queues and the SQLite outbound buffer are bounded. A full engine queue loses an event (the Celery, RQ and Dramatiq adapters evict the oldest queued event; the Huey, arq and TaskIQ adapters drop the new one) and buffer pressure evicts oldest rows; both losses are logged.

Documentation

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

License

Apache-2.0, see LICENSE.

Links

• Homepage: https://z4j.com
• Documentation: https://docs.z4j.com
• PyPI: https://pypi.org/project/z4j-flask/
• Issues: https://github.com/z4jdev/z4j-flask/issues
• Changelog: CHANGELOG.md
• Security: security@z4j.com (see SECURITY.md)