# ADR-053: 可觀測性統一架構 — SigNoz 統一派

| 欄位 | 值 |
|------|-----|
| **狀態** | Accepted |
| **日期** | 2026-04-02 (台北時間) |
| **決策者** | 統帥 (ogt) |
| **首席架構師** | Claude Code |
| **相關 ADR** | ADR-035 (Telegram Alert), ADR-037 (監控增強), ADR-039 (Gitea CI/CD) |

---

## 背景

2026-04-02 K3s 健康盤點中發現「0 Pod 重啟、0 異常」的數據，經深入分析確認為**可觀測性盲區**所造成的假象，而非真實穩定：

1. K8s Event 預設僅保留 ~1 小時
2. Pod Log 隨容器消亡而永久消失
3. Prometheus 預設 ~15 天保留，無長期趨勢
4. Descheduler PodSecurity 違規，CronJob 持續失敗
5. kubectl 存取需 sudo 密碼
6. MinIO/Kali 無監控覆蓋

這些盲區對 OpenClaw AI 的 RCA (Root Cause Analysis) 能力構成致命威脅：**「案發現場」已被清空，再聰明的 AI 也只能瞎猜。**

---

## 決策

### 路線選擇

| 選項 | 決策 | 理由 |
|------|------|------|
| **A. SigNoz 統一派** | **採用** | 複用 ClickHouse、零新增服務、單一查詢介面 |
| B. Loki 獨立派 | 否決 | .188 過載、維運複雜度增加、查詢分散 |

### 核心架構

```
所有 Log/Event 來源
  → OTEL Collector (DaemonSet, K3s 節點)
  → 192.168.0.188:24318 (SigNoz OTEL Collector HTTP)
  → ClickHouse (統一儲存)
  → SigNoz UI (統一查詢)

SigNoz OTEL Collector (Prometheus Receiver)
  → 直接 scrape node-exporter (172.28.0.1:9100)
  → 直接 scrape kube-state-metrics (192.168.0.121:30888)
  → SigNoz ClickHouse (長期儲存)

注意: 原計畫 Prometheus remote_write 因 SigNoz 不支援 Protobuf 格式而廢棄
      改用 OTEL Collector 內建 prometheus receiver 直接 scrape 關鍵指標
```

---

## 實施內容 (Phase O)

### O-1: 基礎設施修復

| 項目 | 修復內容 |
|------|---------|
| Descheduler | securityContext PSA restricted 合規 + RBAC 補齊 + namespace PSA label |
| kubectl | Mac 本機 kubeconfig 指向 VIP，免 SSH |
| MinIO 監控 | Prometheus scrape config + 4 條告警規則 |
| Kali 監控 | Blackbox TCP probe + 1 條告警規則 |

### O-2: OTEL Log 管線

| 組件 | 功能 |
|------|------|
| OTEL Collector DaemonSet | filelog receiver → 所有 Pod stdout/stderr → SigNoz |
| Event Exporter | K8s Warning/Error Events → 結構化 JSON → SigNoz |
| 保留期 | Log/Event 30 天，Metrics 90 天 (ClickHouse TTL) |

### O-3: 長期指標

Prometheus `remote_write` → SigNoz，僅轉 8 類關鍵 metric series：
node / container / kube-state / API / awoooi 自訂 / DB / probe / up

### O-4: Wave A 告警鏈路收尾

| Wave 項目 | 狀態 |
|-----------|------|
| A.1 Sentry Token CD 注入 | ✅ |
| A.2 SignOz 告警規則 | 待 .188 手動部署 |
| A.3 SignOz Webhook Handler | ✅ (2026-03-29 已實作) |
| A.4 Sentry Comment API | ✅ (2026-03-29 已實作) |
| A.5 Alert Chain Metrics | ✅ (2026-03-29 已實作) |
| A.6 Smoke Test Script | ✅ scripts/alert_chain_smoke_test.py |
| B.2 CD Smoke Test 整合 | ✅ cd.yaml |

---

## 關鍵設計決策

### 1. observability namespace PSA = privileged

OTEL Collector 必須以 root 讀取 `/var/log/pods`（該目錄 root:root 0750）。這是業界標準做法（Promtail、Fluentbit 亦同），不可避免。**僅限 observability namespace**，其他 namespace 維持 restricted。

### 2. Prometheus white-list remote_write

不全量 remote_write，只轉 ~50 個關鍵指標，防止 ClickHouse 高基數爆炸。完整指標保留在 Prometheus 本地 15 天。

### 3. Event 過濾策略

Warning/Error Event 全量保留。Normal/Scheduled/Pulling/Pulled/Created/Started 等高頻無意義 Event 丟棄，降低 ClickHouse 儲存壓力。

---

## 驗收標準

- [x] kubectl 可從 Mac 本機免密碼查詢所有 namespace
- [x] OTEL Collector 2 Pod Running (mon + mon1)
- [x] Event Exporter 1 Pod Running
- [x] Descheduler CronJob 正常執行 (Completed)
- [x] MinIO 監控 up (Bearer Token 認證，mc admin prometheus generate)
- [x] Kali Scanner TCP probe up
- [x] MinIO/Kali 告警規則已加入 Prometheus (追加至 alerts.yml，7 groups)
- [x] SigNoz 指標流入 (OTEL Collector prometheus receiver: node + kube-state)
- [x] Alert Chain Smoke Test 7/8 PASSED (1 non-critical: 指標剛啟動)
- [x] CD Pipeline 整合 Alert Chain Smoke Test + Sentry Token 注入
- [x] ClickHouse TTL 設定完成 — signoz_logs 30天 (已內建) / signoz_metrics 90天 (8表已修改)
- [x] ~~Prometheus remote_write~~ → 改用 OTEL Collector federation scrape (SigNoz 不支援 remote_write 格式)

---

## 後續行動

1. SSH 到 .188 部署剩餘配置 (prometheus-config-phase-o.yaml / prometheus-remote-write-signoz.yaml / minio-kali-alerts.yaml / SigNoz rules)
2. Wave D: NVIDIA Grafana Dashboard + 監控覆蓋率報告

---

## 影響評估

| 項目 | 影響 |
|------|------|
| .188 磁碟 | +~10-15 GB (30-90 天保留，ClickHouse 自動 TTL) |
| .188 CPU | +~50-200m (OTEL Collector 轉發) |
| K3s 節點 | +50m/64Mi per node (OTEL Collector DaemonSet) |
| OpenClaw RCA 能力 | **大幅提升** — 30 天 Log/Event 可查，90 天指標趨勢 |
