async-jobs

非同期ジョブ

Celery、ARQ、Redis、Temporal によるバックグラウンドタスク処理。このスキルはマニュアルではなくラッパーです。Celery と ARQ はそれぞれの製品について十分なドキュメントを提供しているため、ここでは私たち独自の差分、しきい値、実用的な設定、順序に関する制約、ツール選択のルールを扱います。製品の仕組みについては、繰り返し説明せずリンクを示します。

まず Read("references/ork-delta.md") を実行してください。

クイックリファレンス

トピック	独自の内容が記載されている場所
設定	references/celery-config.md、rules/jobs-task-queue.md
タスクのルーティング	references/ork-delta.md（キューの分類、プリフェッチの段階、Redis の優先度）
Canvas ワークフロー	rules/celery-canvas.md
再試行戦略	references/ork-delta.md（バックオフの上限、冪等性のレイヤー、ロックの TTL）
スケジューリング	rules/jobs-scheduling.md、references/ork-delta.md（Beat のプロセスモデル）
モニタリング	references/ork-delta.md（アラートのしきい値、ヒストグラムのバケット）
結果バックエンド	rules/jobs-monitoring.md、references/ork-delta.md（戻り値の契約）
ARQ のパターン	rules/jobs-task-queue.md、references/ork-delta.md（予算、プールの所有権）
Temporal ワークフロー	rules/temporal-workflows.md
Temporal アクティビティ	rules/temporal-activities.md

10 のトピック領域、rules/ にある 6 つのルールファイル、references/ork-delta.md にあるプロジェクト独自の差分。

クイックスタート

@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)

Celery の再試行タスクと ARQ/FastAPI の統合パターンの例をさらに読み込むには、Read("references/quick-start-examples.md") を実行してください。

上流の適用範囲（内容を繰り返さないでください）

製品の仕組みを確認する必要がある場合は、以下を参照してください。右側の列に記載されている内容をここに残すのは、上流のドキュメントでは把握できない、独自のしきい値、実際に使用する設定、または順序に関する制約だからです。

トピック	公式ドキュメント	独自の内容を残す場所
Celery の設定、シリアライザー、時間制限、ワーカーフラグ	https://docs.celeryq.dev/en/stable/userguide/configuration.html and .../optimizing.html	references/celery-config.md、rules/jobs-task-queue.md
キュー宣言、ルータークラス、Redis の優先度の仕組み	https://docs.celeryq.dev/en/stable/userguide/routing.html	references/ork-delta.md
chain / group / chord / signature のセマンティクス	https://docs.celeryq.dev/en/stable/userguide/canvas.html	rules/celery-canvas.md に独自の canvas の範囲を記載します。chord での si() の使い方に関するガイダンスは未検証で、異論もあります。これに依拠する前に、引数の受け渡し動作を上流の canvas ページで確認してください
autoretry_for、retry_backoff、Reject、タスクの基底クラス	https://docs.celeryq.dev/en/stable/userguide/tasks.html	references/ork-delta.md、rules/jobs-task-queue.md
Beat のスケジュール、crontab の構文、DatabaseScheduler	https://docs.celeryq.dev/en/stable/userguide/periodic-tasks.html and https://django-celery-beat.readthedocs.io/en/latest/	rules/jobs-scheduling.md に独自の beat_schedule の形式を記載し、references/ork-delta.md にプロセスモデルを記載します
Flower のフラグ、inspect、シグナル名	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
結果バックエンド、AsyncResult、カスタム状態	https://docs.celeryq.dev/en/stable/userguide/configuration.html	rules/jobs-monitoring.md に独自のステータスエンドポイントと update_state() の使い方を記載します
タスクごとの 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 のステータス	https://arq-docs.helpmanual.io/	rules/jobs-task-queue.md にワーカーの骨組みを記載し、references/ork-delta.md に予算を記載します
FastAPI の lifespan と依存関係の接続	https://fastapi.tiangolo.com/advanced/events/	references/ork-delta.md
SET NX EX を使った分散ロック	https://redis.io/docs/latest/commands/set/	references/ork-delta.md

設定

読み込み：Read("references/celery-config.md")。

決定事項	推奨事項
シリアライザー	JSON（pickle は使用しない）
ACK モード	遅延 ACK（task_acks_late=True）
プリフェッチ	公平性を重視する場合は 1、スループット重視の場合は 4～8
時間制限	soft < hard（540 / 600）
タイムゾーン	常に UTC

タスクのルーティング

決定事項	推奨事項
キュー数	5：critical / high / default / low / bulk
優先度レベル	0～9。4 つの Redis 優先度スイッチをすべて同時に設定
ワーカーの割り当て	キューごとに専用のワーカーを割り当てる
プリフェッチ	critical は 1、high は 2、default は 4、low/bulk は 8
ルーティング	ルーティングルールが 5 つを超えたらルータークラスを使用

