CSP-004　可觀測性與日誌規範（Observability & Logging）

1. 目的

定義統一的結構化日誌、指標、分散式追蹤、健康檢查標準，使 17 個服務具備
一致的可觀測性，滿足 SoW 之效能門檻（授權端到端 P95 ≤ 500ms、核心 P99 ≤ 200ms、路由 ≤ 5ms）。

2. 三支柱

3. 結構化日誌規範

產出方式：一律使用 Spring Boot 4.1 內建之結構化日誌
（logging.structured.format.file=ecs），不自訂 Logback encoder——
官方 Logback→OTel 橋接於 4.1 尚未內建、可用 appender 全為 -alpha
（詳 SCS-020 §9.6）。日誌寫檔後由 Collector 之 filelog receiver 讀取，
零第三方相依。

3.1 欄位對照（實測為準）

ECS 輸出為「巢狀／扁平混用、駝峰與底線並存」，勿依 ECS 慣例猜測：

{"@timestamp":"2026-09-20T10:20:30.123Z","log.level":"INFO",
 "service.name":"authorization-service","traceId":"894ff808…","spanId":"e5f6",
 "message":"AUTH_APPROVED cardRef=****1234 amount=30000 currency=TWD"}

3.2 事件碼（event）本期不實作

原 v1.0 §3 要求之 event 事件碼，本期不實作——專案尚未定義事件碼表，
且事件碼須與 SDD-006 §3.4 之錯誤碼一併規劃（CSP-003 §2：Coder 不得自創碼）。

在事件碼表核定前，以結構化參數記錄事件事實：

log.info("AUTH_APPROVED cardRef={} amount={} currency={}", mask(card), amt, cur);

由 message 與附帶欄位承載語意，不另設 event 欄位——
以免產生恆為空值之欄位（空欄位＝假訊息，與「不可假綠」同旨）。

• 禁止 string concatenation 拼日誌：一律使用結構化參數。
• 日誌層級：ERROR＝需告警、WARN＝需關注、INFO＝關鍵業務事件、DEBUG＝僅開發。

4. 個資遮蔽（對應 SAD-005）

日誌與追蹤中出現之敏感欄位必須經 common-security 遮蔽工具處理：

flowchart LR
    A[業務邏輯] --> B[log.info 結構化]
    B --> C{含敏感欄位?}
    C -- 是 --> D[common-security.mask]
    C -- 否 --> E[輸出 JSON]
    D --> E
    style D fill:#FFF6E0,stroke:#C8A45C

5. 指標規範

每服務必須暴露（Prometheus 格式）：

SLO 範例：授權 http_server_requests_seconds{route=/authorizations} P95 ≤ 0.5s、可用性 ≥ 99.99%。

6. 分散式追蹤

• 所有對外 HTTP／Kafka 呼叫自動注入 traceparent（W3C）。
• 跨系統之唯一識別為 OTel traceId（W3C 標準，32 位十六進位），
  由 OTel 於入口產生並貫穿全鏈（含 Kafka header）。
• ⚠️ 不再另設第二套 correlation ID。原 v1.0 §3／§6 規定之 correlationId
  與 OTel traceId 實為兩套 ID——實測同一請求：
  API 回應 10b8a469…（common-spring correlation ID）
  ≠ 日誌 894ff808…（OTel trace ID），兩者無法相互對照，
  客戶持 API 回應之 ID 查不到對應日誌（SCS-020 §9.5 #3）。
  經裁定（BEAM PMO 2026-09-20）統一以 OTel traceId 為準：
  API 回應之 traceId 與日誌之 traceId 必須為同一值。
• 取樣率預設 1/100；錯誤路徑（4xx/5xx）強制 100% 取樣。
• 禁止在追蹤 span 中記錄敏感 payload；僅記錄長度與欄位名。

6.1 實作點：單一讀取端 TraceContext（2026-09-20 落地）

回應封套之 traceId 一律經 common-spring 之 TraceContext.currentTraceId()
取得，不得另行產生。取值順序：

1. OTel 當前 span 之 traceId（權威）
2. MDC 之 trace_id（OTel 不在場時之降級路徑）
3. 產生 32 碼臨時值（確保永不為空，SAD-001 AP-09）

⚠️ 實測發現之根因（比「有兩套 ID」更嚴重）：CorrelationIdFilter
從未被註冊為 bean——AutoConfiguration.imports 僅登錄 Security×2 ＋ ServiceClient，
該類別亦無 @Component。故 MDC.get("trace_id") 恆為 null，
currentTraceId() 每次呼叫都現產一個新的亂數，回應帶著一個「看似合法」
卻與任何日誌都對不上之追蹤碼——「靜默不做」型缺陷。
改以 OTel 為權威後，只要 OTel 在場即不再受此缺陷影響。

• OTel 缺席時：降級至 MDC／臨時值，並只記一次 WARN
  （使「刻意不接 OTel 之模組」與「忘了接」在日誌上可區分）。
• ⚠️ 待裁定：CorrelationIdFilter 註冊或退役（其職責已被 OTel 取代；
  註冊涉及過濾器順序，順序錯會讓 MDC 與 OTel 出現兩個值，故未擅自註冊）。

7. 健康檢查與告警

• GET /actuator/health/liveness：程式存活（不依賴外部）。
• GET /actuator/health/readiness：依賴（DB、下游、Kafka）就緒。
• 告警分級：P1（可用性跌幅／不變式違反）即時通訊軟體＋電話；P2（延遲超標）工單。

8. 禁止事項

9. 修訂記錄

| O4 | 指標名稱含具體實例 IP／Pod 名 | 聚合失效 |
| O5 | 每秒高頻 log 同一事件無節流 | 磁碟／成本爆量 |