awoooi/docs/superpowers/specs/2026-04-02-observability-ultimate-completion-design.md

# 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