Schedulers overview
z4j has two complementary surfaces in this section:
- Per-engine scheduler adapters (below) - surface an existing native scheduler (celery-beat, rq-scheduler, APScheduler, etc.) in the z4j dashboard so operators can see and edit those schedules in one UI without migrating away from the native scheduler. Useful when you’re already running the native scheduler and it fits.
- z4j-scheduler - a separate companion process that fires schedules against any of the six engines z4j supports. Schedules live in z4j-brain’s database; edit from the dashboard, declarative config, or REST without a daemon restart. Useful when you have multiple engines in one shop, or want a single audit-logged surface for schedule edits across the org. If you’re running one engine and one schedule list, the existing native scheduler is probably fine.
Per-engine scheduler adapters
Section titled “Per-engine scheduler adapters”Each engine has one or more native schedulers it pairs well with; z4j ships an adapter for each so the dashboard surfaces them.
| Scheduler | Package | Read | Write (v1.0) | Pairs with |
|---|---|---|---|---|
| celery-beat | z4j-celerybeat | ✓ | ✓ (requires django-celery-beat) | Celery |
| rq-scheduler | z4j-rqscheduler | ✓ | read-only in v1.0 | RQ |
| APScheduler | z4j-apscheduler | ✓ | ✓ | Dramatiq / standalone |
| huey-periodic | z4j-hueyperiodic | ✓ | read-only (decorators) | Huey |
| arq-cron | z4j-arqcron | ✓ | read-only (decorators) | arq |
| taskiq-scheduler | z4j-taskiq-scheduler | ✓ | ✓ | taskiq |
Read vs. write
Section titled “Read vs. write”- Read-only - z4j can show the schedule in the dashboard but cannot create/pause/delete entries. This applies where the scheduler stores schedules in decorator form (code), not state.
- Write - z4j can create / update / pause / resume / delete schedule entries via the dashboard UI and REST API.
Discovery
Section titled “Discovery”Schedules are discovered on agent boot via the scheduler-specific API and re-synced every 5 minutes. Changes made outside the dashboard (e.g., directly editing the Postgres django_celery_beat_* tables) are picked up on the next sync.
CRUD operations
Section titled “CRUD operations”When supported, the UI exposes:
- Create - name, task, cron or interval, args/kwargs, enabled/disabled.
- Update - any of the above.
- Pause / Resume - toggle
enabled. - Delete - remove the entry.
Every CRUD op writes an audit log entry.
Pitfalls
Section titled “Pitfalls”- Clock drift - if your brain and agent live in different timezones, use UTC crontabs. The dashboard renders in the viewer’s local time.
- Duplicate schedules - one project can have duplicate names across agents (useful for active/standby). The dashboard shows all.
- Paused-at-broker vs paused-at-scheduler - some engines have both; z4j operates at the scheduler level. If you pause at the broker, the dashboard still shows “enabled” on the schedule.