Canvas ワークフロー

読み込み：Read("rules/celery-canvas.md")。

決定事項	推奨事項
順次処理	s() を使った Chain
並列処理	独立したタスクには Group を使用
ファンイン	Chord（本体を実行するには、ヘッダー内のすべてのタスクが成功する必要があります）
入力を無視	不変のシグネチャ si() を使用
Chain 内のエラー	Reject は Chain を停止し、retry は続行します
部分的な失敗	Chord のヘッダータスクからエラー辞書を返す

リトライ戦略

判断項目	推奨事項
リトライ間隔	指数バックオフを使用し、ジッターを有効にして、600s を上限とします
最大リトライ回数	一時的なエラーは 3～5 回、恒久的なエラーは 0 回です
冪等性	Redis マーカー（TTL は 86400s）とベンダーの冪等性キーを併用します
失敗したタスク	手動レビュー用の DLQ を使用します
シングルトン	ハードタイムリミットより長い TTL を設定した Redis ロックを使用します

スケジューリング

読み込み：Read("rules/jobs-scheduling.md")。

判断項目	推奨事項
スケジュールタイプ	時刻ベースには Crontab、頻度指定には浮動小数点の間隔を使用します
動的なスケジュール	DatabaseScheduler（django-celery-beat）を使用します
重複実行	デフォルトは 3600s、長時間ジョブは 7200s の Redis ロックを使用します
Beat プロセス	別プロセスにします。埋め込みの --beat は開発用途のみです
タイムゾーン	常に UTC を使用します

モニタリング

判断項目	推奨事項
ダッシュボード	永続ストレージを備えた Flower を使用します
メトリクス	Prometheus を task_prerun / task_postrun / task_failure に接続します
ヘルス	ブローカーへの接続、ワーカーが 1 つ以上あること、キューの深さを確認します
アラート	critical > 100、default > 5000、ワーカー数 < 1
オートスケール	キューの深さ > 500

結果バックエンド

読み込み：Read("rules/jobs-monitoring.md")。

判断項目	推奨事項
ステータスの保存	Redis の結果バックエンドを使用し、ステータスと小さな JSON のみを保存します
大きな結果	S3 またはデータベースに保存し、タスクは参照先の dict を返します
進捗	update_state() でカスタム状態を使用します
結果のクエリ	状態を確認して AsyncResult を使用します

ARQ パターン

読み込み：Read("rules/jobs-task-queue.md")。

判断項目	推奨事項
シンプルな非同期処理	ARQ（ネイティブの非同期処理）を使用し、max_jobs=10、job_timeout=300 を設定します
プールの所有者	FastAPI の lifespan を使用します。リクエストごとに create_pool を呼び出してはいけません
複雑なワークフロー	Celery を使用します（チェーン、コード、DLQ、タスクごとのレート制限）
プロセス内の短時間処理	FastAPI BackgroundTasks を使用します。30s 未満かつ非クリティカルな処理に限ります
LLM ワークフロー	Celery ではなく LangGraph を使用します

ツールの選定

ツールの比較表（ARQ、Celery、RQ、Dramatiq、FastAPI BackgroundTasks）の全内容は、Read("references/quick-start-examples.md") を読み込んでください。

アンチパターン（禁止）

詳細な一覧は Read("references/anti-patterns.md") を読み込んでください。

主なルール：リクエストハンドラーで長時間タスクを実行しないこと、タスク内で結果を待機してブロックしないこと、Redis に大きな結果を保存しないこと、リトライ対象のタスクでは必ず冪等性を確保すること。

Temporal ワークフロー

読み込み：Read("rules/temporal-workflows.md")。

判断項目	推奨事項
ワークフロー ID	ビジネス上の意味を持たせ、冪等にします
決定性	workflow.random()、workflow.now() を使用します
I/O	常にアクティビティ経由で行い、直接実行しません

Temporal アクティビティ

読み込み：Read("rules/temporal-activities.md")。

判断項目	推奨事項
アクティビティのタイムアウト	ほとんどの場合、start_to_close を使用します
エラー処理	ビジネスエラーはリトライ不可にします
テスト	統合テストでは WorkflowEnvironment.start_local() を使用します

関連スキル

• ork:python-backend - FastAPI、asyncio、SQLAlchemy のパターン
• ork:langgraph - LangGraph のワークフローパターン（Celery ではなく LLM ワークフローに使用）
• ork:distributed-systems - レジリエンスパターン、サーキットブレーカー
• ork:monitoring-observability - メトリクスとアラート

機能の詳細

キーワードインデックスと問題から機能へのマッピングについては、Read("references/capability-details.md") を読み込んでください。