From 51961b9f03a1ba2419945eca8ac99b5e72efd65f Mon Sep 17 00:00:00 2001 From: OG T Date: Thu, 2 Apr 2026 13:45:23 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20Phase=20O=20=E5=8F=AF=E8=A7=80=E6=B8=AC?= =?UTF-8?q?=E6=80=A7=E7=B5=82=E6=A5=B5=E8=A3=9C=E5=AE=8C=E8=A8=88=E7=95=AB?= =?UTF-8?q?=E8=A8=AD=E8=A8=88=E8=A6=8F=E6=A0=BC?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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) --- ...bservability-ultimate-completion-design.md | 329 ++++++++++++++++++ 1 file changed, 329 insertions(+) create mode 100644 docs/superpowers/specs/2026-04-02-observability-ultimate-completion-design.md diff --git a/docs/superpowers/specs/2026-04-02-observability-ultimate-completion-design.md b/docs/superpowers/specs/2026-04-02-observability-ultimate-completion-design.md new file mode 100644 index 00000000..944e46cb --- /dev/null +++ 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