Async Jobs
Background task processing with Celery, ARQ, Redis and Temporal. This skill is a wrapper, not a
manual: Celery and ARQ document their own product well, so what lives here is our delta, the
thresholds, working config, ordering constraints and tool-choice rules we picked. Product
mechanics are linked, not restated.
Start with Read("references/ork-delta.md").
Quick Reference
| Topic |
Where our part lives |
| Configuration |
references/celery-config.md, rules/jobs-task-queue.md |
| Task Routing |
references/ork-delta.md (queue taxonomy, prefetch tiers, Redis priority) |
| Canvas Workflows |
rules/celery-canvas.md |
| Retry Strategies |
references/ork-delta.md (backoff cap, idempotency layers, lock TTLs) |
| Scheduling |
rules/jobs-scheduling.md, references/ork-delta.md (beat process model) |
| Monitoring |
references/ork-delta.md (alert thresholds, histogram buckets) |
| Result Backends |
rules/jobs-monitoring.md, references/ork-delta.md (return contract) |
| ARQ Patterns |
rules/jobs-task-queue.md, references/ork-delta.md (budgets, pool ownership) |
| Temporal Workflows |
rules/temporal-workflows.md |
| Temporal Activities |
rules/temporal-activities.md |
10 topic areas, 6 rule files in rules/, house delta in references/ork-delta.md.
Quick Start
@app.task(bind=True, max_retries=3, default_retry_delay=60)
def process_payment(self, order_id: str):
try:
return gateway.charge(order_id)
except TransientError as exc:
raise self.retry(exc=exc, countdown=2 ** self.request.retries * 60)
Load more examples: Read("references/quick-start-examples.md") for Celery
retry task and ARQ/FastAPI integration patterns.
Upstream coverage (do not restate)
Fetch these when you need product mechanics. The right-hand column is the part we keep, because
it is a house threshold, a working config or an ordering constraint that upstream cannot know.
| Topic |
First-party source |
House subset stays in |
| Celery settings, serializers, time limits, worker flags |
https://docs.celeryq.dev/en/stable/userguide/configuration.html and .../optimizing.html |
references/celery-config.md, rules/jobs-task-queue.md |
| Queue declarations, router classes, Redis priority mechanics |
https://docs.celeryq.dev/en/stable/userguide/routing.html |
references/ork-delta.md |
| chain / group / chord / signature semantics |
https://docs.celeryq.dev/en/stable/userguide/canvas.html |
rules/celery-canvas.md keeps the house canvas subset. Its si()-in-chords guidance is UNVERIFIED and contested: confirm the argument-passing behaviour against the upstream canvas page before relying on it |
autoretry_for, retry_backoff, Reject, task base classes |
https://docs.celeryq.dev/en/stable/userguide/tasks.html |
references/ork-delta.md, rules/jobs-task-queue.md |
| Beat schedules, crontab syntax, DatabaseScheduler |
https://docs.celeryq.dev/en/stable/userguide/periodic-tasks.html and https://django-celery-beat.readthedocs.io/en/latest/ |
rules/jobs-scheduling.md keeps our beat_schedule shapes; references/ork-delta.md keeps the process model |
Flower flags, inspect, signal names |
https://docs.celeryq.dev/en/stable/userguide/monitoring.html, https://docs.celeryq.dev/en/stable/userguide/signals.html, https://flower.readthedocs.io/en/latest/config.html |
references/ork-delta.md |
Result backend, AsyncResult, custom states |
https://docs.celeryq.dev/en/stable/userguide/configuration.html |
rules/jobs-monitoring.md keeps our status endpoints and update_state() usage |
Per-task rate_limit, control.rate_limit, Redis Lua |
https://docs.celeryq.dev/en/stable/userguide/workers.html, https://redis.io/docs/latest/develop/programmability/eval-intro/ |
references/ork-delta.md |
ARQ WorkerSettings, enqueue_job, _defer_by / _defer_until, Job status |
https://arq-docs.helpmanual.io/ |
rules/jobs-task-queue.md keeps the worker skeleton; references/ork-delta.md keeps the budgets |
| FastAPI lifespan and dependency wiring |
https://fastapi.tiangolo.com/advanced/events/ |
references/ork-delta.md |
Distributed locks with SET NX EX |
https://redis.io/docs/latest/commands/set/ |
references/ork-delta.md |
Configuration
Load: Read("references/celery-config.md").
| Decision |
Recommendation |
| Serializer |
JSON (never pickle) |
| Ack mode |
Late ack (task_acks_late=True) |
| Prefetch |
1 for fair, 4-8 for throughput |
| Time limit |
soft < hard (540 / 600) |
| Timezone |
UTC always |
Task Routing
| Decision |
Recommendation |
| Queue count |
5: critical / high / default / low / bulk |
| Priority levels |
0-9, with all four Redis priority switches set together |
| Worker assignment |
Dedicated worker per queue |
| Prefetch |
1 critical, 2 high, 4 default, 8 low/bulk |
| Routing |
Router class once past 5 routing rules |
Canvas Workflows
Load: Read("rules/celery-canvas.md").
| Decision |
Recommendation |
| Sequential |
Chain with s() |
| Parallel |
Group for independent tasks |
| Fan-in |
Chord (all header tasks must succeed for the body to run) |
| Ignore input |
Use si() immutable signature |
| Error in chain |
Reject stops the chain, retry continues it |
| Partial failures |
Return an error dict from chord header tasks |
Retry Strategies
| Decision |
Recommendation |
| Retry delay |
Exponential backoff, jitter on, capped at 600s |
| Max retries |
3-5 for transient, 0 for permanent |
| Idempotency |
Redis marker (86400s TTL) plus the vendor idempotency key |
| Failed tasks |
DLQ for manual review |
| Singleton |
Redis lock with a TTL longer than the hard time limit |
Scheduling
Load: Read("rules/jobs-scheduling.md").
| Decision |
Recommendation |
| Schedule type |
Crontab for time-based, float interval for frequency |
| Dynamic |
DatabaseScheduler (django-celery-beat) |
| Overlap |
Redis lock, 3600s default and 7200s for long jobs |
| Beat process |
Separate process; embedded --beat is development only |
| Timezone |
UTC always |
Monitoring
| Decision |
Recommendation |
| Dashboard |
Flower with persistent storage |
| Metrics |
Prometheus wired to task_prerun / task_postrun / task_failure |
| Health |
Broker reachable, at least one worker, queue depths |
| Alerting |
critical > 100, default > 5000, workers < 1 |
| Autoscale |
Queue depth > 500 |
Result Backends
Load: Read("rules/jobs-monitoring.md").
| Decision |
Recommendation |
| Status storage |
Redis result backend, status and small JSON only |
| Large results |
S3 or database, task returns a reference dict |
| Progress |
Custom states with update_state() |
| Result query |
AsyncResult with state checks |
ARQ Patterns
Load: Read("rules/jobs-task-queue.md").
| Decision |
Recommendation |
| Simple async |
ARQ (native async), max_jobs=10, job_timeout=300 |
| Pool ownership |
FastAPI lifespan, never a per-request create_pool |
| Complex workflows |
Celery (chains, chords, DLQ, per-task rate limits) |
| In-process quick |
FastAPI BackgroundTasks, under 30s, non-critical only |
| LLM workflows |
LangGraph, not Celery |
Tool Selection
Load: Read("references/quick-start-examples.md") for the full tool
comparison table (ARQ, Celery, RQ, Dramatiq, FastAPI BackgroundTasks).
Anti-Patterns (FORBIDDEN)
Load details: Read("references/anti-patterns.md") for the full list.
Key rules: never run long tasks in request handlers, never block on results inside tasks, never
store large results in Redis, always use idempotency for retried tasks.
Temporal Workflows
Load: Read("rules/temporal-workflows.md").
| Decision |
Recommendation |
| Workflow ID |
Business-meaningful, idempotent |
| Determinism |
Use workflow.random(), workflow.now() |
| I/O |
Always via activities, never directly |
Temporal Activities
Load: Read("rules/temporal-activities.md").
| Decision |
Recommendation |
| Activity timeout |
start_to_close for most cases |
| Error handling |
Non-retryable for business errors |
| Testing |
WorkflowEnvironment.start_local() for integration tests |
Related Skills
ork:python-backend - FastAPI, asyncio, SQLAlchemy patterns
ork-extras:langgraph - LangGraph workflow patterns (use for LLM workflows, not Celery)
ork-extras:distributed-systems - Resilience patterns, circuit breakers
ork-extras:monitoring-observability - Metrics and alerting
Capability Details
Load details: Read("references/capability-details.md") for the keyword index
and problem-to-capability mapping.
1---2name: async-jobs3license: MIT4compatibility: "Claude Code 2.1.277+."5description: Async job processing patterns for background tasks, Celery workflows, task scheduling, retry strategies, and distributed task execution. Use when implementing background job processing, task queues, or scheduled task systems.6user-invocable: false7metadata:8 source: https://skillmd.com/skills/yonatangross/async-jobs9 owner-agent: "python-performance-engineer"10 category: workflow-automation11 version: "2.0.0"12 author: "OrchestKit"13 complexity: "medium"14 tags: "async, jobs, celery, background-tasks, scheduling, queues"15allowed-tools: "Read Glob Grep WebFetch WebSearch"16---1718# Async Jobs1920Background task processing with Celery, ARQ, Redis and Temporal. This skill is a wrapper, not a21manual: Celery and ARQ document their own product well, so what lives here is our delta, the22thresholds, working config, ordering constraints and tool-choice rules we picked. Product23mechanics are linked, not restated.2425Start with `Read("references/ork-delta.md")`.2627## Quick Reference2829| Topic | Where our part lives |30|-------|----------------------|31| [Configuration](#configuration) | `references/celery-config.md`, `rules/jobs-task-queue.md` |32| [Task Routing](#task-routing) | `references/ork-delta.md` (queue taxonomy, prefetch tiers, Redis priority) |33| [Canvas Workflows](#canvas-workflows) | `rules/celery-canvas.md` |34| [Retry Strategies](#retry-strategies) | `references/ork-delta.md` (backoff cap, idempotency layers, lock TTLs) |35| [Scheduling](#scheduling) | `rules/jobs-scheduling.md`, `references/ork-delta.md` (beat process model) |36| [Monitoring](#monitoring) | `references/ork-delta.md` (alert thresholds, histogram buckets) |37| [Result Backends](#result-backends) | `rules/jobs-monitoring.md`, `references/ork-delta.md` (return contract) |38| [ARQ Patterns](#arq-patterns) | `rules/jobs-task-queue.md`, `references/ork-delta.md` (budgets, pool ownership) |39| [Temporal Workflows](#temporal-workflows) | `rules/temporal-workflows.md` |40| [Temporal Activities](#temporal-activities) | `rules/temporal-activities.md` |414210 topic areas, 6 rule files in `rules/`, house delta in `references/ork-delta.md`.4344## Quick Start4546```python47@app.task(bind=True, max_retries=3, default_retry_delay=60)48def process_payment(self, order_id: str):49 try:50 return gateway.charge(order_id)51 except TransientError as exc:52 raise self.retry(exc=exc, countdown=2 ** self.request.retries * 60)53```5455Load more examples: `Read("references/quick-start-examples.md")` for Celery56retry task and ARQ/FastAPI integration patterns.5758## Upstream coverage (do not restate)5960Fetch these when you need product mechanics. The right-hand column is the part we keep, because61it is a house threshold, a working config or an ordering constraint that upstream cannot know.6263| Topic | First-party source | House subset stays in |64|-------|--------------------|-----------------------|65| Celery settings, serializers, time limits, worker flags | https://docs.celeryq.dev/en/stable/userguide/configuration.html and .../optimizing.html | `references/celery-config.md`, `rules/jobs-task-queue.md` |66| Queue declarations, router classes, Redis priority mechanics | https://docs.celeryq.dev/en/stable/userguide/routing.html | `references/ork-delta.md` |67| chain / group / chord / signature semantics | https://docs.celeryq.dev/en/stable/userguide/canvas.html | `rules/celery-canvas.md` keeps the house canvas subset. Its `si()`-in-chords guidance is UNVERIFIED and contested: confirm the argument-passing behaviour against the upstream canvas page before relying on it |68| `autoretry_for`, `retry_backoff`, `Reject`, task base classes | https://docs.celeryq.dev/en/stable/userguide/tasks.html | `references/ork-delta.md`, `rules/jobs-task-queue.md` |69| Beat schedules, crontab syntax, DatabaseScheduler | https://docs.celeryq.dev/en/stable/userguide/periodic-tasks.html and https://django-celery-beat.readthedocs.io/en/latest/ | `rules/jobs-scheduling.md` keeps our `beat_schedule` shapes; `references/ork-delta.md` keeps the process model |70| Flower flags, `inspect`, signal names | https://docs.celeryq.dev/en/stable/userguide/monitoring.html, https://docs.celeryq.dev/en/stable/userguide/signals.html, https://flower.readthedocs.io/en/latest/config.html | `references/ork-delta.md` |71| Result backend, `AsyncResult`, custom states | https://docs.celeryq.dev/en/stable/userguide/configuration.html | `rules/jobs-monitoring.md` keeps our status endpoints and `update_state()` usage |72| Per-task `rate_limit`, `control.rate_limit`, Redis Lua | https://docs.celeryq.dev/en/stable/userguide/workers.html, https://redis.io/docs/latest/develop/programmability/eval-intro/ | `references/ork-delta.md` |73| ARQ `WorkerSettings`, `enqueue_job`, `_defer_by` / `_defer_until`, `Job` status | https://arq-docs.helpmanual.io/ | `rules/jobs-task-queue.md` keeps the worker skeleton; `references/ork-delta.md` keeps the budgets |74| FastAPI lifespan and dependency wiring | https://fastapi.tiangolo.com/advanced/events/ | `references/ork-delta.md` |75| Distributed locks with `SET NX EX` | https://redis.io/docs/latest/commands/set/ | `references/ork-delta.md` |7677## Configuration7879Load: `Read("references/celery-config.md")`.8081| Decision | Recommendation |82|----------|----------------|83| Serializer | JSON (never pickle) |84| Ack mode | Late ack (`task_acks_late=True`) |85| Prefetch | 1 for fair, 4-8 for throughput |86| Time limit | soft < hard (540 / 600) |87| Timezone | UTC always |8889## Task Routing9091| Decision | Recommendation |92|----------|----------------|93| Queue count | 5: critical / high / default / low / bulk |94| Priority levels | 0-9, with all four Redis priority switches set together |95| Worker assignment | Dedicated worker per queue |96| Prefetch | 1 critical, 2 high, 4 default, 8 low/bulk |97| Routing | Router class once past 5 routing rules |9899## Canvas Workflows100101Load: `Read("rules/celery-canvas.md")`.102103| Decision | Recommendation |104|----------|----------------|105| Sequential | Chain with `s()` |106| Parallel | Group for independent tasks |107| Fan-in | Chord (all header tasks must succeed for the body to run) |108| Ignore input | Use `si()` immutable signature |109| Error in chain | `Reject` stops the chain, `retry` continues it |110| Partial failures | Return an error dict from chord header tasks |111112## Retry Strategies113114| Decision | Recommendation |115|----------|----------------|116| Retry delay | Exponential backoff, jitter on, capped at 600s |117| Max retries | 3-5 for transient, 0 for permanent |118| Idempotency | Redis marker (86400s TTL) plus the vendor idempotency key |119| Failed tasks | DLQ for manual review |120| Singleton | Redis lock with a TTL longer than the hard time limit |121122## Scheduling123124Load: `Read("rules/jobs-scheduling.md")`.125126| Decision | Recommendation |127|----------|----------------|128| Schedule type | Crontab for time-based, float interval for frequency |129| Dynamic | DatabaseScheduler (`django-celery-beat`) |130| Overlap | Redis lock, 3600s default and 7200s for long jobs |131| Beat process | Separate process; embedded `--beat` is development only |132| Timezone | UTC always |133134## Monitoring135136| Decision | Recommendation |137|----------|----------------|138| Dashboard | Flower with persistent storage |139| Metrics | Prometheus wired to `task_prerun` / `task_postrun` / `task_failure` |140| Health | Broker reachable, at least one worker, queue depths |141| Alerting | critical > 100, default > 5000, workers < 1 |142| Autoscale | Queue depth > 500 |143144## Result Backends145146Load: `Read("rules/jobs-monitoring.md")`.147148| Decision | Recommendation |149|----------|----------------|150| Status storage | Redis result backend, status and small JSON only |151| Large results | S3 or database, task returns a reference dict |152| Progress | Custom states with `update_state()` |153| Result query | `AsyncResult` with state checks |154155## ARQ Patterns156157Load: `Read("rules/jobs-task-queue.md")`.158159| Decision | Recommendation |160|----------|----------------|161| Simple async | ARQ (native async), `max_jobs=10`, `job_timeout=300` |162| Pool ownership | FastAPI lifespan, never a per-request `create_pool` |163| Complex workflows | Celery (chains, chords, DLQ, per-task rate limits) |164| In-process quick | FastAPI BackgroundTasks, under 30s, non-critical only |165| LLM workflows | LangGraph, not Celery |166167## Tool Selection168169Load: `Read("references/quick-start-examples.md")` for the full tool170comparison table (ARQ, Celery, RQ, Dramatiq, FastAPI BackgroundTasks).171172## Anti-Patterns (FORBIDDEN)173174Load details: `Read("references/anti-patterns.md")` for the full list.175176Key rules: never run long tasks in request handlers, never block on results inside tasks, never177store large results in Redis, always use idempotency for retried tasks.178179## Temporal Workflows180181Load: `Read("rules/temporal-workflows.md")`.182183| Decision | Recommendation |184|----------|----------------|185| Workflow ID | Business-meaningful, idempotent |186| Determinism | Use `workflow.random()`, `workflow.now()` |187| I/O | Always via activities, never directly |188189## Temporal Activities190191Load: `Read("rules/temporal-activities.md")`.192193| Decision | Recommendation |194|----------|----------------|195| Activity timeout | `start_to_close` for most cases |196| Error handling | Non-retryable for business errors |197| Testing | `WorkflowEnvironment.start_local()` for integration tests |198199## Related Skills200201- `ork:python-backend` - FastAPI, asyncio, SQLAlchemy patterns202- `ork-extras:langgraph` - LangGraph workflow patterns (use for LLM workflows, not Celery)203- `ork-extras:distributed-systems` - Resilience patterns, circuit breakers204- `ork-extras:monitoring-observability` - Metrics and alerting205206## Capability Details207208Load details: `Read("references/capability-details.md")` for the keyword index209and problem-to-capability mapping.