awoooi/docs/adr/ADR-048-sentry-openclaw-ai-triage.md

ADR-048: Sentry → OpenClaw AI Triage 自動化

狀態: 已實作 (Phase 23) 日期: 2026-04-01 (台北時區) 作者: Claude Code 關聯: Phase 10 (Sentry 基礎整合), Phase 21 (ADR-037 異常頻率統計), Phase 22 (ADR-044 Nemotron 協作)

---

問題陳述

Sentry 持續捕獲後端 Python 與前端 Next.js 錯誤，但缺乏自動化 triage 流程：

• 工程師需手動查看 Sentry Issue 並判斷嚴重程度
• 錯誤發生後沒有即時通知渠道（Telegram）
• 無法自動關聯歷史頻率判斷是否為常態錯誤或異常升級
• 沒有 AI 輔助根因分析，所有診斷依賴人工

目標：Sentry 新錯誤觸發時，自動完成 triage → AI 分析 → Incident 建立 → Telegram 通知，無需人工介入。

---

決策

透過 Sentry Issue Alert Webhook 整合 OpenClaw AI Triage 流程。

選擇 Webhook 而非輪詢的原因

方案	延遲	基礎設施成本	複雜度
Webhook (本方案)	近即時 (<2s)	無額外組件	低
輪詢 (每分鐘)	最高 60s	需 scheduler	中
Sentry Alerts API	近即時	需 OAuth	高

---

架構

自架 Sentry (192.168.0.110:9000)
    │  Issue Alert Webhook (action=triggered, level=error/fatal)
    ▼
AWOOOI API  POST /api/v1/webhooks/sentry/error
    │
    ├─ [同步] 去重檢查 (Redis, 10min TTL)
    ├─ [同步] Level 過濾 (只處理 error/fatal)
    │
    └─ [背景 BackgroundTask]
         │
         ├─ 1. AnomalyCounter.record_anomaly() → 頻率統計
         │      (ADR-037: 1h/24h/7d/30d + 升級判斷)
         │
         ├─ 2. OpenClawHttpService.analyze_error()
         │      Circuit Breaker (ADR-038) + Semaphore
         │      優先 Ollama (本地) → Fallback Claude
         │      → ErrorAnalysisResult (root_cause, fix, prevention, confidence)
         │
         ├─ 3. ApprovalService.create_approval()
         │      風險等級 = Sentry Level + 頻率升級
         │      → Approval ID
         │
         ├─ 4. TelegramGateway.send_approval_card()
         │      格式: 🐛 SENTRY 錯誤告警 + OpenClaw 分析 + [Y/n]
         │
         └─ 5. SentryService.post_issue_comment()
                AI 分析結果回寫至 Sentry Issue

Sentry Cloud (wooo-92.sentry.io) 前端整合

前端 Next.js 錯誤透過 Sentry Cloud 捕獲，使用相同 Webhook 格式。 在 Sentry Cloud 配置 Alert Rule 指向同一端點： POST https://awoooi.wooo.work/api/v1/webhooks/sentry/error

---

實作細節

端點

POST /api/v1/webhooks/sentry/error

觸發條件 (Sentry Alert Rule 配置)

• action: triggered
• level: error 或 fatal

去重策略

• Redis key: sentry_dedup:{issue_id}
• TTL: 600 秒 (10 分鐘)
• 同一 issue 10 分鐘內不重複處理

風險等級映射

Sentry Level	基礎風險	頻率升級 (ESCALATE)	頻率升級 (PERMANENT_FIX)
fatal	CRITICAL	CRITICAL	CRITICAL
error	HIGH	HIGH	CRITICAL
warning	MEDIUM	HIGH	CRITICAL

Webhook Secret 驗證

• Config: SENTRY_WEBHOOK_SECRET
• Header: sentry-hook-signature (HMAC-SHA256)
• 生產環境未設定 → Fail-Closed 拒絕
• 開發環境未設定 → 允許跳過 (僅供測試)

---

影響評估

正向影響

• MTTR 縮短: AI 自動根因分析，工程師無需從 log 推斷
• 告警品質提升: 頻率統計避免重複告警噪音
• 可審計性: 所有 Sentry Issue 自動建立 Approval 記錄
• 回饋閉環: AI 分析結果回寫 Sentry Comment，歷史可查

風險與緩解

風險	緩解措施
OpenClaw 不可用	Circuit Breaker (ADR-038) + 降級：無 AI 分析仍建立 Approval
Telegram 傳送失敗	Exception catch + log，不中斷主流程
Redis 不可用	check_dedup 失敗 → 預設 True（允許處理，可能重複）
Sentry API Token 未設	Comment 回寫跳過，其他流程不受影響

不影響項目

• 現有 Alertmanager → AWOOOI → Telegram 流程不變
• 現有 GitHub Webhook 整合不變
• Sentry SDK 錯誤捕獲邏輯不變

---

相關檔案

• Router: apps/api/src/api/v1/sentry_webhook.py
• Service (Sentry API): apps/api/src/services/sentry_service.py
• Service (Webhook 業務邏輯): apps/api/src/services/sentry_webhook_service.py
• Config: apps/api/src/core/config.py (SENTRY_WEBHOOK_SECRET)
• Circuit Breaker: apps/api/src/core/circuit_breaker.py (ADR-038)

---

後續工作

• 在自架 Sentry 配置 Issue Alert Rule 指向 /webhooks/sentry/error
• 在 Sentry Cloud 配置相同 Alert Rule
• K8s Secret 注入 SENTRY_WEBHOOK_SECRET
• E2E 測試：手動觸發 Sentry Issue → 驗證 Telegram 收到告警