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

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

   # 在 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

   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