docs: Phase O 可觀測性終極補完計畫設計規格

SigNoz 統一派架構，解決 6 大盲區 (Event/Log/Metrics/Descheduler/kubectl/MinIO-Kali) + Monitoring Master Plan Wave A-D 收尾 + 5 個首席架構師 Review 節點 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-02 13:45:23 +08:00
parent 3ad7b60f68
commit 51961b9f03
1 changed files with 329 additions and 0 deletions
--- a/docs/superpowers/specs/2026-04-02-observability-ultimate-completion-design.md
+++ b/docs/superpowers/specs/2026-04-02-observability-ultimate-completion-design.md
@@ -0,0 +1,329 @@
+# AWOOOI 可觀測性終極補完計畫
+
+> **代號**: Phase O (Observability)
+> **決策**: 路線 A — SigNoz 統一派
+> **批准**: 統帥 2026-04-02
+> **架構師**: Claude Code (首席架構師)
+> **預估工時**: 12-15h (含 Wave A-D 收尾)
+
+---
+
+## 1. 戰略背景
+
+### 1.1 問題起源
+
+2026-04-02 K3s 健康檢查中發現「0 Pod 重啟」的數據，經深入分析確認為 **可觀測性盲區** 而非真實穩定：
+
+- K8s Event 僅保留 ~1 小時
+- Pod Log 隨容器消亡
+- Prometheus 預設 ~15 天保留
+- Descheduler PodSecurity 違規持續失敗
+- kubectl 存取需 sudo 密碼
+- MinIO/Kali 無監控
+
+### 1.2 架構決策
+
+| 選項 | 決策 | 理由 |
+|------|------|------|
+| A. SigNoz 統一派 | **採用** | 複用 ClickHouse、少一個故障點、單一查詢介面 |
+| B. Loki 獨立派 | 否決 | .188 已過載、增加維運複雜度、查詢分散 |
+
+---
+
+## 2. 六大盲區解決方案
+
+### O1: K8s Event 長期保留 (🔴 致命)
+
+**現狀**: Event 保留 ~1 小時，RCA 不可能
+**目標**: 30 天可查詢
+
+**方案**: 部署 `kubernetes-event-exporter` 為 K3s Deployment
+
+```
+K8s API Server (Event Watch)
+  → kubernetes-event-exporter (K3s Deployment)
+    → OTEL Collector (192.168.0.188:24318)
+      → SigNoz ClickHouse (結構化 Log 儲存)
+```
+
+**關鍵配置**:
+- 輸出格式: JSON Log (含 namespace, reason, involvedObject, message)
+- 過濾: 排除 Normal/Scheduled 高頻事件，保留 Warning + Error 全量
+- 保留期: SigNoz ClickHouse TTL 30 天
+
+### O2: Pod Log 集中聚合 (🔴 致命)
+
+**現狀**: Pod 死亡 = Log 永失
+**目標**: 所有 Pod Log 集中儲存 30 天
+
+**方案**: 部署 OTEL Collector DaemonSet (filelog receiver)
+
+```
+/var/log/pods/*/*/*.log (K3s 節點)
+  → OTEL Collector DaemonSet (K3s 節點本地)
+    → batch processor + filter processor
+      → OTEL Exporter → 192.168.0.188:24318
+        → SigNoz ClickHouse
+```
+
+**關鍵配置**:
+- Receiver: `filelog` 讀取 `/var/log/pods/*/*/*.log`
+- Processor:
+  - `k8s_attributes`: 自動注入 Pod name, namespace, node, labels
+  - `filter`: 捨棄 kube-system debug 等無用 log
+  - `batch`: 批次發送 (200 條/5 秒)
+- Resource Limits: CPU 100m / Memory 128Mi (DaemonSet 輕量)
+- 保留期: SigNoz ClickHouse TTL 30 天
+
+### O3: 長期指標儲存 (🔴 盲區)
+
+**現狀**: Prometheus ~15 天本地保留
+**目標**: 關鍵指標 90 天
+
+**方案**: Prometheus `remote_write` → SigNoz OTLP
+
+```
+Prometheus (192.168.0.188)
+  → remote_write (metric relabeling 過濾)
+    → SigNoz OTLP/HTTP (192.168.0.188:24318)
+      → ClickHouse (長期儲存)
+```
+
+**關鍵配置**:
+- `remote_write` 端點: `http://localhost:24318/api/v1/write` (同機免跨網路)
+- Metric Relabeling: **只轉發關鍵指標** (降低 ClickHouse 負擔)
+  - `node_cpu_seconds_total`, `node_memory_*` (節點)
+  - `container_cpu_*`, `container_memory_*` (容器)
+  - `kube_pod_container_status_restarts_total` (重啟)
+  - `http_request_duration_*`, `http_requests_total` (API)
+  - `awoooi_*` (自訂業務指標)
+  - `pg_*`, `redis_*` (資料庫)
+- 預估: ~50 個關鍵 metric series，90 天約 2-5 GB ClickHouse 儲存
+- Prometheus 本地保留維持 15 天 (全量)
+
+### O4: Descheduler PodSecurity 修復 (🔴 故障)
+
+**現狀**: CronJob 因 PodSecurity `restricted` 違規持續失敗
+**目標**: 正常執行
+
+**方案**: 修正 descheduler.yaml 加入 securityContext
+
+```yaml
+spec:
+  template:
+    spec:
+      securityContext:
+        runAsNonRoot: true
+        runAsUser: 65534  # nobody
+        seccompProfile:
+          type: RuntimeDefault
+      containers:
+        - name: descheduler
+          securityContext:
+            allowPrivilegeEscalation: false
+            readOnlyRootFilesystem: true
+            capabilities:
+              drop: ["ALL"]
+```
+
+### O5: kubectl 免密碼存取 (🔴 盲區)
+
+**現狀**: wooo 需 sudo 密碼
+**目標**: wooo 免密碼 + Mac 本機直接查詢
+
+**方案 (兩步)**:
+
+1. **K3s 節點**: 複製 kubeconfig 到 wooo home
+   ```bash
+   # 在 120 和 121 上
+   sudo cp /etc/rancher/k3s/k3s.yaml /home/wooo/.kube/config
+   sudo chown wooo:wooo /home/wooo/.kube/config
+   sudo chmod 600 /home/wooo/.kube/config
+   # 修改 server 為 VIP
+   sed -i 's|127.0.0.1|192.168.0.125|' /home/wooo/.kube/config
+   ```
+
+2. **Mac 本機**: 建立 kubeconfig
+   ```bash
+   mkdir -p ~/.kube
+   scp wooo@192.168.0.120:/home/wooo/.kube/config ~/.kube/config
+   # server 已指向 VIP 192.168.0.125:6443
+   ```
+
+### O6: MinIO / Kali 監控補齊 (🟠 盲區)
+
+**MinIO (192.168.0.188)**:
+- 啟用內建 Prometheus 端點: `MINIO_PROMETHEUS_AUTH_TYPE=public`
+- Prometheus scrape config 新增 target
+- 告警規則: `MinioDiskUsageHigh`, `MinioOffline`
+
+**Kali (192.168.0.112)**:
+- 部署 node-exporter (系統層級監控)
+- Blackbox Exporter TCP probe (8080 Scanner API)
+- 告警規則: `KaliScannerDown`, `KaliDiskFull`
+
+---
+
+## 3. Monitoring Master Plan 收尾 (Wave A-D)
+
+### 3.1 Wave A 剩餘 (P0)
+
+| # | 任務 | 狀態 | 工時 |
+|---|------|------|------|
+| A.1 | Sentry API Token 注入 K8s Secret | ⏳ | 15min |
+| A.2 | SignOz 告警規則部署到 SigNoz | ⏳ | 30min |
+| A.3 | SignOz Webhook Handler | ⏳ | 45min |
+| A.4 | Sentry Comment API 整合 | ⏳ | 30min |
+| A.5 | Alert Chain Metrics | ✅ 已完成 | — |
+| A.6 | Smoke Test Script | ⏳ | 45min |
+
+### 3.2 Wave B (P1) — CD 鏈路保護
+
+| # | 任務 | 工時 |
+|---|------|------|
+| B.1 | Alert Chain PrometheusRule | ✅ 已完成 |
+| B.2 | CD Pipeline Smoke Test 整合 | 45min |
+| B.3 | 文檔 + E2E 驗證 | 30min |
+
+### 3.3 Wave C (P2) — 監控即代碼
+
+| # | 任務 | 工時 |
+|---|------|------|
+| C.1 | generate_monitoring.py 自動發現 | 1h |
+| C.2 | CI coverage 驗證 | 45min |
+| C.3 | Docker 容器自動發現 | 1h |
+
+### 3.4 Wave D (P3) — 視覺化
+
+| # | 任務 | 工時 |
+|---|------|------|
+| D.1 | NVIDIA Grafana Dashboard | 1.5h |
+| D.2 | 監控覆蓋率報告 | 1.5h |
+
+---
+
+## 4. SigNoz ClickHouse 容量規劃
+
+| 資料類型 | 每日估算 | 30天 | 90天 | 壓縮率 |
+|----------|---------|------|------|--------|
+| K8s Events (O1) | ~5 MB | 150 MB | — | 10:1 |
+| Pod Logs (O2) | ~200 MB | 6 GB | — | 5:1 |
+| 指標 Remote Write (O3) | ~50 MB | — | 4.5 GB | 20:1 |
+| Traces (現有) | ~100 MB | 3 GB | — | 10:1 |
+| **合計** | **~355 MB/天** | **~10 GB** | **~15 GB** | — |
+
+**.188 磁碟現況**: 使用中 ~60%（估計），新增 15 GB 完全可承受。
+
+**清理策略**: ClickHouse TTL 自動過期，無需人工介入。
+
+---
+
+## 5. 細化實施步驟 (16 Steps)
+
+### Phase O-1: 基礎設施修復 (2h)
+> 🏗️ **首席架構師 Review 節點: O-1 完成後**
+
+| Step | 任務 | 工時 | 類型 |
+|------|------|------|------|
+| **1.1** | Descheduler securityContext 修復 + 部署驗證 | 30min | K8s YAML |
+| **1.2** | kubectl 免密碼 (120/121 kubeconfig + Mac 本機) | 30min | 基礎設施 |
+| **1.3** | MinIO Prometheus 端點啟用 + scrape config | 30min | 監控 |
+| **1.4** | Kali node-exporter + Blackbox probe 設定 | 30min | 監控 |
+
+**Review 重點**: Descheduler PSA 合規性、kubeconfig 權限安全性、監控 target 覆蓋率
+
+### Phase O-2: OTEL Log 收集管線 (3h)
+> 🏗️ **首席架構師 Review 節點: O-2 完成後**
+
+| Step | 任務 | 工時 | 類型 |
+|------|------|------|------|
+| **2.1** | OTEL Collector DaemonSet YAML (filelog receiver) | 1h | K8s YAML |
+| **2.2** | kubernetes-event-exporter Deployment YAML | 45min | K8s YAML |
+| **2.3** | SigNoz ClickHouse TTL 設定 (Log 30天 / Metrics 90天) | 30min | 基礎設施 |
+| **2.4** | 部署到 K3s + Log 流入驗證 | 45min | 驗證 |
+
+**Review 重點**: OTEL Collector 配置 (filter/batch processor)、NetworkPolicy egress 規則、ClickHouse TTL 正確性、資源限制合理性
+
+### Phase O-3: 長期指標 + Prometheus Remote Write (1.5h)
+> 🏗️ **首席架構師 Review 節點: O-3 完成後**
+
+| Step | 任務 | 工時 | 類型 |
+|------|------|------|------|
+| **3.1** | Prometheus remote_write 配置 + metric relabeling | 45min | 配置 |
+| **3.2** | 部署驗證: SigNoz Metrics Explorer 確認資料流入 | 30min | 驗證 |
+| **3.3** | 告警規則: MinIO + Kali + ClickHouse 磁碟 | 15min | 監控 |
+
+**Review 重點**: metric relabeling 白名單是否遺漏關鍵指標、ClickHouse 寫入效能、告警閾值合理性
+
+### Phase O-4: Wave A 收尾 — 告警鏈路完整化 (2.5h)
+
+| Step | 任務 | 工時 | 類型 |
+|------|------|------|------|
+| **4.1** | Sentry API Token 注入 + K8s Secret | 15min | Secret |
+| **4.2** | SignOz 告警規則部署 | 30min | 配置 |
+| **4.3** | SignOz Webhook Handler (signoz_webhook.py) | 45min | 程式碼 |
+| **4.4** | Sentry Comment API 整合 | 30min | 程式碼 |
+| **4.5** | Smoke Test Script + CD 整合 (A.6 + B.2) | 30min | 程式碼 |
+
+### Phase O-5: Wave B-C — CD 保護 + 監控即代碼 (3h)
+> 🏗️ **首席架構師 Review 節點: O-5 完成後 (含 O-4)**
+
+| Step | 任務 | 工時 | 類型 |
+|------|------|------|------|
+| **5.1** | CD Pipeline Smoke Test 整合到 cd.yaml | 30min | CI/CD |
+| **5.2** | generate_monitoring.py 自動發現 | 1h | 程式碼 |
+| **5.3** | CI coverage 驗證 + Docker 容器自動發現 | 1h | 程式碼 |
+| **5.4** | E2E 告警鏈路驗證文檔 | 30min | 文檔 |
+
+**Review 重點**: Webhook handler 程式碼品質、CD smoke test 可靠性、generate_monitoring 邏輯正確性、**告警鏈路 E2E 端到端測試**
+
+### Phase O-6: Wave D — 視覺化 + 最終驗收 (3h)
+> 🏗️ **首席架構師 Final Review: 全量驗收**
+
+| Step | 任務 | 工時 | 類型 |
+|------|------|------|------|
+| **6.1** | NVIDIA Grafana Dashboard | 1.5h | 視覺化 |
+| **6.2** | 監控覆蓋率報告 | 1h | 文檔 |
+| **6.3** | ADR-052 撰寫 (可觀測性統一架構決策) | 30min | ADR |
+
+**Final Review 重點**: 全部 6 大盲區驗證、監控覆蓋率 ≥95%、ClickHouse 資源消耗實測、OpenClaw RCA 查詢路徑驗證
+
+---
+
+## 6. 首席架構師 Review 矩陣
+
+| Review 節點 | Phase | 審查類型 | 審查重點 |
+|-------------|-------|----------|----------|
+| **R1** | O-1 完成 | 基礎設施 | PSA 合規、權限安全、監控覆蓋 |
+| **R2** | O-2 完成 | 架構 + 配置 | OTEL 管線正確性、TTL、NetworkPolicy、資源限制 |
+| **R3** | O-3 完成 | 配置 + 效能 | Remote write 白名單、ClickHouse 寫入效能 |
+| **R4** | O-4+O-5 完成 | 程式碼 + E2E | Webhook code quality、CD smoke test、告警鏈路 E2E |
+| **R5 (Final)** | O-6 完成 | 全量驗收 | 6 大盲區全數封閉、覆蓋率報告、ADR 品質 |
+
+**Review 標準**: 沿用現有評分體系 (100 分制，90+ OUTSTANDING)
+
+---
+
+## 7. 風險與緩解
+
+| 風險 | 機率 | 影響 | 緩解 |
+|------|------|------|------|
+| ClickHouse OOM (.188 記憶體不足) | 低 | 高 | TTL 嚴格控制 + 日誌過濾 + 監控 ClickHouse memory |
+| OTEL DaemonSet 影響 K3s 節點效能 | 低 | 中 | 資源限制 100m/128Mi + 實測 |
+| Prometheus remote_write 高基數爆炸 | 中 | 高 | metric relabeling 白名單，只轉 ~50 series |
+| Log Storm 衝垮 SigNoz | 低 | 高 | filter processor 捨棄 debug + batch 限流 |
+
+---
+
+## 8. 驗收標準 (Definition of Done)
+
+- [ ] kubectl 可從 Mac 本機免密碼查詢所有 namespace
+- [ ] K8s Event 可在 SigNoz 查到 7 天前的 Warning 事件
+- [ ] 已死亡的 Pod Log 可在 SigNoz 查到
+- [ ] Prometheus 90 天前的關鍵指標可在 SigNoz 查到
+- [ ] Descheduler CronJob 成功執行至少 3 次
+- [ ] MinIO + Kali 出現在 Prometheus targets 且 UP
+- [ ] Wave A-D 全部任務完成
+- [ ] 告警鏈路 E2E 測試通過 (Alertmanager → API → Telegram)
+- [ ] ClickHouse 磁碟使用增長 < 預估 120%
+- [ ] ADR-052 已撰寫並 commit