dbe0da057c
Three proposals addressing the 2026-02-25 trace pipeline OOM crash (114K CIDs): 1. trace-events-memory-triage: fetchmany iterator (read_sql_df_slow_iter), admission control (50K CID limit for non-MSD), cache skip for large queries, early memory release with gc.collect() 2. trace-async-job-queue: RQ-based async jobs for queries >20K CIDs, separate worker process with isolated memory, frontend polling via useTraceProgress composable, systemd service + deploy scripts 3. trace-streaming-response: chunked Redis storage (TRACE_STREAM_BATCH_SIZE=5000), NDJSON stream endpoint (GET /api/trace/job/<id>/stream), frontend ReadableStream consumer for progressive rendering, backward-compatible with legacy single-key storage All three proposals archived. 1101 tests pass, frontend builds clean. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
46 lines
2.3 KiB
Markdown
46 lines
2.3 KiB
Markdown
## Why
|
||
|
||
trace pipeline 處理大量 CIDs（> 20K）時，即使經過分批處理優化（提案 1），
|
||
仍然面臨以下根本問題：
|
||
|
||
1. **同步 request-response 模型**：gunicorn 360s timeout 是硬限，lineage + events 合計可能超過 300s
|
||
2. **worker thread 被佔住**：大查詢期間 1 個 gunicorn thread 完全被佔用，降低即時頁服務能力
|
||
3. **前端無進度回饋**：使用者只能盯著 loading spinner 等 5-6 分鐘，不知道是否正常運作
|
||
4. **失敗後需完全重新執行**：中途 timeout/OOM 後，已完成的 seed-resolve 和 lineage 結果全部浪費
|
||
|
||
業界標準做法是將長時間任務放入非同步佇列（RQ/Dramatiq），API 先回 202 + job_id，
|
||
背景 worker 獨立處理，前端輪詢或 SSE 取得結果。
|
||
|
||
## What Changes
|
||
|
||
- **引入 RQ（Redis Queue）**：利用既有 Redis 基礎設施，最小化新依賴
|
||
- **新增 trace job worker**：獨立進程（systemd unit），不佔 gunicorn worker 資源
|
||
- **新增 `POST /api/trace/events-async`**：CID > 閾值時回 202 + job_id
|
||
- **新增 `GET /api/trace/job/{job_id}`**：輪詢 job 狀態（queued/running/completed/failed）
|
||
- **新增 `GET /api/trace/job/{job_id}/result`**：取得完成後的結果（分頁）
|
||
- **前端 useTraceProgress 整合**：自動判斷同步/非同步路徑，顯示 job 進度
|
||
- **Job TTL + 自動清理**：結果保留 1 小時後自動過期
|
||
- **新增 systemd unit**：`mes-dashboard-trace-worker.service`
|
||
- **更新 .env.example**：`TRACE_ASYNC_CID_THRESHOLD`、`TRACE_JOB_TTL_SECONDS`、`TRACE_WORKER_COUNT`
|
||
|
||
## Capabilities
|
||
|
||
### New Capabilities
|
||
|
||
- `trace-async-job`: 非同步 trace job 佇列（RQ + Redis）
|
||
|
||
### Modified Capabilities
|
||
|
||
- `trace-staged-api`: events endpoint 整合 async job 路由
|
||
- `progressive-trace-ux`: 前端整合 job 輪詢 + 進度顯示
|
||
|
||
## Impact
|
||
|
||
- **新增依賴**：`rq>=1.16.0,<2.0.0`（requirements.txt、environment.yml）
|
||
- **後端新增**：trace_job_service.py、trace_routes.py（async endpoints）
|
||
- **前端修改**：useTraceProgress.js（async 整合）
|
||
- **部署新增**：deploy/mes-dashboard-trace-worker.service、scripts/start_server.sh（worker 管理）
|
||
- **部署設定**：.env.example（新 env vars）
|
||
- **不影響**：其他 service、即時監控頁、admin 頁面
|
||
- **前置條件**：trace-events-memory-triage（提案 1）
|