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.
- 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/.
- 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_BROKERattaches 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, andz4j-dramatiqexpose@z4j_metarather than this framework package defining one - Service-user safe, auto-relocates the local outbound buffer
to
$TMPDIR/z4j-{uid}when$HOMEis unwritable
pip install z4j-flask z4j-celery z4j-celerybeatWire 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_IDMint 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.
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.
- 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.
Full docs at docs.z4j.com/frameworks/flask/.
Apache-2.0, see LICENSE.
- 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)