hazel-shen · hazel-shen · Jul 4, 2026 · Jul 4, 2026 · Jul 4, 2026
diff --git a/observability/README.md b/observability/README.md
@@ -1,17 +1,17 @@
 # Observability（本機 Prometheus + Grafana）
 
-這個資料夾提供一套 **本機監控環境**，用於觀察 FAQ Bot 的執行情況：
+這個資料夾提供一套 **本機監控環境**，用於觀察 FAQ Bot 與 Agent Governance Policy Gate 的執行情況：
 
-- **Prometheus**：抓取後端 `/metrics`（FastAPI 服務）
-- **Grafana**：內建一個「FAQ Bot Overview」儀表板（JSON 可匯入）
-- **可選**：將資料 **remote_write 到 Grafana Cloud**（在 `prometheus.yml` 內已有註解）
+- **Prometheus**：抓取三個來源的指標
+- **Grafana**：由 provisioning 自動載入 datasource 與 dashboard，無需手動匯入
+- **可選**：將資料 remote_write 到 Grafana Cloud（在 `prometheus.yml` 內已有註解）
 
 ---
 
 ## 前置需求
 
 - 已安裝 **Docker** 與 **Docker Compose**
-- 後端 FastAPI 服務需已在 [http://localhost:8000/metrics](http://localhost:8000/metrics) 暴露 Prometheus 指標
+- 後端 FastAPI 服務（faq-api）需已在 `http://localhost:8000/metrics` 暴露 Prometheus 指標
 
 ---
 
@@ -31,55 +31,82 @@ docker-compose up -d
   - 預設帳密：`admin / admin`
   - 首次登入會要求修改密碼
 
-### 設定 Prometheus Data Source
+### Datasource 自動載入
 
-首次登入 Grafana 後：
+Datasource（Prometheus，uid: `prometheus`）由 `provisioning/datasources/` 自動配置，無需手動設定。
 
-1. 進入 **Connections** → **Data Sources**
-2. 新增 **Prometheus**
-3. URL 填入：`http://prometheus:9090`  
-   （因為 Grafana 與 Prometheus 在同一個 docker compose 網路中）
+### Dashboard 自動載入
 
-> 若登入後已自動帶入 Prometheus Data Source，可略過這一步。
+Dashboard 由 `provisioning/dashboards/default.yml` 自動掃描 `dashboards/` 子目錄，啟動後 Grafana 側會出現兩個資料夾：
 
-### 匯入儀表板
+| Grafana 資料夾 | 來源目錄 | Dashboard |
+|---|---|---|
+| `governance` | `dashboards/governance/` | Agent Governance — Policy Gate |
+| `faq` | `dashboards/faq/` | FAQ Bot Overview v2 |
 
-1. **Grafana** → **Dashboards** → **Import**
-2. 上傳 `dashboards/faq-bot-overview.json`
-3. 匯入完成後會看到 **FAQ Bot Overview** 儀表板
+> `dashboards-archive/` 不在掛載路徑內，Grafana 不再載入其中的舊版 dashboard（faq-bot-overview_v1）。
 
 ---
 
-## 主要指標（Prometheus metrics）
+## Prometheus Scrape 來源
+
+三個 scrape 目標：
+
+| 服務 | 位址 | 說明 |
+|---|---|---|
+| faq-api | `http://host.docker.internal:8000/metrics` | FAQ Bot FastAPI 後端 |
+| Pushgateway | `http://pushgateway:9091` | agent-governance-demo 的 Policy Gate 指標（`honor_labels: true`） |
+| OPA | `http://opa:8181/metrics` | OPA binary 自身指標（決策延遲等） |
+
+---
+
+## 排練前清場
+
+governance dashboard 為**示意數據**（demo 環境，非生產統計）。排練前可用 agent-governance-demo 的清場腳本清掉舊 schema 殘留：
+
+```bash
+cd ../agent-governance-demo
+bash scripts/metrics_reset.sh
+```
+
+清場後再跑 `bash scripts/run_demo.sh 2 stub` 產資料，確認「累加不倒退」後再上台。
+
+---
 
-FAQ Bot 服務會輸出以下常用指標：
+## 主要指標（Prometheus metrics）
 
-### 請求數與延遲
+### FAQ Bot（faq-api）
 
+#### 請求數與延遲
 - `llm_requests_total`
 - `llm_request_latency_seconds`
 
-### Token 與成本
-
+#### Token 與成本
 - `llm_tokens_total`
 - `llm_cost_total_usd_total`
 
-### 快取相關
-
+#### 快取相關
 - `rag_cache_requests_total`
 - `rag_cache_results_total`
 
-### 子流程延遲
-
+#### 子流程延遲
 - `rag_embedding_latency_seconds`
 - `rag_retrieval_latency_seconds`
 - `rag_rerank_latency_seconds`
 - `rag_llm_latency_seconds`
 
-### 輸入檢查 / 限流
-
+#### 輸入檢查 / 限流
 - `input_*`
 
+### Agent Governance（Pushgateway，job="agent-governance-demo"）
+
+- `tool_gate_allow_total` / `tool_gate_blocked_total` / `tool_gate_approval_total`
+- `tool_gate_audit_event`
+- `policy_anomaly_triggered_total`
+- `policy_patch_proposed_total` / `policy_patch_accepted_total` / `policy_patch_rejected_total`
+- `opa_test_result` / `opa_test_run_total` / `opa_test_duration_seconds`
+- `push_time_seconds`（資料新鮮度）
+
 ---
 
 ## （可選）送資料到 Grafana Cloud
@@ -94,10 +121,6 @@ remote_write:
     basic_auth:
       username: "<instance id or user>"
       password: "<grafana cloud api key>"
-    write_relabel_configs:
-      - source_labels: [job]
-        target_label: job
-        replacement: "faq-bot-dev"
 ```
 
 3. 重新啟動：
@@ -107,10 +130,6 @@ docker compose down
 docker compose up -d
 ```
 
-**建議**：用不同 job/label 區分 dev 與 prod，避免資料混在一起。
-
-**注意**：Grafana Cloud Free Plan 保留時間為 14 天，remote_write 會增加流量與存放量。
-
 ---
 
 ## 關閉 / 清除資料
@@ -126,14 +145,3 @@ docker volume rm observability_prom_data observability_grafana_data
 ```
 
 ⚠️ **如果要保留 Grafana 的儀表板配置，不要刪除 `grafana_data` volume。**
-
-## 📊 指標 (Prometheus)
-
-| 分類         | 指標                                                                                                                                                                 | 說明                 |
-| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- |
-| Runtime      | `python_gc_*`, `python_info`                                                                                                                                         | Python GC 與版本資訊 |
-| 請求         | `llm_requests_total`, `llm_request_latency_seconds`                                                                                                                  | 請求數、延遲統計     |
-| Token/成本   | `llm_tokens_total`, `llm_cost_total_usd_total`                                                                                                                       | Token 使用量與成本   |
-| Cache        | `rag_cache_requests_total`, `rag_cache_results_total`                                                                                                                | Cache 查詢與命中率   |
-| RAG Pipeline | `rag_embedding_latency_seconds`, `rag_retrieval_latency_seconds`, `rag_rerank_latency_seconds`, `rag_llm_latency_seconds`, `rag_errors_total`                        | 各階段延遲與錯誤     |
-| Input Policy | `input_accepted_total`, `input_rejected_total`, `input_rate_limited_total`, `input_chars_histogram`, `input_tokens_histogram`, `input_violation_last_seen_timestamp` | 輸入檢查與限流統計   |