awoooi/docs/adr/ADR-022-sentry-integration-architecture.md

ADR-022: Sentry 整合架構

項目	內容
狀態	✅ 已採用
日期	2026-03-26
決策者	首席架構師 + 統帥
Phase	Phase 10

背景

AWOOOI 需要完整的錯誤追蹤能力，補強 SignOz APM 的不足：

• SignOz 專注效能監控 (Traces, Metrics)
• Sentry 專注錯誤追蹤 (Stacktrace, Context, Session Replay)

決策

採用 BFF + AI 分析 三層架構：

┌─────────────────────────────────────────────────────────────┐
│                    AWOOOI Web UI                            │
│         /errors 頁面 (React + next-intl)                    │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                  AWOOOI API (BFF Layer)                     │
│         Router: /api/v1/errors/*                            │
│         Service: SentryService + ErrorAnalyzerService       │
└─────────────────────────────────────────────────────────────┘
                              │
              ┌───────────────┼───────────────┐
              ▼                               ▼
┌──────────────────────┐         ┌──────────────────────────┐
│   Sentry Self-Hosted │         │   OpenClaw LLM           │
│   192.168.0.110:9000 │         │   192.168.0.188:8088     │
└──────────────────────┘         └──────────────────────────┘

架構組件

1. SentryService (services/sentry_service.py)

職責: 封裝 Sentry API 呼叫

class SentryService:
    async def list_projects() -> list[dict]
    async def list_issues(query, limit, cursor) -> list[dict]
    async def get_issue(issue_id) -> dict
    async def get_issue_events(issue_id, limit, full) -> list[dict]
    async def get_project_stats(stat, resolution) -> list
    def get_issue_url(issue_id) -> str

設計原則:

• Singleton 模式
• 配置從 core/config.py Settings 取得
• 支援 DI 測試替換

2. ErrorAnalyzerService (services/error_analyzer_service.py)

職責: AI 根因分析

class ErrorAnalyzerService:
    async def analyze_error(
        issue_id, title, level, culprit,
        count, stacktrace, context
    ) -> tuple[ErrorAnalysisResult | None, str, bool]

分析結果:

• root_cause: 根因分析
• category: CODE_BUG | DEPENDENCY | CONFIGURATION | ...
• severity: LOW | MEDIUM | HIGH | CRITICAL
• fix_recommendation: 修復建議
• prevention: 預防措施
• confidence: 信心度 (0.0-1.0)

3. Router Layer (api/v1/errors.py)

職責: HTTP 轉發 (符合 leWOOOgo 積木化)

端點	功能
GET /stats	錯誤統計概覽
GET /issues	列出 Issues (分頁、過濾)
GET /issues/{id}	Issue 詳情
GET /trends	趨勢圖表數據
POST /issues/{id}/analyze	觸發 AI 分析

配置管理

所有 Sentry 配置集中於 core/config.py:

SENTRY_SELF_HOSTED_URL: str = "http://192.168.0.110:9000"
SENTRY_ORG: str = "sentry"
SENTRY_PROJECT: str = "awoooi-api"
SENTRY_AUTH_TOKEN: str = ""  # K8s Secret

與 SignOz 的關係

工具	職責	查看時機
SignOz	APM + Traces	慢、效能問題
Sentry	Error Tracking	壞、錯誤堆疊

互補策略: 兩者皆部署，各司其職。

前端整合

• 使用 next-intl 100% i18n (禁止 hardcode)
• Nothing.tech 視覺規範 (白底、細邊框、無陰影)
• React Hook: useErrors() 自動刷新 60 秒

替代方案 (已拒絕)

方案	拒絕原因
直接嵌入 Sentry Iframe	違反視覺主權，無法自訂 UI
前端直接呼叫 Sentry API	違反 BFF 原則，CORS 問題
只用 SignOz	錯誤追蹤能力不足

後果

正面

• 完整的錯誤追蹤能力
• AI 輔助根因分析
• 符合 leWOOOgo 架構

負面

• 多一個服務需維護 (Sentry Self-Hosted)
• 額外的 API 呼叫延遲

相關文件

• project_phase10_arch_review.md - 架構審查報告
• project_sentry_full_integration.md - 整合計畫
• ADR-005: BFF Architecture
• ADR-006: AI Fallback Strategy