2f5986df5c
ADR 編號修正: - ADR-023 failure-auto-repair → ADR-028 - ADR-025 cicd-ai-integration → ADR-029 新增 ADR: - ADR-021: Playbook 更新驗證 - ADR-022: Sentry 整合架構 - ADR-027: Incident-Approval 同步 - ADR-028: 失敗自動修復閉環 - ADR-029: CI/CD AI 整合 (原 ADR-025) 更新: - ADR-018: LLM 測試策略狀態更新 Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
145 lines
4.9 KiB
Markdown
145 lines
4.9 KiB
Markdown
# 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 呼叫
|
||
|
||
```python
|
||
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 根因分析
|
||
|
||
```python
|
||
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`:
|
||
|
||
```python
|
||
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
|