沒有同生命週期管理時，新服務上線後的監控覆蓋率取決於有沒有人記得手動建立 log group 和 alarm，而這個記憶在服務數量增長後會衰退。監控缺口在平時不被注意，在事故排查時才浮現 — 需要回溯「什麼時候開始劣化」時，可能發現劣化期間根本沒有對應的 metric 資料。

同生命週期的落地方式

可觀測性是基礎設施的一部分，它的建立、變更與銷毀要跟被監控的資源綁在同一個 apply 單位裡。一個 RDS 實例被 IaC 建立時，它的 log group、它的關鍵 metric alarm 應該在同一份 terraform plan 裡一起出現；這個資源被 destroy 時，對應的 alarm 也一起收掉。

落地方式是把監控宣告收進服務的 module。模組四（環境分離與模組化）談的模組化在這裡延伸成「每個服務模組自帶它的 observability 宣告」。一個 database module 內部除了 aws_db_instance，還包含它的 log group、CPU alarm、連線數 alarm：

 1# modules/database/monitoring.tf — 跟 database 資源同一個 module
 2resource "aws_cloudwatch_log_group" "db_slow_query" {
 3  name              = "/rds/${var.env}/${var.db_identifier}/slowquery"
 4  retention_in_days = var.log_retention_days
 5  kms_key_id        = var.log_kms_key_arn
 6}
 7
 8resource "aws_cloudwatch_metric_alarm" "db_cpu" {
 9  alarm_name          = "${var.env}-${var.db_identifier}-cpu-high"
10  comparison_operator = "GreaterThanThreshold"
11  evaluation_periods  = 3
12  metric_name         = "CPUUtilization"
13  namespace           = "AWS/RDS"
14  period              = 300
15  statistic           = "Average"
16  threshold           = 80
17  alarm_actions       = [var.oncall_sns_arn]
18
19  dimensions = {
20    DBInstanceIdentifier = aws_db_instance.primary.identifier
21  }
22}

這樣 terraform apply 建資料庫的同一刻，監控就存在；terraform destroy 砍資料庫時，孤兒 alarm 也一起清掉。新環境套用同一個 module 時，監控覆蓋率自動跟著資源走，不需要額外的人工記憶。

監控脫鉤造成的兩類漂移

把監控外掛在資源之外（用另一份 IaC、另一個 repo、或手動在 console 設定）會製造兩種方向相反的漂移，兩者的共同根因都是監控跟資源不在同一個 apply 單位裡。

漂移一：新資源沒有監控

service 透過 PR 加上去了，但 alarm 的建立依賴某人事後手動進 console 設定，或等另一個 repo 的 PR 跟上。於是有些 service 有 alarm、有些沒有，覆蓋率取決於「誰記得」。沒有 alarm 的 service 出事時，事故發現路徑從「告警 → 排查」退化成「客訴 → 排查」，反應時間從分鐘級退化到小時級。

用一條查詢就能看出這個漂移有多嚴重：列出所有 RDS instance，比對各自有沒有對應的 CloudWatch alarm。沒有 alarm 的 instance 就是漂移的活證據。

1# 列出所有 RDS instance，比對有沒有對應的 CloudWatch alarm
2aws rds describe-db-instances \
3  --query 'DBInstances[].DBInstanceIdentifier' --output text | tr '\t' '\n' | while read db; do
4  count=$(aws cloudwatch describe-alarms \
5    --alarm-name-prefix "${db}" --query 'MetricAlarms | length(@)')
6  echo "${db}: ${count} alarms"
7done

漂移二：死資源留下殘響

資源砍了但 alarm 還在，orphan alarm 對不存在的 target 持續報 INSUFFICIENT_DATA，跟有效 alarm 混在同一個通知頻道裡，降低告警的訊噪比。訊噪比低到一定程度後，有效的 INSUFFICIENT_DATA（某個服務停止送 metric）也被一起略過 — 告警疲勞讓 alarm 從保護機制退化成背景噪音。

漂移二的成本不只是注意力。殘留的 alarm 會佔用 CloudWatch alarm 的配額（每個帳號有配額上限），大量孤兒 alarm 累積後，新服務要加 alarm 可能需要先清理舊的 — 這在事故當下是最不該花時間的事。

修法是把 alarm 的生命週期綁進 module：資源 destroy 時 alarm 跟著 destroy，不需要另一個流程去「記得清理」。如果因為歷史原因已經有大量孤兒 alarm，可以用 alarm 的 StateValue 為 INSUFFICIENT_DATA 且持續超過 7 天作為清理候選的篩選條件。

log group 設計

Log group 是日誌的歸屬與保存單位，它要回答兩個治理問題：留多久（retention）、誰能讀（access control）。這兩個問題寫進 IaC 才能稽核，而非依賴 vendor 的隱性預設。

Retention：三方取捨

許多雲端服務在沒有明確宣告 log group 時會自動建一個、套上「永久保留」的預設值。永久保留的問題不是技術性的 — CloudWatch Logs 可以存到無限久 — 而是治理性的：日誌無限堆積、帳單緩慢長大，而沒有人做過「這條 log 該留多久」的顯式決定。

Retention 是成本、合規與除錯需求的三方取捨：

較合理的做法是按日誌類型分層：高頻、除錯用的 application log 設短 retention，稽核相關的 access log 按合規要求設長期保留，必要時再把冷資料用 subscription filter 歸檔到更便宜的物件儲存（S3 + Glacier）。把這些值寫進 IaC，讓「為什麼這條 log 留 90 天」是一個能在 PR 上被討論的決定，而非某人半年前在 console 點的一個數字。成本參考：CloudWatch Logs 的儲存費用約 $0.03/GB/月。一個每天產生 10GB log 的服務，30 天 retention 的月費約 $9，7 天約 $2。retention 天數的選擇是合規需求（留多久才合規）與儲存成本的直接取捨，可以按 log 類型分層設定。

觀測平台的帳單在規模化後容易超線性成長，而缺乏 per-team cost attribution 的環境只能靠全域砍 retention 或降 sampling 來控制成本，兩者都會傷害觀測品質。把 log retention 跟 cardinality budget 的決定從全域級拆到團隊級（用 tag 歸因），才能做到「該省的省、該留的留」。這個取捨在 4.C14 觀測平台成本治理 有多家企業的具體經驗。

 1resource "aws_cloudwatch_log_group" "api" {
 2  name              = "/app/${var.env}/api"
 3  retention_in_days = var.env == "prod" ? 30 : 7
 4  kms_key_id        = aws_kms_key.logs.arn
 5}
 6
 7resource "aws_cloudwatch_log_group" "audit" {
 8  name              = "/app/${var.env}/audit"
 9  retention_in_days = 365
10  kms_key_id        = aws_kms_key.logs.arn
11}

Dev 環境的 retention 可以大幅縮短（7 天甚至 3 天），因為它不承擔合規責任，存取量也低，帳單節省直接對應這個差值。

存取控制與加密

「誰能讀」是 retention 之外的另一半。Log 經常夾帶 PII（使用者信箱、IP）、token 或內部結構，讀取權限要跟模組二（身分與憑證地基）建立的 IAM 角色一起管。

常見陷阱是 log 在傳輸與儲存都加密了（kms_key_id 有設），卻對整個團隊開放讀取。加密保護的是靜態資料不被未授權存取，但如果整個開發團隊都有 logs:GetLogEvents 權限，加密形同虛設 — read 權限應該縮到值班與稽核需要的最小集合。

 1# 只允許 oncall role 讀取 prod log
 2data "aws_iam_policy_document" "log_read" {
 3  statement {
 4    actions   = ["logs:GetLogEvents", "logs:FilterLogEvents"]
 5    resources = [aws_cloudwatch_log_group.api.arn]
 6  }
 7}
 8
 9resource "aws_iam_role_policy" "oncall_log_read" {
10  role   = var.oncall_role_name
11  policy = data.aws_iam_policy_document.log_read.json
12}

應用層該怎麼決定哪些欄位根本不該進 log（例如在 logger 層做 PII masking），屬於資料保護的範圍，見 backend 模組七：資安與資料保護。

metric 與 alarm 設計

Metric 與 alarm 寫進 IaC，目的是讓「資源被建立的同時就帶著它的健康判準」。Alarm 是一份成文約定：哪條 metric、跨多長的評估窗口、超過什麼值要通知誰。把這份約定寫進 code，它就能被 review、被版本控制、被跨環境複用。

症狀型 vs 成因型告警

閾值設計是訊號與雜訊的取捨。告警可以分成兩類：症狀型（symptom-based）對應的是「使用者已經受影響」的指標 — 5xx 錯誤率、p99 延遲、佇列積壓。成因型（cause-based）對應的是「某個元件在劣化但使用者可能還沒感知」的指標 — CPU 使用率、記憶體使用率、磁碟 IOPS。

收益最高的起點是：症狀型設 alarm 並綁通知，成因型留在 dashboard 上作為診斷線索。理由是成因和症狀之間不一定有直接關係 — CPU 在 80% 不代表使用者受影響（可能 auto-scaling 正在長新節點），而 CPU 在 30% 也不代表安全（可能是某個 goroutine 卡住了，CPU 反而閒下來）。如果每個成因指標都獨立設 alarm，告警數量會與資源數量等比增長，訊噪比下降後症狀型告警容易被成因型告警淹沒。

 1# 症狀型 alarm：5xx 超過閾值代表使用者已受影響
 2resource "aws_cloudwatch_metric_alarm" "api_5xx" {
 3  alarm_name          = "${var.env}-api-5xx-rate"
 4  comparison_operator = "GreaterThanThreshold"
 5  evaluation_periods  = 3
 6  metric_name         = "5XXError"
 7  namespace           = "AWS/ApiGateway"
 8  period              = 60
 9  statistic           = "Sum"
10  threshold           = 10
11  treat_missing_data  = "notBreaching"
12  alarm_actions       = [var.oncall_sns_arn]
13}
14
15# 成因型指標：CPU 放 dashboard、不設 alarm
16# 除非確認「CPU 到 X% 一定代表服務即將不可用」這個因果關係

當成因和症狀之間有明確的因果閾值（例如 RDS 磁碟用量到 90% 就會開始拒絕寫入），那條成因也值得設 alarm — 關鍵是因果關係要確認過、而非假設。

INSUFFICIENT_DATA 的處理

treat_missing_data 決定了「沒收到 metric 資料點」時 alarm 怎麼判定。這個設定常被忽略，但它在兩個情境下會造成顯著差異：

持續有資料的 metric（如 API request count）：資料突然消失通常代表服務掛了或 metric 管線斷了，應該設 treat_missing_data = "breaching" — 沒資料本身就是異常訊號。

間歇性的 metric（如錯誤 count、某個低頻 Lambda 的 invocation）：平常就沒有資料點，沒資料代表正常運作，應該設 treat_missing_data = "notBreaching" — 避免每次低谷時段都觸發假告警。

判讀方式是問自己：「這條 metric 如果 10 分鐘沒有任何資料，代表好事還是壞事？」好事用 notBreaching，壞事用 breaching，不確定用 ignore（不改變 alarm 狀態，等下一個有資料的評估週期再判定）。

告警必須連到動作

一條有用的 alarm 至少要綁定通知去向。alarm_actions 為空的 alarm 只會在 CloudWatch console 裡變色，而事故發生時沒有人會盯著 console 看 — alarm 的價值在於它主動推送到值班的人手上。

1resource "aws_sns_topic" "oncall" {
2  name = "${var.env}-oncall-alerts"
3}
4
5resource "aws_sns_topic_subscription" "pagerduty" {
6  topic_arn = aws_sns_topic.oncall.arn
7  protocol  = "https"
8  endpoint  = var.pagerduty_integration_url
9}

通知去向也該寫進 IaC — SNS topic、subscription、整合端點都是基礎設施的一部分。手動建的 SNS subscription 跟手動建的 alarm 有同樣的問題：沒人記得、沒人維護、出事才發現斷了。

把基礎告警做成 module 預設

如果每次新服務上線都要有人「記得」去加 alarm，代表 alarm 還沒進 module 模板。把基礎告警（錯誤率、延遲、健康檢查失敗）做成服務模組的預設輸出，新服務 apply 時 alarm 跟著一起生出來：

 1# modules/service/variables.tf
 2variable "alarm_5xx_threshold" {
 3  type    = number
 4  default = 10
 5}
 6
 7variable "alarm_latency_p99_ms" {
 8  type    = number
 9  default = 3000
10}

開新服務時 alarm 跟著資源一起生出來，調整閾值才是該服務 owner 的選配。預設值的選擇依據是「保守但不擾民」— 初始閾值設寬一點，上線穩定後再根據實際基線收斂。

觀測訊號的設計有一個容易忽略的盲區：aggregated metric 會遮蔽局部惡化。Discord 在三代儲存架構的遷移過程中反覆遇到同一個問題——整體 p95 延遲正常，但少數 hot partition 或大型群組的延遲已經飆升，直到使用者回報才發現。教訓是 alarm 的維度要跟業務的 fan-out 結構對齊，而非只看全域聚合。詳見 4.C13 Discord：從儲存問題回推觀測缺口。規模化後叢集的動態擴縮也會改變觀測模型——擴縮事件本身要成為觀測對象，見 4.C8 Airbnb：K8s 規模化觀測訊號治理。

基礎設施訊號 vs 客戶端行為訊號

本模組的可觀測性處理基礎設施訊號，Monitoring 監控體系處理客戶端與業務行為訊號。兩者觀測的對象不同、生命週期也不同，因此分屬不同的 code 與不同的部署管道。

基礎設施訊號是資源層的健康狀態：log group retention、CPU、佇列深度、5xx 比例、實例存活。它們跟著資源被 IaC 建立與銷毀，回答的問題是「這個系統還活著嗎、哪裡壞了」。

客戶端行為訊號則是 SDK、Collector、業務埋點那一層：使用者點了什麼、轉換漏斗在哪裡流失、前端 JS 錯誤率、自訂業務事件。它們跟著產品功能演進、不跟著基礎設施資源同生共滅。

判讀分界的問法是：這個訊號是「資源建立時就該存在」還是「功能開發時才埋」。前者進本模組的 IaC，後者進 monitoring 那層的應用程式碼。

兩者在事故排查時會合流 — 基礎設施 alarm 告訴值班「RDS CPU 飆到 95%」，客戶端訊號告訴產品團隊「結帳頁面的失敗率從 0.1% 跳到 12%」。把兩條訊號交叉比對才能判斷影響範圍。但它們的擁有者、變更節奏與部署管道不同 — 基礎設施 alarm 跟著 infra PR 走，前端埋點跟著產品 sprint 走。混在同一份 code 裡會讓「誰負責這條訊號的閾值」變模糊，也讓 infra PR 的 review 範圍擴大到不相干的業務邏輯。

跨分類引用

• → monitoring 監控體系：客戶端 SDK / Collector 那層的監控
• → 模組四：環境分離與模組化：module 化在這裡延伸成「每個模組自帶 observability 宣告」
• → 模組五：核心服務上 IaC：每個核心服務帶自己的 log 與 alarm
• → 模組七：infra 走 PR 流程：observability 變更也走 PR 與自動化護欄
• → backend 模組七：資安與資料保護：哪些欄位不該進 log、PII 處理

連線生命週期 log

連線生命週期 log 記錄的是「流程走到第幾步、每步成功或失敗」。這一層的 log 粒度是步驟級 — 不記錄每一個封包或每一次函式呼叫，只記錄流程中的關鍵節點。

以 app_tunnel 的連線流程為例，連線生命週期包含五步：biometric 認證 → credential 讀取 → WebSocket 連線 → auth token 發送 → stream 訂閱。每步完成時記一條 log，失敗時記一條包含原因的 log。

1[conn] Step 1/5: biometric auth completed (duration: 320ms)
2[conn] Step 2/5: credential loaded (user: admin)
3[conn] Step 3/5: WebSocket connected (url: wss://...)
4[conn] Step 4/5: auth token sent
5[conn] Step 5/5: stream subscribed, ready

app_tunnel 在實機測試前六個核心元件中只有兩個有 log，且全是 W2 修復時事後補上的（T.C4）。W2-002 auth token 問題的 debug 過程中，開發者無法從任何 log 判斷失敗發生在五步中的哪一步。如果有連線生命週期 log，第一次連線就能看到「Step 3 完成，Step 4 未執行」— 直接定位到 auth token 缺失。

連線生命週期 log 在所有模式（debug 和 release）都應該啟用。這層 log 量小（每次連線 5-10 條），不影響效能，但在 production 問題回報時是第一手資訊來源。

Protocol 訊息 log

Protocol 訊息 log 記錄的是通訊協議層面的細節：發送和接收的 frame type、payload 前綴、handshake 參數、逾時值。這一層的粒度比連線生命週期更細 — 每一次 send/receive 都記錄。

1[proto] TX: text frame, payload: {"AuthToken":"base64..."} (42 bytes)
2[proto] RX: text frame, payload prefix: "0" (output data, 128 bytes)
3[proto] TX: binary frame, payload: [72, 101, 108, 108, 111] (5 bytes)

Protocol log 在 debug 時幫助確認「程式碼發送了什麼、收到了什麼」。app_tunnel 的 text/binary frame 問題（T.C1）如果有 protocol log，開發者會在 log 中看到 TX: binary frame 而非預期的 TX: text frame — 直接指向 frame type 問題。

Protocol log 在 release mode 應該能關閉。這層 log 量大（每次鍵盤輸入一條），且 payload 可能包含敏感資訊。Debug mode 預設啟用，release mode 提供開關（例如隱藏設定頁的 toggle）讓進階使用者在回報問題時開啟。

使用者行為 log

使用者行為 log 記錄的是使用者在 UI 上的操作：按鈕點擊、畫面切換、設定變更。這層 log 的粒度是操作級 — 使用者做了一個有意義的動作記一條。

1[ui] screen: HomeScreen, action: tap Connect Terminal
2[ui] screen: TerminalScreen, state: connecting → connected
3[ui] screen: TerminalScreen, action: tap back button
4[ui] screen: HomeScreen, state: returned from terminal

使用者行為 log 在兩個場景有價值：第一，debug 時還原使用者操作路徑 — 「使用者做了什麼導致問題出現」；第二，結合狀態矩陣（ux-design 模組一）做狀態轉換的實際覆蓋率分析 — 哪些狀態轉換在真實使用中經常發生，哪些從未發生。

使用者行為 log 在 release mode 啟用時需要注意隱私。記錄「使用者切換了畫面」是合理的；記錄「使用者輸入了密碼 abc123」需要 redaction 機制（monitoring 模組七 資安）。

三層的關係

三層 log 各自獨立運作，debug 時通常按照從粗到細的順序使用。

粗篩：先看連線生命週期 log，確認流程走到哪一步。如果 Step 3 失敗，問題在 WebSocket 連線層。

細查：切到 protocol 訊息 log，看 Step 3 的連線嘗試中發送和接收了什麼。如果看到 binary frame 發送但沒有回應，問題可能在 frame type。

還原：如果問題和使用者操作有關（例如只在特定操作順序下觸發），看使用者行為 log，還原操作路徑。

三層 log 用同一個時間戳和 correlation ID（例如連線 session ID），讓跨層比對可行。

下一步路由

• 在功能規格中定義 log 點 → 功能規格中的 log 點定義方法
• 事後補 log 和設計產物 log 的品質差異 → 「事後補 log」vs「設計產物 log」的品質差異
• Log 收集方案選擇 → 自架 log endpoint vs 商業方案
• 事件分類與收集策略 → monitoring 模組一 監控心智模型

概念位置

跟 traditional logging 的對比：

主流 OTel GenAI span 類型：

每個 span 標準屬性：gen_ai.system（vendor）、gen_ai.request.model、gen_ai.usage.input_tokens / output_tokens、gen_ai.request.temperature 等。

設計責任

讀 LLM observability docs / OTel spec 看到「span」「trace」「OTel GenAI semconv」就是這 framing。寫 code 場景的判讀：

1. 何時值得加 tracing：超過個人 demo、有實際使用者 / production 流量、開始遇到「為什麼 agent 跑這條路」debug 問題
2. 不該自己寫 logging：用 OTel GenAI semconv 標準化、未來可換 backend（LangSmith → Phoenix → 自架）
3. Trace 不只 debug、也是 eval 來源：production trace 餵回 LLM-as-judge 做品質評估
4. 跟 4.20 LLM tracing 章節 的關係：本卡是定義、章節是工程實務（attribute 設計、cost monitoring、failure debug 流程）

業務背景

一家處理線上支付的金融科技公司，每日交易量約 200 萬筆，涵蓋信用卡收單、轉帳與退款。每季有外部稽核查核交易處理的完整性與存取控制，事故發生時法務需要在 48 小時內提供特定交易的完整處理鏈證據。

初期系統把所有 log 寫到同一個 log group — application debug、request trace、交易狀態變更與使用者存取紀錄全混在一起。稽核人員要從數 TB 的 log 中撈出特定交易的完整軌跡，每次查詢耗時數小時。

技術挑戰

Operational log 與 audit log 混合

Application log 記錄 debug 資訊（SQL timing、cache hit/miss、retry），audit log 記錄業務事件（交易建立、狀態變更、存取紀錄）。兩者混在同一個 pipeline 時，retention 策略互相衝突 — debug log 留 14 天夠用，但 audit log 法規要求保留 5 年。統一設成 5 年讓儲存成本暴增，統一設成 14 天則遺失合規證據。

PII 暴露在 log 中

早期 log 直接印出 request body，信用卡號跟身分證字號散落在各種 log entry。稽核指出 PII 在 log 系統中的暴露面超過業務需要，但 log 已經寫入後無法回溯修改。

Event correlation 斷裂

交易從建立到完成經過多個服務（checkout-api → payment-gateway → settlement → notification），但各服務的 log 使用不同的 correlation key。Checkout 用 order_id，payment-gateway 用 payment_ref，settlement 用自己的 batch_id。稽核要求「給我交易 X 的完整處理鏈」時，工程師需要手動在三個系統各自查詢再人工拼接。

解法

Audit log 分離

把 audit event 獨立到專屬 pipeline：交易狀態變更、使用者存取、權限變動、退款操作各自產生結構化 audit event，寫入 immutable storage（append-only、禁止刪除與修改）。Operational log 維持 14 天 retention，audit log 走 5 年 retention + cold archive。

分離的判準是「這筆紀錄是否可能被稽核或法務要求提供」。是 → audit pipeline；否 → operational pipeline。灰色地帶（例如認證失敗 log）歸入 audit pipeline — 寧可多留不可少留。

PII redaction pipeline

在 log ingestion 階段加入 redaction processor：信用卡號遮罩為末四碼、身分證字號完全移除、email 保留 domain 遮罩使用者名稱。Redaction 發生在寫入儲存之前，原始資料不落地。

需要完整 PII 的場景（如詐欺調查）走另一條授權存取管道，跟觀測 pipeline 分離。

統一 correlation key

所有服務在交易入口處產生 trace_id 和 transaction_id，兩個 key 同時寫入每一筆 audit event 和 operational log。稽核查詢用 transaction_id 就能撈出跨服務的完整處理鏈，不需要手動拼接。

取捨

分離 pipeline 的最大成本在 routing 規則的維護 — 新服務上線時要確認 audit event 走對 pipeline。解法是在 SDK 層提供 emit_audit_event() 函式，讓 routing 在 producer 端決定，不依賴下游 pipeline 的內容判斷。

回寫教材的連結

• 4.12 Audit Log Governance：audit log 分離的設計原則與 PII 治理。
• 4.20 Observability Evidence Package：把 audit trail 包成可交接的 evidence package。
• 4.18 Observability Operating Model：audit pipeline 的 ownership 歸 platform team 還是 compliance team。
• 4.3 Tracing Context：跨服務 correlation key 的 propagation 設計。

判讀徵兆

讀者在自己的系統看到以下訊號時，應該回讀本案例：

• 稽核或法務要求提供某筆交易的完整處理鏈，工程師需要超過 1 小時才能拼出來
• Log retention 設定跟法規要求不一致，但沒人確切知道差多少
• PII 出現在 log search 結果中，但沒有系統性的遮罩機制
• Application log 跟 audit log 用同一套 retention policy，儲存成本持續上升但沒人敢縮短
• 事故後法務要證據，發現關鍵時段的 log 已經因為 retention 過期而被刪除

本頁先給最短路徑、再展開日常 instrumentation 跟 Collector 部署、最後進階治理（sampling / semantic conventions / logs 成熟度）跟排錯。

本章目標

讀完本章後、你應該能：

1. 用 OTel SDK 或 auto-instrumentation 對應用程式做 instrumentation
2. 配置 OTLP exporter 把 telemetry 送到任一 backend
3. 部署 OTel Collector（agent / gateway 模式）作為 backend 切換抽象層
4. 區分 head-based vs tail-based sampling、選擇對應策略
5. 評估從 vendor SDK 遷移到 OTel SDK 的相容性風險

最短路徑：5 分鐘把 OTel 跑起來

1# 1. 應用程式加 auto-instrumentation（範例：Python）
2# TODO: opentelemetry-bootstrap -a install
3# TODO: opentelemetry-instrument --traces_exporter otlp --metrics_exporter otlp python app.py
4
5# 2. 啟動 OTel Collector
6# TODO: docker run -p 4317:4317 -p 4318:4318 otel/opentelemetry-collector-contrib
7
8# 3. Collector 配置範例
9# TODO: otel-collector-config.yaml with otlp receiver + exporter to backend

最短路徑驗證 telemetry 從 app → Collector → backend 串通。實際 production 要評估 sampling、retention、cardinality。

日常操作與決策形狀

Instrumentation 模式

子議題：

• Auto-instrumentation：Java / Python / Node / .NET / Ruby / Go 各語言成熟度不同
• Manual instrumentation：開發者寫 trace span / metric instrument
• Library instrumentation：opentelemetry-instrumentation-（HTTP client / DB / framework）

OTLP exporter 配置

子議題：

• OTLP gRPC（4317）vs HTTP（4318）
• Endpoint / headers / authentication 配置
• 對應指令範例：環境變數 OTEL_EXPORTER_OTLP_ENDPOINT、OTEL_EXPORTER_OTLP_HEADERS

Collector 部署模式

子議題：

• Agent：跟應用程式同 host / pod、做 local buffer + enrichment
• Gateway：集中部署、跨多 agent 接收、做 sampling / routing
• Sidecar：K8s sidecar pattern、跟 pod 同生命週期
• 對應配置：receivers / processors / exporters pipeline

深入：OTel Collector 部署模式：agent / gateway / sidecar 與 pipeline 設計（三種位置責任分工、pipeline 設計、collector 失效 / 記憶體壓力 / backpressure 故障演練、容量成本邊界）。

進階主題（按需閱讀）

Auto-instrumentation 跨語言成熟度

子議題：

• Java：最成熟、auto-instrumentation 廣度最大
• Python：成熟、覆蓋主流 framework
• Node：成熟、async context propagation 較複雜
• Go：較弱（runtime 不支援 monkey patching）、多用 manual
• .NET：成熟、跟 Application Insights 對齊
• Ruby / PHP：相對較弱、覆蓋主流 framework

Sampling 策略

對應案例 4.C7 Datadog OTel migration。子議題：

• Head-based sampling：trace 開始時決定保留與否、低成本但 lose context
• Tail-based sampling：trace 完成後決定（依錯誤 / 延遲）、Collector 要 buffer 整個 trace
• Sampling rate 配置（global / per-service / probabilistic）
• 對應工具：OTel Collector 的 tail_sampling processor、Refinery（Honeycomb）

Semantic conventions

子議題：

• HTTP / DB / messaging / RPC 等的 attribute 命名規範
• Resource attributes（service.name / service.version / deployment.environment）
• Span name / status code convention
• Migration：應用層用 OTel semantic conventions、避免 vendor-specific naming

Logs in OTel

子議題：

• Logs 比 metrics / traces 較晚進 OTel spec（v1.0 較新）
• Log signal 設計：log record 跟 span 關聯（trace_id / span_id）
• 跟 Loki / Elastic / CloudWatch 的整合
• 從現有 logging library 移轉的路徑（log-forwarding vs SDK）

Vendor SDK vs OTel SDK 遷移

對應案例 4.C4 X-Ray to OpenTelemetry 與 4.C7 Datadog OTel。子議題：

• 動機：避免 vendor lock-in、多 backend 並存、開源治理
• 風險：vendor-specific feature 損失（profiling / RUM 整合）
• 遷移路徑：dual ship → cutover → cleanup
• 對應 4.C9 反例：OTel migration signal drift

Resource detection

子議題：

• 自動偵測 cloud provider（AWS / GCP / Azure）resource attributes
• K8s resource detector（pod / namespace / cluster）
• Container resource detector
• 對應配置：OTEL_RESOURCE_ATTRIBUTES

排錯快速判讀

Telemetry 沒到 backend

操作原則：先確認 SDK 配置正確、再看 Collector 是否收到、最後看 exporter 是否成功。

1# TODO: 設 OTEL_LOG_LEVEL=debug 看 SDK 內部 log
2# TODO: 看 Collector internal metrics（zPages / Prometheus exporter）

判讀路徑：SDK → Collector → backend、三段各自獨立、要逐層 isolate。

Cardinality explosion

操作原則：metric attribute 含 high-cardinality 值（user_id / session_id）會爆 backend 成本。判讀：看 backend 的 series 數量、找 attribute 來源。

Trace span gap

操作原則：trace 不完整、看 context propagation 是否在跨 service / 跨 thread 邊界丟失。

Auto-instrumentation 不生效

操作原則：確認 SDK 版本跟 library version 對應、agent 啟動方式正確。對應 4.C7 Datadog OTel migration 的踩坑經驗。

Sampling 過頭 / 不足

操作原則：sampling rate 跟 backend 預算 + debug 需求對齊。判讀：debug 時找不到 trace（sampling 過頭）vs backend 成本爆（sampling 不足）。

何時改走其他服務

不在本頁內的主題

• 各語言 SDK 完整 API
• OTLP protocol binary format
• 各 backend 的 OTel 整合細節（見各 backend vendor 頁）
• OTel project governance / sig 細節

案例回寫

直接相關案例

跨 vendor 對照

下一步路由

• 上游概念：4.17 Telemetry Data Quality
• 平行 vendor：所有 04 vendor 都可作 OTel backend
• 下游能力：4.20 Observability Evidence Package

• structured log schema
• correlation id / request id fields
• index 與 retention
• query pattern

概念定位

log schema 是把事件紀錄從文字輸出變成可查詢資料的契約，責任是讓不同服務在事故時能用同一組欄位還原脈絡。

這一頁處理的是欄位與搜尋路徑。log 的價值在於事故時能用穩定欄位找到同一個 request、同一個 tenant、同一個 dependency call 與同一段錯誤鏈，寫得多本身沒有幫助。

核心判讀

判讀 log schema 時，先看 correlation fields 是否穩定，再看 search index 與 retention 是否對齊查詢需求。

重點訊號包括：

• request id、trace id、tenant boundary 與 service name 是否跨服務一致
• high-cardinality 欄位是否被放進可控索引，並受查詢價值與成本預算約束
• retention 是否依 operational debug、audit、compliance 分層
• query pattern 是否能支援 incident timeline 還原

判讀訊號

• log 欄位 schema 漂移、跨服務 correlation id 對不上
• 事故時靠 grep 拼湊事件、無結構化查詢入口
• log 索引爆量、查詢退化但無清理流程
• log 含大量 free-form text、無一致關鍵欄位
• retention 策略全平、舊事件查不到 / 不該留的還在留

查詢模式設計

Log 的寫入格式跟讀取需求是兩個不同的設計問題。寫入追求 schema 穩定與吞吐效率；讀取要在不同時間壓力下，用不同的查詢形狀取回不同精度的資料。同一份 structured log 至少被三種查詢模式讀取，每種模式對索引、延遲與結果形狀的要求不同。

即席診斷查詢

事故中的查詢要在秒級內定位問題。典型操作是拿到一個 request id 或 error code，加上 time window，撈出相關事件鏈。

即席查詢的索引策略是把高頻過濾欄位放進結構化索引：service name、log level、error code、request id、trace id、tenant boundary。這些欄位的共同特徵是有界或半有界（error code 有限、request id 雖然無界但查詢時一定帶精確值），查詢時用等值匹配或短範圍掃描。

即席查詢的反模式是對 free-text 欄位做全文搜尋當作主要診斷入口。全文搜尋適合探索性調查（「最近有沒有出現某個未預期的 exception message」），但事故中的時間壓力下，結構化欄位的精確查詢比全文搜尋快一到兩個數量級。

聚合趨勢查詢

Dashboard 跟告警的查詢是定期的聚合計算：過去 5 分鐘的 error count by service、過去 1 小時的 log volume by level、某個 tenant 的 warning 趨勢。這類查詢不需要看單筆 log 的內容，而是需要 count / rate / group by 的聚合結果。

聚合查詢的負載特性跟即席查詢不同。即席查詢讀少量資料、要求低延遲；聚合查詢掃大量資料、容忍較高延遲但執行頻率高（dashboard 每 30 秒刷新一次 = 每分鐘 2 次相同的重聚合）。當 log volume 成長，重複計算聚合的成本會推高 query engine 負擔。

應對策略有兩種。一是在 log pipeline 把常用聚合轉成 metrics — collector 端做 log-to-metric 轉換（例：把 level=error 的 log 計數轉成 error_log_total counter），dashboard 讀 metric 而非重掃 log。二是在查詢層設定 materialized view 或快取，讓重複查詢直接取用預計算結果。

鑑識回溯查詢

事後分析與合規稽核的查詢範圍大（跨天、跨週甚至跨月）、對完整性要求高、但延遲容忍也高（分鐘級回應可接受）。鑑識查詢常見的形狀是「某個 tenant 在過去 30 天內所有 authentication failure」或「某個 API 的 error 分布演變」。

鑑識查詢的儲存設計跟 storage tiering 直接相關。Hot tier 保留最近數天的 full-index log，warm tier 保留數週的部分索引或壓縮 log，cold tier 保留數月到數年的歸檔 log。鑑識查詢命中 cold tier 時，系統可能需要 rehydrate（把歸檔資料暫時載回可查詢狀態），這個操作本身需要時間和臨時儲存空間。

鑑識場景的關鍵設計決策是「哪些欄位在 cold tier 仍可查詢」。全部欄位都保留索引成本太高；只保留 timestamp + service name + tenant 的最小索引，能支援基本的範圍掃描，細節再用 rehydrate 後的全文搜尋補。

三種模式的資源隔離

三種查詢模式搶同一個 query engine 時，聚合查詢的持續負載會擠壓即席查詢的回應速度。事故中團隊最需要即席查詢的低延遲，但此時 dashboard 也在高頻刷新聚合查詢，兩者競爭 query 資源。

可操作的隔離方式是讓即席查詢跟聚合查詢走不同的 query priority 或 query queue。Elasticsearch 的 search thread pool、Loki 的 query-frontend queue、Datadog 的 query quota 都提供某種程度的查詢隔離。設計時要把即席查詢的延遲 SLA 當作硬性約束，聚合查詢的延遲可以被彈性排程。

交接路由

• 04.7 metric cardinality / cost：label 預算與保留階梯
• 04.8 訊號治理閉環：log-based alert 的生命週期
• 04.12 audit log：稽核訊號跟 operational log 的邊界
• 04.23 觀測查詢設計：跨訊號類型的讀取路徑系統設計

四類 log 點

每個功能的 log 點按執行時機分成四類。

啟動 log

功能開始執行時記錄。回答「這個功能是否被觸發了」。

啟動 log 包含觸發來源（使用者操作、系統排程、外部事件）和初始參數（連線目標、操作類型）。如果一個功能從未被觸發，啟動 log 的缺席就是線索。

步驟 log

功能執行過程中的每個關鍵步驟完成時記錄。回答「流程走到哪裡了」。

步驟 log 的粒度依功能複雜度而定。三步驟的功能每步記一條；十步驟的功能可以只記關鍵的三到五步。判斷標準是：如果這一步失敗，開發者是否需要知道失敗點在哪。

錯誤 log

步驟失敗、例外捕獲、非預期狀態出現時記錄。回答「出了什麼問題」。

錯誤 log 必須包含足夠的 context 讓開發者不需要重現問題就能判斷原因。至少包含：哪一步失敗、失敗原因（error message）、當時的關鍵狀態值。

完成 log

功能正常結束時記錄。回答「功能是否成功完成、花了多久」。

完成 log 包含執行結果和耗時。和啟動 log 配對使用 — 有啟動但沒有完成代表功能中途異常退出。

在功能規格中加可觀測性欄位

以 app_tunnel 的「連線到 ttyd 終端機」功能為例，傳統規格只寫：

• 輸入：使用者選擇的伺服器
• 處理：建立 WebSocket 連線、發送 auth token、開始接收 terminal output
• 輸出：終端機畫面顯示 terminal output

加上可觀測性欄位後：

這張表在功能規格階段就能寫出來，因為它只依賴功能的流程設計，不依賴實作細節。功能流程確定後，每一步在哪裡需要 log 點就確定了。

log 點命名規則

統一的命名規則讓 log 可以被 grep、過濾和統計。

階層式命名：{功能}.{步驟}.{事件}。例如 connect.ws.connected、connect.auth.failed。

事件後綴統一：start（啟動）、done（步驟完成）、failed（失敗）、complete（功能完成）。

和程式碼結構對應：log 點名稱對應到程式碼中的函式或模組。connect.biometric.done 對應 BiometricService.authenticate() 的成功路徑。這讓開發者看到 log 名稱就知道去哪裡找程式碼。

log 點規格的 review 檢查

功能規格 review 時，可觀測性欄位的檢查要點：

每步都有 log：流程中的每個步驟在成功和失敗時都有對應的 log 點。遺漏的步驟意味著該步驟出問題時無法從 log 判斷。

錯誤 log 有足夠 context：error log 只寫「連線失敗」不夠；需要寫「連線失敗」加上 error code、目標 URL、已完成的步驟。

敏感欄位有 redaction 標記：密碼、token、個人資料在 log 規格中標記為 redact，實作時用 redaction 機制處理。

啟動和完成配對：每個功能有啟動 log 就應該有完成 log，形成完整的生命週期。

下一步路由

• 三層 log 的詳細設計 → 三層 log 設計
• 事後補 log 和設計產物 log 的差異 → 「事後補 log」vs「設計產物 log」的品質差異
• Log 中的敏感資訊處理 → monitoring 模組七 資安

對應 findings

待寫章節

• 三層 log 設計（連線生命週期 / protocol 訊息 / 使用者行為）
• 功能規格中的 log 點定義方法
• 自架 log endpoint vs 商業方案的取捨判斷
• 「事後補 log」vs「設計產物 log」的品質差異

跨分類引用

• → monitoring 模組二 Log Schema：本模組教「設計 log 點」，monitoring 教「log 收集到之後怎麼處理」
• → monitoring 模組七 資安：log 內容可能含 secret，SDK redaction 在這裡介入
• ← ux-design 模組一：狀態矩陣可加「可觀測性」欄位

業務背景

一個線上多人遊戲平台，日活躍使用者約 50 萬人。每逢賽季開跑或限時活動，同時在線人數在 30 分鐘內從平日基線暴增 8-10 倍，matchmaking 服務的 request rate 從 5k/s 衝到 50k/s，遊戲伺服器同時運行的 match instance 從數千增到數萬。

觀測系統在平日運作良好 — Prometheus 單機 scrape 500 萬 active series、Grafana dashboard 查詢秒級回應、告警在 1 分鐘內觸發。但每次活動開跑時，觀測系統本身開始劣化：dashboard 查詢從秒級變成分鐘級、告警延遲 5 分鐘以上才送到、部分 metric 直接消失。值班工程師在最需要觀測的時刻失去了可信訊號。

技術挑戰

Cardinality 爆炸

平日的 metric label 設計包含 match_id、player_id 跟 server_instance。平日 active series 約 500 萬，活動開跑後 match 跟 player 數量暴增，active series 在 30 分鐘內衝到 2000 萬。Prometheus 的 head block 記憶體從 20 GB 暴增到 80 GB，超過機器 64 GB 上限，觸發 OOM kill。

OOM 後 Prometheus 重啟需要 replay WAL，這段時間（5-15 分鐘）完全沒有 metric。活動最需要觀測的前 30 分鐘，觀測系統反而停擺。

Scrape freshness 延遲

即使 Prometheus 沒 OOM，大量 target 的 scrape 時間也會拉長。平日每輪 scrape 15 秒完成，活動期間拉長到 60-90 秒。Scrape interval 設定 30 秒時，下一輪 scrape 在上一輪還沒結束時就啟動，造成 sample 丟失跟時間錯位。Dashboard 上看到的數字可能延遲 2-3 分鐘，值班人員基於過期數據做判斷。

Alert 閾值失真

告警規則基於平日 baseline 設定 — 例如 error_rate > 1% 觸發。活動期間的 error rate 波動更大（matchmaking 短暫排隊造成的 timeout 增加是預期行為），平日閾值在活動期間持續觸發 false positive。值班人員開始 ignore alert，真正的問題（伺服器記憶體洩漏）被淹沒在噪音中。

解法

Cardinality guardrail

把高 cardinality label 從 real-time metric 移除。match_id 和 player_id 不再作為 Prometheus label，改為 log 和 trace 的欄位。Real-time metric 只保留 region、server_pool、game_mode 等低 cardinality 維度。

需要 per-match 或 per-player 分析時，走 log analytics pipeline（非 real-time，延遲 5-10 分鐘可接受）。這讓 Prometheus 的 active series 在活動期間從 2000 萬降到 800 萬，留在單機可承受範圍。

Pre-aggregation recording rules

為活動期間最常查的 pattern（per-region error rate、matchmaking queue depth、server utilization）建立 recording rules。Recording rules 在 Prometheus server 端預先計算，dashboard 查詢直接讀預計算結果，避免 heavy aggregation query 在活動期間拖慢 Prometheus。

1# recording rule 示例
2groups:
3  - name: peak_precompute
4    interval: 15s
5    rules:
6      - record: region:matchmaking_errors:rate5m
7        expr: sum(rate(matchmaking_errors_total[5m])) by (region)

Signal tiering

把觀測訊號分成兩層：

Tier 1 支撐告警跟即時 dashboard，保證活動期間不劣化。Tier 2 支撐事後分析跟 root cause investigation，接受延遲。

Dynamic alert threshold

活動期間啟用「高峰模式」alert profile — 調高 error rate 閾值（1% → 5%）、加長 for: duration（1m → 5m）、停用已知在活動期間會 false positive 的告警。高峰模式由活動排程系統自動觸發，活動結束後自動切回平日 profile。

取捨

分層治理的核心取捨是犧牲 per-match real-time debug 能力，換取觀測系統在高峰期間的穩定。這個取捨在活動場景成立 — 活動期間最需要的是「整體是否健康」的判斷，per-match debug 在事後分析夠用。

回寫教材的連結

• 4.7 Cardinality Cost Governance：cardinality guardrail 的設計原則與偵測機制。
• 4.17 Telemetry Data Quality：scrape freshness、sampling bias 與 signal tiering。
• 4.11 Telemetry Pipeline：real-time vs batch analytics pipeline 的分層設計。
• 4.4 Dashboard Alert：dynamic alert threshold 與高峰模式切換。

判讀徵兆

讀者在自己的系統看到以下訊號時，應該回讀本案例：

• 流量高峰期間 Prometheus 記憶體使用異常增長或觸發 OOM
• Dashboard 在尖峰時段查詢變慢或 timeout，正好是最需要看的時候
• Alert 在活動期間大量觸發但多數是 false positive，值班人員開始 ignore
• prometheus_tsdb_head_series 在特定時段突然暴增，結束後回落
• Metric label 中包含高 cardinality identifier（user_id、session_id、request_id）

對「K8s metrics、service metrics、需要 PromQL 表達能力、自管 metrics 棧」這條路徑、Prometheus 是首選。

本章目標

讀完本章後、你應該能：

1. 用 docker 跑起 Prometheus、配置 scrape target
2. 用 PromQL 查詢 metrics、寫 recording rules / alerting rules
3. 設計 service discovery（K8s / Consul / file_sd）
4. 看懂 cardinality 訊號、避免 label explosion
5. 評估長期儲存（Thanos / Mimir / Cortex）跟 remote write 的選擇

最短路徑：5 分鐘把 Prometheus 跑起來

先建最小 config 檔（Prometheus scrape 自己）：

1# prometheus.yml
2global:
3  scrape_interval: 15s
4
5scrape_configs:
6  - job_name: "prometheus"
7    static_configs:
8      - targets: ["localhost:9090"]

啟動並驗證：

 1# 1. 啟動 Prometheus
 2docker run -d --name prom -p 9090:9090 \
 3  -v "$(pwd)/prometheus.yml:/etc/prometheus/prometheus.yml" \
 4  prom/prometheus
 5
 6# 2. 確認 target 正常（等 15 秒讓第一次 scrape 完成）
 7curl -s http://localhost:9090/api/v1/targets | jq '.data.activeTargets[].health'
 8
 9# 3. 查詢驗證
10curl -s 'http://localhost:9090/api/v1/query?query=up' | jq '.data.result[].value[1]'

up 回傳 "1" 代表 Prometheus 能 scrape 自己。瀏覽器訪 http://localhost:9090 可用 PromQL UI 互動查詢。實際 production 要配 retention、alerting rules 與 HA。

日常操作與決策形狀

Scrape 配置與 service discovery

子議題：

• Static config：手動列 target、適合小規模
• File SD：動態檔案、適合外部系統推送
• Kubernetes SD：K8s API server 動態發現
• Consul SD：跟 Consul service registry 整合
• 對應配置：scrape_configs 區段

PromQL 查詢

子議題：

• Instant query vs range query
• Aggregation：sum / avg / max / min / count + by / without
• Rate / increase（counter 處理）
• Histogram quantile（histogram_quantile + bucket）
• 對應指令：HTTP API /api/v1/query

Recording rules / Alerting rules

子議題：

• Recording rules：預先計算昂貴 query、降低 dashboard 查詢成本
• Alerting rules：定義 alert condition + for duration + labels / annotations
• Alertmanager：去重 / 抑制 / 分組 / routing
• 對應配置：rule_files

Deep Article

• Prometheus 容量規劃與故障模式：單機容量邊界、cardinality 與 retention 的資源模型、常見故障模式與判讀
• PromQL 與 Recording Rules 實務：常見 SLI 查詢模式、recording rules 設計慣例、效能陷阱與故障判讀
• Remote Write 與長期儲存整合：remote write 配置、Mimir / Thanos / Cortex 三家比較、故障模式與容量規劃

進階主題（按需閱讀）

High availability

子議題：

• Prometheus 沒原生 HA — 跑兩個 instance scrape 同 target、靠下游去重
• Thanos：sidecar 模式、跨 Prometheus instance 查詢統一
• Mimir：fully replicated metric storage（多 Prometheus → Mimir）
• 對應案例 4.C8 Airbnb K8s scale signals

Cardinality 管理

對應案例 4.C2 Gaming peak cardinality。子議題：

• Cardinality = unique label combinations 數量
• High-cardinality label（user_id / request_id / trace_id）會炸 Prometheus
• 偵測：prometheus_tsdb_head_series metric
• 修法：drop label / aggregation / 改用 traces backend（Honeycomb）

Remote write / read

子議題：

• Remote write：Prometheus → 長期儲存（Mimir / Cortex / Thanos / Datadog / Grafana Cloud）
• Remote read：查詢時拉長期儲存資料
• 用 receiver / agent 模式（無 local TSDB）
• 對應配置：remote_write / remote_read

Exporters 生態

子議題：

• Node exporter（host metrics）
• Blackbox exporter（HTTP / TCP / ICMP probing）
• Database exporters（postgres / mysql / redis）
• 應用層 metrics：用 client library（prometheus_client）原生暴露
• 對應 ServiceMonitor / PodMonitor（Prometheus Operator）

Prometheus Operator（K8s）

子議題：

• CRD：Prometheus / ServiceMonitor / PodMonitor / PrometheusRule / Alertmanager
• 自動發現 ServiceMonitor 物件、不手動改 scrape config
• kube-prometheus-stack Helm chart
• 對應 4.C6 ADOT EKS 對照

Pull vs Push model

子議題：

• Pull model（Prometheus default）：service discovery、health check 自然
• Push model（Pushgateway）：適合 short-lived job、不建議常駐 service
• 為何 Pushgateway 不推：cardinality 不易管、scrape semantics 違反

排錯快速判讀

Scrape failure

操作原則：先看 target 是否健康、再看 network 跟認證。

1curl -s http://localhost:9090/api/v1/targets | jq '.data.activeTargets[] | {job: .labels.job, health, lastError}'

Cardinality explosion

操作原則：series 數量持續增長、可能 OOM。

1curl -s 'http://localhost:9090/api/v1/query?query=prometheus_tsdb_head_series' | jq '.data.result[].value[1]'

對應 4.C2 Gaming peak 的處理路徑。

Query 過慢

操作原則：query 過大範圍 / aggregation 過多 → Recording rules 預先聚合。

Alert flapping / noise

操作原則：alert 觸發頻繁但無實際問題、調整 for: duration、加 absent() check、用 Alertmanager inhibition。

Memory pressure

操作原則：Prometheus retention 跟 cardinality 決定 memory。判讀：cardinality 太大 → remote write 卸載長期儲存。

何時改走其他服務

不在本頁內的主題

• PromQL 完整 syntax reference（prometheus.io/docs/prometheus/latest/querying/）
• Exporter 內部實作
• Alertmanager routing tree 細節
• Operator CRD spec

案例回寫

直接相關案例

跨 vendor 對照

下一步路由

• 上游概念：Metrics Basics
• 平行 vendor：Grafana Stack（Mimir）、OpenTelemetry
• 下游能力：4.20 Observability Evidence Package

• metrics 基本型別
• latency histogram
• error rate / throughput
• SLI / SLO / error budget

概念定位

metrics 是把服務狀態壓縮成可聚合、可比較、可告警的時間序列，責任是讓團隊看見趨勢、容量與服務健康。

這一頁處理的是 metric 型別與計算語意。counter、gauge 與 histogram 各自回答不同問題；選錯型別會讓後面的 SLI、dashboard 與 alert 都建立在錯誤訊號上。

核心判讀

判讀 metrics 時，先看指標型別是否對應問題，再看分母、bucket 與 label 是否穩定。

重點訊號包括：

• latency 是否用 percentile / histogram 補足 average 的盲點
• error rate 的分母是否能代表真實請求量
• bucket 是否覆蓋實際尾端延遲
• label 是否能切出必要維度，同時不讓 metric cardinality 失控

判讀訊號

• 用 average 而非 percentile 追 latency、p99 失真
• counter / gauge 混用、計算公式錯
• histogram bucket 沒對齊實際分佈、tail latency 被截斷
• error rate 分母不穩（流量低時誤觸發、高時稀釋）
• 商業 SLI 跟 metric 對不上、靠人解釋

聚合查詢與 recording rule

Metrics 的讀取面跟寫入面是兩個不同的效能瓶頸。寫入面的壓力來自 series 數量（cardinality）；讀取面的壓力來自查詢時的聚合計算量。兩者可以獨立失控 — series 數量合理但每次 dashboard 刷新都重算複雜表達式，query engine 一樣會過載。

Query-time aggregation 的成本

Dashboard panel 或 alert rule 每次觸發時，TSDB 對 raw series 執行聚合表達式（rate、sum、histogram_quantile）。當 raw series 數量大、查詢時間範圍長、dashboard 刷新頻率高，同一個計算會被反覆執行。

一個典型的 SLO burn rate panel 可能涉及：先算 rate、再除以 total、再跟 threshold 比較、最後乘以 window。每次刷新把整條運算鏈走一遍。當這類 panel 有十幾個、每 30 秒刷新一次，query engine 的 CPU 會被 dashboard 佔滿，留給事故即席查詢的餘量不夠。

Recording rule 把計算推到寫入時

Recording rule 是 Prometheus 生態（包括 Thanos、Mimir、VictoriaMetrics）的標準應對方式：在 TSDB 內定期執行聚合表達式，把結果寫成新的 time series。Dashboard 跟 alert rule 讀 recording rule 的輸出而非重算 raw series。

Recording rule 的設計判準是查詢頻率跟計算成本的乘積。高頻讀取（dashboard auto-refresh、每分鐘 evaluate 的 alert rule）加上高計算成本（多維度 rate + ratio + quantile）的組合最值得做 recording rule。低頻即席查詢（事故時的 ad-hoc 切片）直接查 raw series，保留完整維度。

Recording rule 的命名慣例用 level:metric:operations 格式（如 job:http_requests_total:rate5m），讓讀者從名稱直接判斷來源粒度跟計算方式。沒有命名慣例時，recording rule 增長到數百條後會難以維護跟除錯。

Rollup 與 downsampling

Rollup 解決的是時間維度的讀取成本。原始資料以 15 秒間隔採集，查詢「過去 90 天的 error rate 趨勢」時需要掃描數百萬個資料點；rollup 把舊資料聚合成 5 分鐘或 1 小時粒度，查詢時只讀取聚合後的少量資料點。

Rollup 的聚合函數選擇影響查詢語意。Counter 用 sum 合理、gauge 用 average 合理、histogram 用 average 會失去分布資訊（p99 被壓平）。設計 rollup 時要按 metric type 指定對應的聚合函數，混用會讓長時間範圍的 dashboard 產生誤導性數值。

查詢路由的透明度也是設計重點。使用者把 dashboard 時間範圍從 1 小時拉到 7 天時，系統自動從 raw series 切到 rollup series，精度從 15 秒變成 5 分鐘。如果這個切換對使用者不透明，事故中觀察到的數值變化可能是精度切換的假象而非真實服務變化。

Metrics 讀取面的資源隔離

Metrics 的 query engine 跟 log 一樣面臨多種查詢模式競爭資源的問題。Dashboard 定期刷新是穩定的背景負載；alert rule evaluation 是系統關鍵的定期負載；事故即席查詢是偶發的突增負載。三者搶同一個 query engine 時，dashboard 跟 alert 的穩定負載會壓縮即席查詢的可用資源。

Prometheus 原生的資源隔離有限，但 Thanos Query Frontend、Mimir Query Frontend、Grafana Cloud 的 query scheduler 都支援 query priority 或 query queue 分離。設計時把 alert evaluation 設為最高優先（告警不能因 query 排隊而延遲），dashboard 次之，即席查詢的延遲容忍最高但不能被完全餓死。

交接路由

• 04.6 SLI/SLO 訊號設計：把 metric 升級為 user-journey SLI
• 04.7 metric cardinality / cost：label 治理與成本邊界
• 04.9 continuous profiling：metrics 之外的第四角觀測訊號
• 04.23 觀測查詢設計：跨訊號類型的讀取路徑系統設計
• 4.C11 Uber M3：單機 Prometheus 到平台級 metrics 系統的演進

• trace / span 模型
• trace context propagation
• context 斷鏈的常見邊界與修復
• sampling 策略的 tracing 面（SSoT 在 4.7）
• service graph 與依賴發現
• 反模式

概念定位

Trace 是把一次 request 在多個服務、queue 與背景任務中的路徑串起來的診斷訊號，責任是讓團隊從症狀追到跨服務等待點。

Log 回答「某個服務發生了什麼」；metric 回答「某個服務的健康趨勢」；trace 回答「一次 request 跨多個服務時，時間花在哪、錯誤發生在哪一段」。三者互補，trace 的獨特價值在於它串起跨服務的因果鏈 — 沒有 trace，事故定位只能靠人工比對不同服務的 log timestamp。

本章處理的是 context propagation — 怎麼讓 trace context 在 HTTP call、queue 投遞、背景任務啟動等邊界上正確傳遞。Context 斷掉時，trace 從「完整路徑」退化成幾段需要人工拼接的局部紀錄，跨服務診斷的時間成本會從秒級回退到分鐘甚至小時級。

Trace 與 Span 的結構

Span 是 trace 的基本單位

一個 span 代表一段有起止時間的工作。每個 span 記錄：操作名稱（POST /api/orders）、開始與結束時間、狀態（OK / Error）、屬性（service name、http.status_code、db.statement）與事件（exception、log message）。

Span 之間透過 parent-child 關係組成 tree。一個 HTTP request 進入 API gateway 時建立 root span，gateway 呼叫 order service 時建立 child span，order service 查 DB 時建立另一個 child span。整棵 tree 共享同一個 trace id，讓所有 span 可以被聚合成一次 request 的完整路徑。

Trace 是 span tree

一個 trace 是所有共享同一個 trace id 的 span 的集合。在 waterfall view 中，trace 呈現為時間軸上的巢狀條狀圖 — root span 在最上面，child span 依序往下排列，每段的長度代表耗時。

Waterfall view 的診斷價值是「一眼看到時間花在哪」。如果 checkout API 的 total latency 是 800ms，waterfall 會顯示 payment service 佔了 600ms — 問題定位從「整個 checkout 慢」縮小到「payment service 慢」，後續 debug 只需要看 payment service 的 log 跟 metric。

Context Propagation

什麼是 trace context

Trace context 是跨服務傳遞 trace 身份的資料。最小的 trace context 包含 trace id（標識整條 trace）跟 parent span id（標識上游 span）。下游服務收到 trace context 後，建立新的 child span 並繼承 trace id，讓兩端的 span 歸屬同一條 trace。

W3C Trace Context 標準定義了 HTTP header 的傳遞格式：traceparent header 帶 trace id + parent span id + trace flags，tracestate header 帶 vendor-specific 的附加資訊。OpenTelemetry SDK 預設使用 W3C 格式；部分 vendor 有自己的 header 格式（Datadog 用 x-datadog-trace-id、AWS X-Ray 用 X-Amzn-Trace-Id），需要在 collector 或 SDK 層做格式轉換。

Propagation 的傳遞機制

HTTP call 是最常見的 propagation 路徑 — SDK 的 HTTP client middleware 自動把 trace context 注入 request header，下游 SDK 的 HTTP server middleware 自動從 header 提取 context。大部分 OpenTelemetry SDK 的 auto-instrumentation 會自動處理這一層，開發者不需要手動注入。

gRPC 用 metadata（等同 HTTP header）傳遞，機制類似。

Message queue 的 propagation 需要把 trace context 放進 message 的 header 或 metadata。Kafka 用 record header、RabbitMQ 用 message properties、NATS 用 message header。Producer 端注入、consumer 端提取。Queue 的 propagation 比 HTTP 複雜的原因是 consumer 可能在 producer 之後很久才消費 — context 的時間跨度可能從毫秒擴大到分鐘或小時。

Context 斷鏈的常見邊界

Context propagation 在以下邊界容易斷裂：

Thread / goroutine / task 邊界：同步 runtime 通常用 thread-local 存放 context，新開 thread 不會自動繼承。Go 用 context.Context 顯式傳遞，相對不容易遺漏；Java 用 ThreadLocal，啟動新 thread 或提交到 thread pool 時 context 需要手動傳遞或用 agent auto-instrumentation。Async runtime（Node.js 的 AsyncLocalStorage、Python 的 contextvars）各有自己的 context 傳播機制。

Queue / event 邊界：producer 把 trace context 注入 message header，consumer 提取並建立新 span。如果 producer 端的 SDK 沒有自動注入（例如用了原生 Kafka client 而非 instrumented client），context 就斷了。跨 queue 的 trace 在 waterfall view 中會出現時間斷層 — producer span 結束到 consumer span 開始之間可能有秒級到分鐘級的等待。

Background job / cron 邊界：cron job 或 scheduled task 沒有上游 request，沒有 trace context 可繼承。這類工作需要在啟動時建立 root span，並把 job name、schedule、trigger reason 作為 span 屬性，讓 trace 至少可以追蹤 job 內部的行為。

跨語言 / 跨 vendor 邊界：不同語言的 SDK 或不同 vendor 的 instrumentation 可能用不同的 header 格式。W3C Trace Context 標準解決了格式問題，但混用 vendor-specific SDK 時（例如一個服務用 Datadog agent、另一個用 OTel SDK），需要在 collector 層做 context format 轉換。

斷鏈的修復策略

修復斷鏈的目標是讓 trace 在邊界處重新接上，不需要人工拼接。

Queue 邊界：確保 producer 跟 consumer 都使用 instrumented client（OTel SDK 的 messaging instrumentation），而非原生 client。Instrumented client 自動處理 header 注入跟提取。Consumer 端建立的 span 用 CONSUMER kind 標記，waterfall view 會顯示 queue 等待時間。

Thread pool 邊界：Java 生態用 Context.wrap() 包裝提交到 thread pool 的 Runnable/Callable；Go 生態用 context.Context 作為第一個函數參數傳遞（這是 Go 的慣例，不需要額外處理）。Auto-instrumentation agent 可以自動處理常見 thread pool（Java 的 ExecutorService、Node.js 的 worker_threads）。

跨 vendor 邊界：在 collector 層（OTel Collector）統一轉換 header 格式。Collector 的 receiver 支援多種格式輸入，exporter 統一輸出 W3C 格式。這層轉換在 4.11 telemetry pipeline 的 collector 中介段處理。

Trace 與 Log / Metric 的關聯

Correlation id 統一

Trace id 應該同時出現在 log 的結構化欄位中。當 log 的 trace_id 欄位帶著跟 trace 相同的值，debug 工作流就能從 trace waterfall 跳到某個 span 對應的 log，或從 log 跳到完整的 trace view。

實作方式是在 logger 初始化時，把當前 span 的 trace id 注入 log 的 context fields。OTel SDK 的 log bridge 可以自動做這件事；沒有自動橋接的框架需要手動把 span.SpanContext().TraceID() 寫進 log 的 correlation id 欄位。

Exemplar：metric 到 trace 的跳板

Metric 是聚合訊號，本身不帶單一 request 的 trace id。Exemplar 是附加在 metric 資料點上的代表性 trace id — 當某個 histogram bucket 收到一個資料點時，附帶記錄產生這個資料點的 trace id。

Dashboard 上看到 latency p99 升高時，可以從 exemplar 跳到一個具體的高延遲 trace，看 waterfall 定位慢在哪。Exemplar 是 metric 到 trace 的橋樑，讓聚合訊號（metric）跟個別案例（trace）連接起來。

Service Graph 與依賴發現

Trace 資料聚合後可以自動生成 service graph — 哪些服務在呼叫哪些服務、call 的頻率、延遲分布、錯誤率。這個 graph 跟手動維護的 architecture diagram 不同：它來自實際流量，反映的是「現在真的在發生什麼」而非「設計時預期會發生什麼」。

Service graph 的價值在於依賴發現。新服務加入後，如果有 trace instrumentation，它會自動出現在 graph 上。舊服務之間新增的依賴（例如 A 開始直接呼叫 C、繞過 B）也會被 graph 反映。手動維護的 wiki 通常落後實際狀況數週到數月。

Service graph 的完整性取決於 trace 的覆蓋率。如果某些服務沒有 instrumentation 或 sampling 率太低，graph 上會出現斷點或邊權不準。把 service graph 的完整性（「有多少比例的服務有 trace」）作為觀測覆蓋率的一個指標，能推動 instrumentation 的漸進覆蓋。

詳見 4.13 service topology。

核心判讀

判讀 tracing 時，先看 propagation 是否完整，再看 sampling 是否保留可除錯樣本。

重點訊號包括：

• trace id 是否能和 log、metric 共享 correlation id
• async / queue / background job 是否能保留 parent-child 關係
• sampling 是否能在高流量下保留錯誤與高延遲樣本（策略矩陣見 4.7）
• service graph 是否能由 trace 聚合而來，並降低 wiki 手動維護成本
• trace context 在跨語言 / 跨 vendor 邊界是否用 W3C 標準統一

判讀訊號

• Request 跨服務後 trace 斷鏈、靠人重組
• Async / queue 邊界 context 沒傳遞
• 採樣率太低、production debug 找不到對應 trace
• Trace id 跟 log / metric 對不上、無共同 correlation key
• Service graph 不存在或半年沒人看
• 多個 vendor SDK 混用、header 格式不一致
• Background job / cron 沒有 root span、trace 無法追蹤

反模式

交接路由

• 4.4 dashboard-alert：trace 資料在 dashboard 的呈現跟 alert 設計
• 4.7 cardinality / cost：sampling 策略矩陣（Head / Tail / Adaptive / Exemplar）與保留決策
• 4.11 telemetry pipeline：sampling 在 collector 的集中治理、跨 vendor header 轉換
• 4.13 service topology：trace 訊號聚合成依賴圖
• 4.17 telemetry data quality：sampling bias 跟 trace 完整性的資料品質
• 4.23 觀測查詢設計：trace 查詢作為即席診斷的一種模式

自架 log endpoint 的適用場景

自架 log endpoint 適合的前提是：client 和 server 在同一個網路內（同機、同 LAN、同 VPN/tailnet），log 的唯一消費者是開發者本人。

app_tunnel 就是這個場景。Server（ttyd）和 client（Flutter app）在同一台機器或同一個 Tailscale tailnet 內。開發者同時是使用者和維運者。Log 的消費方式是 grep — 不需要 dashboard、不需要告警、不需要多人共享。

在這個場景下，自架 log endpoint 的成本遠低於商業方案。一個 Go 程式開 HTTP endpoint 接收 JSON log 寫入檔案，20 行程式碼就能完成。Client 端的 AppLogger 在 debug mode 同時寫 console 和 POST 到 endpoint。Debug 時用 grep + jq 查詢，不需要額外工具。

1Client (Flutter) → HTTP POST /log → Go receiver → JSON file → grep/jq

這個方案沒有外部依賴、沒有帳號管理、沒有費用、沒有資料隱私顧慮（log 不離開本機網路）。

商業方案的適用場景

商業方案（Sentry、Crashlytics、Datadog）適合的前提是：使用者分佈在外部網路，log 的消費者包含非開發者（維運、客服、產品），且需要告警和趨勢分析。

商業方案提供的能力包括：跨網路收集（SDK 自動處理網路不穩定和批次傳輸）、多人查看 dashboard、告警規則設定、crash 報告自動分群、用戶 session 重播。這些能力在自用工具場景下不需要，在商業產品場景下是基礎需求。

商業方案的成本包括：SDK 整合和設定、帳號和權限管理、月費（依事件量計費）、資料隱私合規（log 傳到第三方伺服器）。

判斷流程

使用者在哪裡

使用者和 server 在同一個網路內（自用工具、內部工具、開發期測試）→ 自架 log endpoint 是成本最低的選擇。

使用者在外部網路（上架 app store、SaaS 產品、B2B 部署）→ 商業方案的跨網路收集能力是必要的，自架需要處理的 edge case（離線緩衝、重試、批次傳輸）太多。

Log 消費者是誰

只有開發者自己 → grep/jq 足夠，不需要 dashboard。

包含非技術人員（客服、產品經理）→ 需要視覺化 dashboard 和搜尋介面，商業方案的 UI 是這個需求的標準答案。

是否需要告警

開發者自己用、即時看 log → 不需要告警。

有維運值班、需要被動發現問題 → 需要告警規則，商業方案內建。

混合方案

開發期用自架 log endpoint（零成本、即時可用），production 切換到商業方案 — 這個策略可行的前提是 log 層的 API 設計足夠抽象。

AppLogger 提供統一的 log 介面（log(level, name, data)），底層實作在 debug mode 寫 console + POST 到本機 endpoint，在 release mode 寫 console + 呼叫 Sentry/Crashlytics SDK。切換只改 AppLogger 的底層實作，不改呼叫端。

這個抽象的投資在自用工具階段就值得做 — 即使目前不需要商業方案，統一的 log 介面也讓 log 點的管理更一致。

下一步路由

• 三層 log 的詳細設計 → 三層 log 設計
• 在功能規格中定義 log 點 → 功能規格中的 log 點定義方法
• Log 收集後的 schema 設計 → monitoring 模組二 Log Schema

業務背景

一個遠距醫療平台，服務多家醫療機構（multi-tenant），處理病歷查閱、處方開立、檢驗報告與預約排程。平台受 HIPAA 跟當地個資法規範，稽核單位要求能回答「哪個使用者在什麼時間查看了哪個病患的哪份紀錄」。

初期系統的存取紀錄散落在各服務的 application log 中 — 病歷服務記了一筆 GET /patient/123/records，處方服務記了一筆 POST /prescription，但兩者沒有共同的 correlation key。稽核問「護理師 A 在 3 月 15 日存取了哪些病歷」時，工程師需要在四個服務各自 grep，再用 timestamp 近似對齊，整個流程耗時半天且結果不可靠。

技術挑戰

存取 log 與 application log 混合

存取紀錄（誰看了什麼）跟 operational log（request timing、error、retry）寫在同一個 pipeline。Application log 的 retention 設定 30 天（除錯夠用），但法規要求存取紀錄保留 6 年。等到稽核來查詢時，超過 30 天的存取紀錄已經被刪。

跨服務存取鏈斷裂

一次病歷查閱可能經過 API gateway → auth service → patient service → record service → audit service 五個服務。每個服務各自記 log，但沒有統一的 access event correlation。Auth service 知道「誰」，patient service 知道「看了哪個病患」，record service 知道「看了哪份紀錄」— 三段資訊散落在三個服務的 log 中，無法自動關聯。

Multi-tenant retention 差異

不同醫療機構受不同法規管轄 — 機構 A 在美國需要 HIPAA 6 年 retention，機構 B 在歐盟需要 GDPR 的「目的限縮」原則（保留期限隨用途而定），機構 C 在台灣需要醫療法規定的 7 年。統一 retention policy 要嘛過度保留（增加成本與 PII 暴露面），要嘛保留不足（法規風險）。

解法

Data access audit log 獨立 pipeline

把存取事件從 application log 分離出來。每當使用者查閱、修改或匯出 PHI（Protected Health Information）時，產生結構化 access event：

 1{
 2  "event_type": "phi_access",
 3  "actor": "nurse-a@hospital-x.com",
 4  "patient_id": "P-2048",
 5  "resource": "medical_record/lab_result/2026-03-15",
 6  "action": "view",
 7  "trace_id": "abc123",
 8  "access_id": "acc-789",
 9  "tenant": "hospital-x",
10  "timestamp": "2026-03-15T14:22:05Z"
11}

Access event 寫入獨立的 immutable storage（append-only log），跟 application log 分開的 pipeline 與 retention。

Cross-service access chain

在 API gateway 入口產生 access_id，跟 trace_id 一起透過 context propagation 傳遞到所有下游服務。每個服務在產生 access event 時帶上這兩個 key。查詢時用 access_id 就能撈出一次存取操作在所有服務的完整軌跡，不需要手動拼接。

trace_id 用於關聯 operational 訊號（latency、error），access_id 用於關聯合規稽核。兩者可以相同也可以不同 — 關鍵是 access event 要同時帶兩個 key。

分層 retention 與 tenant-level policy

每個 tenant 在平台建立時設定法規要求的 retention 期限。Pipeline 根據 tenant tag 自動把 access event 路由到對應的 retention tier。Tenant A 的紀錄到第 6 年自動歸檔到 cold，tenant B 在 GDPR 目的屆滿時觸發刪除審核。

存取 log 中的 PII 處理

Access event 本身包含 patient_id 跟 actor，這些在存取紀錄中是必要資訊（「誰看了什麼」需要這兩個欄位）。處理方式是存取控制而非遮罩 — access event storage 的讀取權限限縮到 compliance team 跟 audit 角色，engineering team 的一般查詢權限無法看到這些欄位。

取捨

分層架構的最大風險是跨層查詢的延遲 — 稽核要求「給我 3 年前的存取紀錄」時，cold tier 的解凍時間可能是小時級。解法是在稽核週期前預先解凍相關 tenant 的 cold archive 到 warm tier。

回寫教材的連結

• 4.12 Audit Log Governance：audit log 分離與 PII 治理。
• 4.18 Observability Operating Model：access log pipeline 的 ownership 與 review cadence。
• 4.17 Telemetry Data Quality：timestamp integrity 跟跨服務時序校正。
• 4.3 Tracing Context：access_id 跟 trace_id 的 propagation 設計。

判讀徵兆

讀者在自己的系統看到以下訊號時，應該回讀本案例：

• 稽核問「使用者 X 在某段時間存取了什麼」，回答需要超過數小時的手動拼接
• 存取紀錄的 retention 跟法規要求不一致，但沒人確切量化差距
• Multi-tenant 環境中所有 tenant 共用同一個 retention policy，無法按法規區分
• 跨服務的存取事件無法自動關聯，需要靠 timestamp 近似比對
• PHI 相關的 log 跟一般 application log 存在同一個 storage，存取控制無法區隔

對「需要 OSS / 自管 observability、跨 data source 統一儀表板、不想 vendor lock-in」這條路徑、Grafana Stack 是首選。

本章目標

讀完本章後、你應該能：

1. 部署 Grafana + Prometheus + Loki + Tempo 基本棧
2. 用 LogQL 查詢 Loki、用 TraceQL 查詢 Tempo
3. 設計 dashboard as code（Jsonnet / Terraform）
4. 評估 Mimir vs Thanos 的長期 metrics 儲存選擇
5. 評估 Grafana Cloud（managed）跟自管的取捨

最短路徑：5 分鐘把 Grafana Stack 跑起來

1# 1. 用 docker-compose 跑起 Grafana + Prometheus + Loki
2# TODO: docker-compose.yml with grafana / prometheus / loki
3
4# 2. 在 Grafana 加 data source
5# TODO: Prometheus / Loki 各自的 datasource config
6
7# 3. 建第一個 dashboard
8# TODO: 用 explorer 試 PromQL + LogQL

最短路徑驗證 Grafana 起來、可訪 metrics + logs。實際 production 要評估 Mimir / Tempo + Grafana Cloud 取捨。

日常操作與決策形狀

Grafana 視覺化

子議題：

• Data source 配置（Prometheus / Loki / Tempo / Postgres / MySQL / Elasticsearch）
• Dashboard 設計：variable + template + panel
• Dashboard as code：Jsonnet (Grafonnet) / Terraform Grafana provider
• 對應指令：HTTP API /api/dashboards

LogQL（Loki 查詢）

子議題：

• LogQL syntax：log stream selector + filter + parser + aggregation
• 跟 PromQL 對齊的設計（同樣 label-based）
• 範例：{job="app"} |= "error" | json | line_format "..."
• 對應 metrics-from-logs（unwrap + rate）

TraceQL（Tempo 查詢）

子議題：

• TraceQL syntax：span selector + attribute + aggregation
• 範例：{ span.http.status_code = 500 && duration > 1s }
• Service graph：跨服務依賴自動分析
• 對應 trace-to-logs / trace-to-metrics 關聯查詢

Deep Article

• LGTM Stack 組合運維：四個元件的責任分工、部署模式、常見故障與 dashboard provisioning
• Loki 設計與操作限制：label-based index 設計、LogQL 查詢模式、cardinality 治理與 Elasticsearch 差異

進階主題（按需閱讀）

Loki 設計與限制

子議題：

• Storage：S3 / GCS / 本地、按 stream 切 chunks
• Label cardinality 跟 Prometheus 一樣敏感（不是 stream content）
• LogQL 不適合 high-cardinality content search（用 Elastic）
• 對應 4.C3 Healthcare retention

Tempo trace 採集

子議題：

• 接受 OTLP / Jaeger / Zipkin protocol
• Storage：S3 / GCS、cheap object storage
• Trace ID lookup 為主、no full-text search（用 traces metrics 反向查）
• 對應 4.C4 X-Ray to OTel

Mimir 長期 metrics 儲存

子議題：

• Prometheus remote write 接收 metric
• Horizontally scalable（multi-tenant）
• 跟 Thanos / Cortex 的對照（Mimir 是 Cortex fork + improvements）
• 對應 4.C8 Airbnb K8s scale

Pyroscope continuous profiling

子議題：

• CPU / memory / mutex / goroutine profiling
• Flame graph 視覺化
• 跟 Tempo trace 關聯（trace-to-profile）
• OSS（Grafana 收購）vs Pyroscope OG

Grafana Cloud（managed）

子議題：

• Free tier 額度 + paid tier
• 含所有 stack（Metrics / Logs / Traces / Profiles）
• Grafana Cloud vs Datadog cost 對照
• Hybrid 模式：self-host backend + Grafana Cloud Grafana

Unified Alerting

子議題：

• Grafana 9+ 統一 alerting（取代 dashboard alert + Prometheus alertmanager 分裂）
• 跨 data source 寫 alert rule
• Multi-dimensional alert（per-label）
• 對應 Alertmanager 兼容

排錯快速判讀

Dashboard 載入慢

操作原則：先看 query 範圍跟 panel 數、用 query inspector 看 query 時間分布。

Loki query 過慢 / 失敗

操作原則：Loki query 需要 label filter 先縮範圍、再 content match。

1# TODO: LogQL: {namespace="prod", app="api"} |= "error"（先 label 後 filter）

Tempo span gap

操作原則：trace 不完整、看 sampling 設定 + Collector buffer 是否 drop。

Mimir ingestion 失敗

操作原則：remote_write rate / size limit 撞到 Mimir quota。判讀：Mimir HTTP 429 / 413。

Grafana 跟 Prometheus disconnected

操作原則：data source 連不上、看 Grafana log + network。

何時改走其他服務

不在本頁內的主題

• 各 Grafana plugin 細節
• Dashboard 美術 / UX 建議
• Grafana / Loki / Tempo / Mimir 各自完整 admin 手冊
• Grafana 商業版 (Enterprise) 功能

案例回寫

直接相關案例

跨 vendor 對照

下一步路由

• 上游概念：Metrics Basics
• 平行 vendor：Prometheus、OpenTelemetry
• 下游能力：4.20 Observability Evidence Package

• Dashboard 設計原則：SLI 導向 vs 指標堆疊
• Alert 設計：symptom-based vs cause-based
• Alert noise control 與 alert fatigue
• Runbook linkage
• Dashboard / alert 的生命週期與 ownership
• 反模式

概念定位

Dashboard 與 alert 是把觀測訊號轉成操作入口的控制面，責任是讓團隊在正常巡檢與事故響應時看到同一組事實。

Dashboard 讓人理解狀態，alert 讓人採取行動。兩者的設計問題不同：dashboard 的問題是「資訊太多、焦點不明」；alert 的問題是「通知太多、行動不明」。兩者都需要 ownership、生命週期管理與 runbook 連結。

Dashboard 設計

SLI 導向 vs 指標堆疊

Dashboard 的常見失敗模式是「把所有能拿到的指標都放上去」。二十個 panel、五十條曲線、無法在 3 秒內回答「服務現在健康嗎」。

SLI 導向的 dashboard 從使用者體驗出發：第一排 panel 回答「使用者感受到的健康狀態」（availability、latency percentile、error ratio），第二排回答「健康狀態的原因」（dependency latency、queue depth、resource utilization），第三排回答「趨勢與容量」（traffic growth、storage usage、capacity headroom）。

每個 panel 都應該能回答一個具體問題。如果團隊看了某個 panel 後的反應是「所以呢？」，這個 panel 不是放錯位置就是不該存在。

Dashboard 層級

不同使用者看不同層級的 dashboard。把所有資訊擠在同一個 dashboard 會讓每個角色都找不到自己要的。

Service overview：on-call 工程師的第一個入口。5-8 個 panel，回答「這個服務現在有沒有問題」。SLI 指標（error rate、latency p99、availability）、最近的 alert、dependency 健康。

Debug dashboard：事故中的深入診斷入口。按 dependency 分組（database panel group、cache panel group、downstream API panel group），每組顯示延遲、錯誤率、連線數。Panel 數量多但按需展開。

Capacity dashboard：容量規劃用。週到月級的趨勢圖 — traffic growth、storage usage、connection pool saturation、cost trends。刷新頻率低（每小時或每天），panel 讀 recording rule 或 rollup 資料。

Business dashboard：給非工程角色看。轉換率、使用者活躍度、營收指標。資料來源可能不只是觀測訊號，還包括 analytics 跟 business metrics。

Dashboard 的查詢效能

Dashboard 是觀測查詢設計中「聚合趨勢」模式的主要消費者（見 4.23）。每個 panel 每 30 秒刷新一次，十個團隊各自有 dashboard 就是每分鐘數百個背景查詢。

Panel 設計時要注意查詢成本：時間範圍越長、raw series 越多、聚合越複雜，query-time cost 越高。長時間趨勢 panel 應該讀 recording rule 或 rollup series，而非每次刷新都掃描 raw data。

Alert 設計

Symptom-based vs cause-based

Symptom-based alert 觸發在使用者可感知的症狀上 — error rate 升高、latency p99 超過閾值、availability 下降。Cause-based alert 觸發在內部原因上 — CPU > 90%、disk usage > 85%、connection pool exhausted。

Symptom-based 是 alert 設計的起點。原因是：cause-based alert 容易產生大量「系統在忙但使用者沒受影響」的 false alarm。CPU 短暫衝到 95% 然後回落，如果 latency 跟 error rate 都正常，這個 alert 不需要人類介入。

Cause-based alert 的價值是預防性告警 — disk usage 趨勢在兩天後會滿、connection pool 使用率在高峰時逼近上限。這類 alert 不需要立即行動，但需要在工作時間排入 task。把 cause-based alert 設成 warning（不 page）、symptom-based alert 設成 critical（page on-call），能降低 noise。

SLO-based alerting

SLO-based alerting 用 burn rate 取代固定閾值。不是「error rate > 1% 就告警」，而是「error budget 的消耗速度超過預期就告警」。

Burn rate alerting 的好處是自動適應基線。低流量時段的 1% error rate 可能只是幾筆錯誤、不值得 page；高流量時段的 0.5% error rate 可能代表大量使用者受影響。Burn rate 用「相對於 SLO 允許的錯誤量，目前消耗速度有多快」來判斷嚴重性，比固定閾值更能反映使用者影響。

SLO-based alert 的實作通常用 multi-window burn rate — 短視窗（5 分鐘）抓急性問題、長視窗（1 小時）抓慢性問題。兩個視窗都超過 burn rate 閾值時才觸發，減少單一 spike 造成的 false alarm。

SLI/SLO 訊號的詳細設計見 4.6。

Alert 的必要欄位

每個 alert rule 應該帶以下 metadata，讓收到 page 的 on-call 工程師在 30 秒內知道下一步：

• Severity：critical（立即行動）/ warning（工作時間處理）/ info（記錄但不通知）
• Runbook link：對應的 runbook URL，描述診斷步驟跟可能的修復動作
• Owner：負責這個 alert 的團隊或服務
• Dashboard link：點進去直接看相關 panel，不用自己找 dashboard
• Summary：一句話描述發生了什麼（checkout error rate > 2% for 5 minutes），而非只有 alert rule 名稱

缺少 runbook link 的 alert 等於「通知了但不告訴你做什麼」。On-call 工程師收到不認識的 alert 時，第一反應是 ack 然後繼續觀察 — 這就是 alert fatigue 的起點。

Alert Noise Control

什麼是 noise

Alert noise 是「觸發了但不需要人類行動」的 alert。包括：

• False positive：條件觸發但實際沒問題（短暫 spike 觸發固定閾值、maintenance 期間的預期 error）
• Redundant alert：同一個問題觸發多個 alert（database 慢 → query timeout alert + error rate alert + latency alert 同時觸發）
• Stale alert：條件已經不適用（服務改版後舊 alert rule 沒更新、abandoned service 的 alert 還在）

Noise rate 量測

Noise rate = 不需要行動的 alert / 總 alert。追蹤方式是讓 on-call 工程師在 ack alert 時標記「actionable」或「noise」。月度彙整 noise rate，超過 30% 的 alert rule 進入治理流程（業界常用的基線閾值，Google SRE Workbook 建議 actionable rate 維持在 70% 以上；團隊可依自身容忍度調整）。

降噪手段

Grouping：把同一個根因觸發的多個 alert 合併成一則通知。Alertmanager 的 group_by 讓同服務、同 alert name 的 alert 只發一次。

Inhibition：高嚴重性 alert 抑制低嚴重性。Database down 觸發時，所有依賴該 database 的 query timeout alert 被抑制 — 根因已知、不需要每個症狀都通知。

Silence / maintenance window：已知的維護活動期間暫停特定 alert。Silence 需要有過期時間，避免永久靜默掩蓋真實問題。

Hysteresis：alert 觸發需要條件持續 N 分鐘（for: 5m），避免瞬間 spike 觸發。恢復也需要條件持續 N 分鐘，避免「反覆觸發 → 恢復」的 flapping。

Runbook 設計

Runbook 是 alert 的行動指南。每個 critical alert 應該連到一份 runbook，描述「收到這個 alert 時該做什麼」。

Runbook 的有效結構：

1. 症狀描述：這個 alert 代表什麼（「checkout error rate 超過 SLO burn rate」）
2. 影響評估：誰受影響、嚴重程度（「付款功能受影響、影響所有 checkout 流程」）
3. 診斷步驟：先看哪個 dashboard、查哪些 log、跑哪些 query
4. 可能的修復動作：restart service、scale up、rollback deployment、failover to backup
5. 升級路徑：如果 15 分鐘內無法解決，通知誰

Runbook 的維護責任跟 alert 的 owner 一致。Alert rule 改了但 runbook 沒更新是常見的退化 — 把 runbook 的 last-reviewed date 作為 alert 治理的審計項目。

Dashboard 與 Alert 的生命週期

Dashboard 跟 alert 都有生命週期。建立時有用，但隨服務演進可能變得過時、冗餘或誤導。沒有生命週期管理的 dashboard / alert 系統會累積 debt — dashboard 數量膨脹但無人看、alert rule 堆疊但多數是 noise。

Ownership

每個 dashboard 跟每個 alert rule 都需要明確的 owner。Owner 負責：維護 panel / rule 的正確性、定期審視 noise rate 跟使用率、在服務變更時更新對應的 dashboard / alert。

沒有 owner 的 dashboard 跟 alert 應該有過期機制 — 超過 N 天沒有人訪問的 dashboard 標記為候選淘汰、超過 N 天沒有觸發的 alert rule 審視是否仍有意義。

定期審視

Dashboard 跟 alert 的定期審視是 4.8 signal governance loop 的一部分。每季或每次重大事故後，審視：

• 哪些 alert 的 noise rate 過高、需要調整或刪除
• 哪些 dashboard 沒人訪問、可以合併或淘汰
• 事故中是否有缺少的 alert 或 dashboard panel

Ownership 矩陣與 metadata 欄位的詳細設計見 4.18 operating model。

核心判讀

Dashboard 跟 alert 是否有效，最直接的訊號是 alert noise rate 跟 dashboard 訪問頻率 — noise rate 超過 30% 代表通知品質退化，dashboard 長期零訪問代表資訊跟決策脫節。

重點訊號包括：

• Alert 是否能對應到明確 runbook、ownership 與停止條件
• Dashboard 是否有固定使用者與更新責任
• Threshold 是否對齊 SLO、容量邊界或使用者影響
• Noise rate 是否被追蹤並回寫治理流程
• Dashboard panel 是否讀 recording rule 而非每次重算 raw data

判讀訊號

• Alert 跟 runbook 沒連、收到 page 不知道做什麼
• Dashboard 數量爆量、無 owner、半年無人訪問
• 同一訊號多個 alert 重複觸發、無 grouping 或 inhibition
• Alert noise rate > 30%、ack 後無實際動作，形成 alert fatigue
• Alert threshold 用直覺數字、沒對齊 SLO / 商業承諾
• Dashboard panel 載入慢、因為直接查 raw series 而非 recording rule
• Maintenance window 過後 silence 沒移除、真實問題被掩蓋

反模式

交接路由

• 4.3 tracing：trace waterfall 作為 dashboard 的診斷入口
• 4.6 SLI/SLO 訊號設計：alert 的訊號源頭、burn rate alerting 的 SLI 依據
• 4.8 訊號治理閉環：alert / dashboard 的生命週期維運
• 4.10 client-side / RUM：補 server-side 看不到的 dashboard 維度
• 4.14 anomaly detection：rule-based alert 之外的統計訊號
• 4.18 operating model：dashboard / alert 的 ownership 矩陣與 metadata 欄位
• 4.23 觀測查詢設計：dashboard 查詢的效能與 recording rule

格式統一性

app_tunnel 在 W2 修復時補的 developer.log 格式不統一（T.C4）。不同元件由不同時間點、不同 debug 需求補上的 log，各自有各自的風格：

有的帶 name: 參數讓 log 可以按元件過濾：

1developer.log('WS connected', name: 'ConnectionManager');

有的不帶，混在全域 log 裡無法過濾：

1developer.log('auth token sent');

有的帶 // i18n-exempt 標記（因為 linter 會對 hardcoded string 報警），有的忘了加。有的把錯誤訊息放在 error: 參數，有的用字串串接。

這些不一致來自事後補 log 的結構性原因：每條 log 是在解決當下問題時加的，沒有統一規範，也沒有 review。加完能定位問題就提交，下次遇到新問題再加新的 log — 格式隨機。

設計產物 log 在產出前就有命名規則和格式規範（見 功能規格中的 log 點定義方法）。所有 log 點走同一個 AppLogger 介面，name、level、結構化欄位在規格階段就定義好，實作時照規格寫。

覆蓋完整性

事後補 log 的覆蓋範圍由「哪些問題已經發生過」決定。W2-002 auth token 問題觸發了 ConnectionManager 和 TerminalScreen 的 log 補充，但 TtydProtocol、BiometricService、CredentialRepository、EnrollmentScreen 四個元件仍然零 log — 因為這四個元件在 W2 的 debug 過程中不是瓶頸。

六個核心元件中四個零 log 的狀態意味著：下次如果問題出在 BiometricService（例如特定 iOS 版本的 biometric API 行為改變），debug 又會回到「手動加 log → 重新編譯 → 插拔裝置」的循環。事後補 log 只覆蓋已知問題的路徑，對未知問題沒有防護。

設計產物 log 的覆蓋範圍由功能流程的步驟數決定。每個功能規格列出所有步驟的 log 點，不管這些步驟是否曾經出過問題。BiometricService.authenticate() 在規格中就有 start/done/failed 三個 log 點，無論是否遇過 biometric 問題。

維護成本

事後補 log 隨 debug 過程累積，沒有統一管理。隨時間推移：

• 某些 log 的觸發條件已經不存在了（被修復的 bug 對應的 log），但沒人清理
• 某些 log 的格式和新加的 log 不一致，但沒人統一
• 某些 log 的 context 資訊不足（當時能定位問題是因為開發者記得 context，半年後換人接手就不夠了）
• 某些 log 在 release build 中不該出現但忘了加條件

設計產物 log 有規格文件作為 source of truth。功能變更時更新規格中的 log 點列表，刪除的步驟對應的 log 點一起刪除，新增的步驟對應的 log 點一起新增。Log 的生命週期和功能的生命週期綁定。

從事後補過渡到設計產物

已有的事後補 log 不需要全部重寫。過渡策略是：

統一入口：建立 AppLogger 封裝，把現有的 developer.log 呼叫改為走 AppLogger。這一步不改 log 內容，只改呼叫方式，讓後續的格式統一和功能切換有統一入口。

補規格：對每個功能寫出 log 點規格表（四類 log 點），比對現有 log 和規格的差距。規格中有但程式碼中沒有的 log 點 = 覆蓋缺口，補上。程式碼中有但規格中沒有的 log 點 = 可能是過時的 debug log，評估是否刪除。

新功能走設計產物流程：從下一個新功能開始，功能規格中包含可觀測性欄位。新功能的 log 從一開始就是設計產物品質。

過渡的第一步是建立統一入口，具體的 log 點規格格式見功能規格中的 log 點定義方法。規格中的每個 log 點屬於哪一層（連線生命週期 / protocol / 使用者行為），在三層 log 設計中定義。收集到 log 之後用自架還是商業方案處理，見自架 log endpoint vs 商業方案的判斷流程。

觀察

app_tunnel 的六個核心元件在實機測試前的 log 覆蓋狀態：

W2-004（P0：iOS 實機 WS stream 不觸發）的 debug 過程：無法從任何 log 判斷問題發生在 biometric → credential → WS connect → auth token → stream listen 的哪一步。開發者被迫在每個函式手動加 developer.log，重新編譯，插拔裝置測試，反覆數次才定位到「stream 訂閱時機」問題。

判讀

1. Log 缺失把 debug 成本從秒級升到分鐘級。如果 ConnectionManager 在企劃階段就設計了「Step 1: biometric → Step 2: credential → Step 3: WS connect → Step 4: auth token → Step 5: listen stream」五步 log，W2-002 的 auth token 問題在第一次連線就能從 log 看到「Step 3 完成，Step 4 未執行」。

2. 「事後補 log」的 log 品質較低。W2 修復時補的 developer.log 格式不統一（有的帶 name:，有的不帶；有的用 // i18n-exempt 標記，有的忘了），沒有統一的 log 層級，沒有結構化欄位。事後補的 log 是救火工具，不是可觀測性設計。

3. 自用工具最適合自架 log 收集。app_tunnel 的 server 和 client 都在同一台機器上（或同一個 Tailscale tailnet），client 可以直接打 HTTP POST 到本機的 log endpoint，不需要 Sentry 或 Crashlytics。一個 Go 寫的 JSON log receiver（20 行）+ grep 就是完整的 debug 工具鏈。

4. Log 設計是功能規格的一部分。「連線到 ttyd 終端機」這個功能的規格不只是「建立 WS 連線」，還包含「每步有 log、失敗有 log、成功有 log」。跟 API 規格需要定義 request/response 一樣，連線功能需要定義 log 點。

策略

1. 功能規格階段列出 log 點清單：每個功能的規格文件新增「可觀測性」欄位，列出啟動/步驟/錯誤/完成四類 log 點。
2. 建立統一 log 層：封裝 developer.log 為 AppLogger，統一 name、level、格式。開發期用 developer.log，後續可切換到 HTTP log endpoint。
3. 自架 log endpoint 方案：本機 Go server 開一個 /log POST endpoint，接收 JSON log，寫入檔案。Client 端 AppLogger 在 debug mode 同時寫 console + POST 到 endpoint。開發期 grep 查詢，不需要 dashboard。
4. Protocol log 獨立一層：WebSocket frame type、payload 前綴、auth handshake 結果獨立記錄，跟 business log 分開。這層 log 在 release mode 應該能關閉。

下一步路由

• 想設計客戶端 log 方案 → 模組二：客戶端可觀測性
• 想理解三層 log 設計 → 三層 log 設計
• 想建自架 log endpoint → 自架 log endpoint vs 商業方案

觀察

AWS 已明確提出 X-Ray SDK/Daemon 的維護時程，並提供遷移到 OpenTelemetry 的路徑。

判讀

當 observability agent 與 SDK 受限於單一供應商，轉向 OTel 可以降低未來轉移成本，但需要治理採集、匯出與語意對齊。

策略

1. 先盤點現有 instrumentation 與依賴 SDK。
2. 先換 collector/agent，再逐步改應用端 instrumentation。
3. 把 trace/metric 的等價驗證納入 release gate。

下一步路由

回 4.11 telemetry pipeline 與 4.17 telemetry data quality。

引用源

• X-Ray to OpenTelemetry migration guide

對「想要 turnkey 體驗、不想自管 observability、多訊號類型統一平台、團隊規模可承擔成本」這條路徑、Datadog 是首選。

本章目標

讀完本章後、你應該能：

1. 安裝 Datadog Agent、配置 APM auto-instrumentation
2. 用 Datadog Logs / Metrics / APM 三大查詢介面
3. 控制 cost（log indexing / metric cardinality / APM trace sampling）
4. 寫 Monitor as code（Terraform）
5. 評估 OTLP ingestion 跟 Datadog SDK 的取捨

最短路徑：5 分鐘把 Datadog 跑起來

1# 1. 安裝 Agent
2# TODO: DD_API_KEY=<key> DD_SITE="datadoghq.com" bash -c "$(curl -L ...)"
3
4# 2. 啟用 APM
5# TODO: 在 Agent config 加 apm_config.enabled: true
6# TODO: 應用程式加 ddtrace-run / dd-trace-py
7
8# 3. 驗證 Agent + APM 上線
9# TODO: 在 Datadog UI 看 Host map + APM Service List

日常操作與決策形狀

Agent 安裝與配置

子議題：

• 安裝方式：package（apt/yum）/ container / K8s DaemonSet / Lambda extension
• Agent config：core / APM / Logs / NetFlow / SNMP 各 sub-config
• DogStatsD：應用層 custom metrics 入口
• 對應指令：datadog-agent status、/etc/datadog-agent/datadog.yaml

APM 自動 instrumentation

子議題：

• 各語言 tracer：dd-trace-java / dd-trace-py / dd-trace-js / dd-trace-go
• Auto-instrumentation 廣度（業界最廣）
• Service / Resource / Operation 三層 trace 結構
• 對應 4.C7 Datadog OTel migration

Logs 配置

子議題：

• 採集方式：Agent 採集 / Fluent Bit / Vector → Datadog
• Indexing vs Archives：indexing 費錢但可查、archives 便宜但只能 rehydrate
• Log Pipeline：parsing / enrichment / sensitive data scrubbing
• 對應 cost 控制：indexing rate / retention

Metrics

子議題:

• Custom metrics（DogStatsD / Agent / API）
• Metric Type：count / gauge / histogram / distribution
• Cardinality 控制：每 metric 收 tags 數限制
• 對應 4.C2 Gaming cardinality

Deep Article

• Datadog 成本治理與 Agent 配置：計價模型、custom metrics 成本控制、Agent 部署配置與常見故障
• OTLP Ingestion 與 OTel 整合：Agent OTLP receiver 配置、OTel SDK feature parity、resource mapping 與故障判讀

進階主題（按需閱讀）

成本治理

子議題：

• Hosts pricing（vs APM / Logs / Custom Metrics 各自獨立）
• Log indexing rate 控制（Exclusion Filters）
• Custom metrics 計費（per metric per host）
• APM trace sampling
• 對應 Datadog Usage Attribution

OTLP ingestion

子議題：

• Datadog Agent 接受 OTLP（gRPC + HTTP）
• 對 OTel SDK 用戶的優勢（avoid Datadog SDK lock-in）
• 對應 4.C7 Datadog OTel migration
• Datadog 自家 SDK vs OTel：feature parity 取捨

Monitor as code

子議題：

• Terraform Datadog provider：dashboard / monitor / SLO / synthetic
• 跟 IaC pipeline 整合
• 多環境（dev / staging / prod）配置

APM Trace Sampling

子議題：

• Head-based sampling（rate-based）
• Tail-based（Datadog 新功能、需 Agent 支援）
• Ingestion vs Indexing sampling 兩層
• 對應 cost 控制

RUM / Synthetics

子議題：

• RUM（Real User Monitoring）：前端用戶體驗
• Synthetics：browser test / API test 主動探測
• Session Replay
• 跟 APM 關聯：frontend trace → backend trace

Security Monitoring

子議題：

• Cloud SIEM
• ASM（Application Security Management、wAF/RASP）
• Cloud Security Posture Management
• 跟 07 security 模組 對照

跟 Monitoring 模組的分工

本頁從 server-side APM 平台角度說明 Datadog — agent 部署、cost governance、OTel 遷移、跟 Grafana Stack 的對照。Client-side 的 RUM 體驗（RUM SDK 四種事件、session replay、全棧追蹤的 client 端視角）見 Monitoring 模組 Datadog RUM。

兩者的交叉點是 trace context — RUM SDK 注入的 trace header 讓 client action 跟 server span 串在同一個 trace。沒有 server-side APM 的團隊用 RUM 也有價值（client-side error + performance），但全棧追蹤需要兩邊都部署。

排錯快速判讀

Agent 連不上 Datadog

操作原則：先 datadog-agent status 看 connectivity、再看 API key + region。

APM trace 缺失

操作原則：trace context propagation 在跨 service / 跨 thread 邊界丟失。

1# TODO: dd-trace-py debug mode / `DD_TRACE_DEBUG=true`

Log indexing cost 爆

操作原則：indexed log 量超預期、用 Exclusion Filter 過濾不必要 log。判讀：Datadog Usage page 看每 day indexed log。

Custom metrics 爆預算

操作原則：每 host 每 metric 計費、cardinality 高（per-user / per-request label）會爆。判讀：Metrics Summary 看 metric volume。

Monitor noise

操作原則：alert 太多、低品質、用 Composite Monitor + Recovery / No data threshold。

何時改走其他服務

不在本頁內的主題

• 各語言 dd-trace SDK 完整 API
• Datadog UI 操作詳細
• Pricing 詳細計算（用 Datadog Usage page）
• 600+ integrations 各自設定

案例回寫

直接相關案例

跨 vendor 對照

待補 Datadog 案例：客戶 cost optimization stories、large scale 部署（Shopify / Coinbase / Zoom 等）engineering blog。

下一步路由

• 上游概念：4.17 Telemetry Data Quality
• 平行 vendor：OpenTelemetry、Grafana Stack
• 下游能力：4.20 Observability Evidence Package

Vendor / Platform 清單

實作時的常用選擇見 vendors — T1 收錄 OpenTelemetry / Prometheus / Grafana Stack / Datadog / Elastic Stack / Honeycomb / AWS CloudWatch / GCP Cloud Operations / Sentry，每個 vendor 有定位、適用場景、取捨與預計實作話題的骨架。Error tracking 是獨立子維度（Sentry），跟 metrics / logs / traces 三角互補。

進入 vendor 比較前，先回到 觀測、可靠性與事故服務選型 判斷目前缺的是訊號層、驗證層、響應層還是閉環層。可觀測性 vendor 選型只處理訊號層與部分告警入口；可靠性驗證與事故協作要交給可靠性與事故流程。

Deep article（vendor 自身的配置、故障、容量）跟 migration playbook（跨 vendor 遷移流程）的撰寫進度見 vendors/ 的「內容覆蓋進度」段。

暫定分類

選型入口

可觀測性選型的核心判斷是團隊缺少哪一種操作訊號。當工程師需要還原事件脈絡時先看 log；需要趨勢與容量判斷時先看 metrics；需要跨服務路徑時先看 trace；需要共同操作入口時先看 dashboard；需要主動通知時先看 alert。

Log aggregation 適合查單一事件與錯誤脈絡；metrics 適合觀察 error rate、latency、throughput 與 queue lag；tracing 適合拆解跨服務 request path；dashboard 適合整合 SLI/SLO 與容量趨勢；alert 適合把需要動作的異常送到負責者面前，並連到 alert runbook。

接近真實網路服務的例子包括 checkout 變慢、queue lag 上升、WebSocket 斷線增加、Redis timeout 增加與下游 API 錯誤率上升。這些場景的共同問題是從症狀回到原因，因此本模組會先處理欄位、關聯、metric cardinality、查詢、視覺化與告警規則。

訊號情境庫

本模組收的是可重複套用的訊號情境，不收服務級案例庫。服務的長期時間線與事故史，留給可靠性驗證與事故處理兩個模組；可觀測性平台只保留能反覆套用在不同服務上的觀測判讀樣式，讓讀者先知道「該看哪種訊號、如何辨識失真、下一步交給誰」。

這種情境庫的責任是定位訊號，服務史由可靠性驗證與事故處理承接。當讀者需要的是平台能力與判讀路由，可觀測性模組的範圍就夠了；當需要的是某個服務怎麼一路演進、怎麼歷次驗證與恢復，那是可靠性與事故模組的工作。

跟可靠性與事故模組的串接

可觀測性是「觀測 → 驗證 → 事故」閉環的起點，但閉環是雙向的：

• 觀測 → 事故：訊號（log spike、SLO burn rate、error rate）觸發告警、進入事故響應流程。判讀邊界由可觀測性定義、響應節奏由事故處理定義。
• 觀測 → 驗證：SLO / SLI 量測由可觀測性提供、是 SLO 政策與 chaos hypothesis 的 baseline。沒有可信訊號就沒有可信驗證。
• 驗證 → 觀測：驗證需求驅動訊號設計 — chaos experiment 需要新 metric、load test 需要新 dashboard、SLO 政策需要新 alert rule。
• 事故 → 觀測：每次事故 post-incident review 揭露偵測缺口（symptom-based alert 缺、訊號太晚、cardinality 不足），回寫到訊號治理。
• 資安 → 觀測：資安偵測、稽核證據與資料外洩風險會形成新的 log schema、audit log、alert 與 evidence chain 需求。尤其 偵測覆蓋率與訊號治理 會回寫到訊號治理閉環。
• 觀測 → 資安：log、trace、audit log 與 service topology 提供資安 triage 的事實基礎，讓 稽核追蹤與責任邊界 能把責任鏈落到可查證資料。
• 詳細閉環說明：見 Observability / Reliability / Incident Response 閉環。

跟 Monitoring 模組的串接

Monitoring 模組 聚焦非 server 端 runtime — mobile app、web 頁面、本機腳本的行為蒐集、錯誤回報與 SDK 設計。本模組聚焦 server-side observability。兩者的交叉點是 trace context propagation 和 event transport format。

• 4.10 Client-side / Synthetic / RUM：概念定位、RUM 與 synthetic 的 server-side 整合
• 4.24 Client-to-Server 觀測串接：從 browser click 到 server span 的完整 trace 鏈路
• 監控資料的雙重用途：同一份 event data 如何同時服務行為分析（monitoring/08）與訊號治理（04）
• 0.15 跨模組 Checkout Episode：從 DB write 到 observability evidence 的四層端到端串聯

與語言教材的分工

語言教材處理如何產生穩定欄位與執行環境訊號。Backend observability 模組處理收集、儲存、查詢、視覺化、告警與跨服務關聯。

企業案例補充

可觀測性的案例補充重點是「訊號平台為什麼這樣設計」，不是工具比較表。閱讀時先抓資料規模、查詢延遲、保留策略與多租戶治理，再對照本模組章節。

若要擴充企業案例，先到 0.14 企業選型案例圖譜 依「企業型態 × 規模階段」挑樣本，再把觀測面教訓回寫到 4.16-4.21。這樣案例擴充會先補齊覆蓋度，再補單點技巧。

第一批缺口回填建議先做三條觀測題目：FinTech 補 audit log completeness 與 evidence traceability（回寫 4.12、4.20）；Gaming 補高峰時段 signal freshness 與 cardinality guardrail（回寫 4.7、4.17）；Healthcare 補資料主權相關的 access evidence 與留存邊界（回寫 4.12、4.18）。

第一批案例正文入口見 可觀測性案例正文，可直接對應 4.12 / 4.17 / 4.18 / 4.20 的回寫欄位。

第二批觀測遷移案例已補： 4.C4 X-Ray 到 OTel 轉換 與 4.C5 Cloud Trace OTLP 導入。兩者可直接回寫到 4.11 telemetry pipeline、4.17 telemetry data quality 與 4.18 operating model。

反例與規模對照入口： 4.C9 反例 / 4.C10 對照。

回退判讀寫法見 0.C4 回退判讀寫法，觀測案例要優先保留訊號語意、採樣策略、告警偏差與 SLO 判讀差異。

跨語言適配評估

可觀測性使用方式會受語言的 logger 生態、trace context、exception/error model、執行環境 metrics 與 instrumentation SDK 影響。同步 runtime 要保留 request context 與 thread-local 邊界；async runtime 要確認 trace context 能跨 task 傳遞；輕量並發 runtime 要觀察 task/goroutine 數量、queue lag 與下游等待。動態語言要特別管理 log schema 穩定性；強型別語言則要避免過度包裝導致 trace 與 error chain 斷裂。

章節列表

註：4.1-4.24 已完成概念層、實作示範與端到端串接正文，案例庫可支援 06 與 08 的路由引用。後續工作重點為案例深挖與跨模組回寫密度提升，而非章節補齊。

個案前拓展空間

個案前拓展的責任是補足讀案例時需要的判讀框架。04 適合補「訊號是否足以支援判讀」這類跨服務能力，不適合展開單一服務的事故史。

本輪先完成這四個前置控制面，讓後續 06 與 08 文章有穩定的訊號前提可引用。若服務案例暴露的是訊號分類問題，回寫 4.16；若暴露的是資料品質問題，回寫 4.17；若暴露的是 owner 與治理問題，回寫 4.18；若暴露的是架構本身難以診斷，回寫 4.19。

後續深化方向

04 後續深化以「案例反例補強、跨模組回寫、證據欄位對齊」為主。可觀測性是 06 與 08 的輸入層，重點在提高 evidence package、data quality 與 incident write-back 的銜接精度。

實作探討入口

進入實作層時，04 建議先從一條最小切片開始：同一個 user journey 建立 SLI + dashboard + alert + evidence query 四件組，再把欄位直接接到 6.23 Verification Evidence Handoff 與 8.19 Incident Decision Log。

首篇示範已完成： 4.22 Checkout API Evidence Package 實作示範。

完成條件是每篇都能回答四件事：判讀訊號、風險代價、控制面邊界與下一步路由。這樣 06 的 SLO / readiness / experiment safety 與 08 的 intake / decision log / impact assessment 才能引用 04，而不需要在各自章節重寫觀測前提。

跟 Infra 可觀測性的分界

Infra 模組六：可觀測性與 log 處理基礎設施層的訊號 — log group、CloudWatch metric、alarm 跟資源同生命週期的 IaC 管理。本模組處理應用層的訊號 — 服務的延遲、錯誤率、trace、業務指標。分界的判讀是：這個訊號是「資源建立時就該存在」還是「功能開發時才埋」——前者進 infra 的 IaC，後者進本模組的應用程式碼。事故排查時兩層合流：infra alarm 告訴你哪個資源異常，本模組的 trace 告訴你哪個請求路徑受影響。

• 觀測系統為什麼需要威脅建模
• 三類弱點：觀測盲區、告警失真、資料暴露
• 每類弱點的判讀流程與修復方向
• 跟 4.4 dashboard-alert 跟 07 資安 的分工

概念定位

可觀測性威脅建模的判讀目標是「觀測系統本身有哪些弱點會讓事故更難處理、更慢收斂、或擴大成資安事件」。觀測系統是事故處理的核心工具 — 工具失靈時，事故的 MTTD（偵測時間）跟 MTTR（修復時間）都會被拉長。

本章用三類弱點盤點觀測系統：觀測盲區（看不到問題）、告警失真（看到錯的東西）、資料暴露（觀測資料本身變成風險）。每類弱點有各自的判讀流程跟修復方向。

跟傳統資安威脅建模的差異：資安威脅建模聚焦「攻擊者怎麼入侵系統」；觀測威脅建模聚焦「觀測系統的設計缺陷怎麼讓事故更難處理」。兩者的交叉點在資料暴露 — 觀測資料含 secret 或 PII 時，觀測弱點直接成為資安弱點。

哪些服務要先做觀測弱點盤點

下列情境同時出現時，觀測弱點會快速放大：

• 服務數量增加，跨服務呼叫變深 — trace 斷鏈的影響面擴大
• 值班依賴告警，但告警常常失真或過量 — alert fatigue 讓真正的問題被淹沒
• 調查事故高度依賴人工搜尋 log — 缺少結構化查詢入口
• 支援工具與觀測平台可接觸敏感資料 — 觀測資料的存取控制不足

弱點一：觀測盲區

觀測盲區是「問題存在但觀測系統看不到」的狀態。盲區的危險在於它讓團隊對系統狀態的判斷建立在不完整的資訊上 — 看起來一切正常，但其實有路徑沒被觀測到。

常見盲區

Sampling 導致的盲區：head sampling 按固定比例丟棄 trace，低流量服務的錯誤樣本可能全部被丟。事故時查 trace 查不到，因為 sampling 把剛好那些 request 的 trace 丟了。修復方向是 tail sampling 或 minimum sample floor（見 4.7 sampling 策略）。

Uninstrumented 路徑：新上線的服務沒加 instrumentation、async worker 沒有 span、third-party SDK 的 HTTP call 沒被攔截。這些路徑在 service graph 上不存在，事故時團隊甚至不知道有這條依賴。修復方向是把 instrumentation coverage 作為 readiness review 的檢查項。

Context 斷鏈形成的局部盲區：trace context 在 queue、thread pool、background job 邊界斷掉後，下游的 span 成為孤兒。團隊可以看到下游服務有問題，但看不到跟上游 request 的因果關係。修復策略見 4.3 tracing。

Log schema 漂移：不同服務的 log 用不同欄位名稱記錄同一個概念（request_id vs req_id vs requestId）。查詢時用 request_id 搜尋會漏掉用其他名稱的服務。修復方向是 log schema 的跨服務統一。

盲區的判讀方式

• 列出所有服務，標記哪些有 trace instrumentation、哪些沒有
• 檢查 service graph 跟已知 architecture diagram 的差異 — 差異就是盲區
• 用已知的跨服務 request 做 end-to-end trace 驗證，看有沒有斷點
• 檢查 sampling policy，確認低流量服務跟 error sample 的保留率

弱點二：告警失真

告警失真是「觀測系統看到了、但告訴你的是錯的或沒用的」。失真比盲區更危險 — 盲區至少讓團隊知道「這裡沒資料、要用其他方式查」；失真讓團隊基於錯誤訊號做判斷。

常見失真模式

Threshold drift：alert 的閾值在設定時是合理的（error rate > 1%），但服務改版後基線變了（正常 error rate 從 0.1% 變成 0.5%），閾值沒跟著調。結果是 alert 頻繁觸發但團隊知道是 false alarm — alert fatigue 開始累積。

Aggregation 掩蓋：用 average latency 做 alert，tail latency 被掩蓋。Average 200ms 但 p99 是 5 秒 — 1% 的使用者體驗極差但 alert 沒觸發。修復方向是 percentile 跟 histogram。

Alert storm：單一根因觸發大量 alert（database 慢 → 所有依賴該 database 的服務都觸發 latency alert + error alert + timeout alert）。On-call 收到 20 則通知，分不清哪個是因、哪個是果。修復方向是 alert grouping 跟 inhibition（見 4.4 dashboard-alert）。

Stale dashboard：Dashboard 的 panel 引用的 metric name 已改名、panel 的 query 因 label 變更而回空值。Dashboard 看起來正常（曲線是平的），但其實是 no data 被渲染成 zero。修復方向是 dashboard 的 no-data alert 跟定期審視。

失真的判讀方式

• 追蹤 alert noise rate（每月有多少 alert 是 actionable 的）
• 檢查 alert rule 的 threshold 跟當前 baseline 是否對齊
• 確認 SLI 用 percentile 而非 average
• 事故復盤時問「這次的事故，alert 有沒有在對的時間告訴我們對的事」

弱點三：資料暴露

觀測資料本身是風險資產。Log 可能含 secret（API key、token、password）、trace 可能含 PII（使用者 email、電話號碼在 span attribute 中）、dashboard 可能對所有人開放且顯示敏感業務指標。

常見暴露路徑

Log 含 secret：SDK 或框架在 error 發生時把完整 request body 寫進 log，body 中的 API key、token、password 跟著進入 log storage。Log storage 的存取控制通常比 secret manager 寬鬆 — 有 log 讀取權限的人都能看到 secret。

Trace attribute 含 PII：http.url attribute 帶完整 URL（含 query parameter 裡的 email 或 token）、db.statement attribute 帶完整 SQL（含 WHERE 子句的使用者 ID）。Trace storage 的保留期可能比業務資料庫長，PII 在 trace 裡存活的時間超過必要範圍。

Dashboard 權限過寬：所有工程師都能看所有服務的 dashboard，包含財務相關的 metric（營收、訂單金額分布）。Dashboard 的存取控制粒度通常是「整個 Grafana instance」而非「per-dashboard」。

Collector / pipeline 有管理員權限：OTel Collector 或 log aggregator 以 admin 權限部署，可以讀寫 secret、修改配置、存取所有資料。Collector 被入侵時，攻擊者可以把 redaction 規則關掉、讓後續的 log 全量暴露。

暴露的修復方向

• SDK 端做 redaction（在送出前掃描已知 secret pattern 並替換成 [REDACTED]）
• Collector 端做 attribute 過濾（在 pipeline 中移除敏感 attribute）
• Log / trace storage 做存取控制（RBAC、per-team 隔離）
• Dashboard 做權限分層（業務 dashboard 需要額外授權）
• 定期掃描 log storage 檢查是否有未 redact 的 secret pattern

詳見 07 資安與資料保護 跟 4.12 audit log governance。

設計取捨：訊號完整度與成本控制

觀測覆蓋越完整，盲區越少、事故定位越快。同時儲存、查詢與維護成本也會上升。穩定做法是先定義核心訊號與最低欄位（log schema 的 correlation fields、SLI 的 availability + latency），再按高風險路徑逐步加深觀測。

「全收」的成本問題見 4.7 cardinality；「選擇性收」的品質問題見 4.17 telemetry data quality。

核心判讀

判讀觀測弱點時，按三類依序盤點：

1. 盲區：哪些服務或路徑沒有被觀測到？Sampling 是否丟掉高價值樣本？
2. 失真：Alert noise rate 有多高？Threshold 跟 baseline 是否對齊？SLI 用的是 average 還是 percentile？
3. 暴露：Log / trace 是否含 secret 或 PII？Dashboard 權限是否過寬？Collector 的存取權限是否最小化？

判讀訊號

• 事故時查 trace 查不到（sampling 丟掉）
• Service graph 跟 architecture diagram 有明顯差異（uninstrumented 服務）
• Alert noise rate > 30%（threshold drift 或 aggregation 掩蓋）
• 同一事故觸發 10+ 個 alert（alert storm、缺 grouping / inhibition）
• Log grep 到 API key 或 token（redaction 缺失）
• Dashboard 對所有人開放且顯示營收指標（權限過寬）

交接路由

• 4.3 tracing：context 斷鏈的修復策略
• 4.4 dashboard-alert：alert noise control、grouping、inhibition
• 4.7 cardinality：sampling 策略與保留決策
• 4.8 signal governance：alert / dashboard 的定期審視
• 4.12 audit log：觀測資料的存取控制與稽核
• 4.16 readiness review：instrumentation coverage 的上線前檢查
• 4.17 telemetry data quality：sampling bias 跟 schema drift 的品質問題
• 07 資安：secret management、data masking、存取控制

觀察

Google Cloud 在 Cloud Trace 提供 OTLP 支援，降低應用程式對特定傳輸介面的綁定。

判讀

當團隊要跨多環境與多工具，標準化傳輸協定能減少重複 instrumentation 與遷移摩擦。

策略

1. 將 collector 與 in-process exporter 對齊 OTLP。
2. 把 trace schema 與 sampling 規則集中治理。
3. 在遷移期保留舊通道與新通道比對。

下一步路由

回 4.11 telemetry pipeline 與 4.18 observability operating model。

引用源

• OTLP in Google Cloud Observability

本章目標

讀完本章後、你應該能：

1. 部署 Elasticsearch + Kibana + Beats 基本棧
2. 用 KQL / Lucene 查詢 logs、用 ES DSL 寫進階搜尋
3. 設計 index lifecycle（hot / warm / cold / frozen）
4. 評估 Beats / Logstash / Fluent Bit / Vector 的採集選擇
5. 評估 Elastic License vs OpenSearch fork 的取捨

最短路徑：5 分鐘把 Elastic Stack 跑起來

1# 1. 用 docker-compose 跑 ES + Kibana
2# TODO: docker-compose.yml with elasticsearch + kibana
3
4# 2. 用 Filebeat 採集 host logs
5# TODO: filebeat.yml with inputs + output.elasticsearch
6
7# 3. 在 Kibana 查詢驗證
8# TODO: KQL: `@timestamp >= now-15m AND log.level: "error"`

日常操作與決策形狀

採集 pipeline

子議題：

• Beats（Filebeat / Metricbeat / Packetbeat / Heartbeat / Auditbeat）：輕量、各自專屬
• Logstash：重型 ETL（grok parsing / enrichment / 多 output）
• Fluent Bit / Vector：替代採集 agent（更輕量、OSS）
• 對應 4.C6 ADOT EKS 對照

查詢語法

子議題：

• KQL（Kibana Query Language）：直覺、適合日常查詢
• Lucene query string：複雜搜尋、boolean operators
• ES DSL（JSON）：API 級進階查詢
• ES|QL（Elastic Query Language、ES 8.11+）：類 SQL pipeline 語法

Index 設計

子議題：

• Index template（mapping / settings）
• Data streams（time-series log / metrics）
• Field types：keyword / text / date / numeric / object / nested
• Dynamic mapping 風險：unbounded field 爆 index

Index Lifecycle Management（ILM）

子議題：

• Hot phase：active write
• Warm phase：read-only、查詢頻率低
• Cold phase：searchable snapshot（S3 / object storage）
• Frozen phase（ES 7.12+）：searchable snapshot + minimal cluster resource
• Delete phase

Deep Article

• Index Lifecycle Management 與 Log Pipeline：ILM policy 設計、data stream / rollover、Beats vs Elastic Agent 採集選擇、ingest pipeline 與 shard sizing、cost governance

Migration Playbook

• Elastic Cloud 遷移：自管 Elastic Stack 遷移到 Elastic Cloud

進階主題（按需閱讀）

Elastic APM

子議題：

• APM Server 接收 trace data
• 各語言 APM agent（Java / Python / Node / .NET / Go / Ruby / PHP）
• 接受 OTLP（ES 7.16+）
• Service map / dependency 視覺化

Elastic Security（SIEM）

子議題：

• SIEM dashboard / detection rule
• ECS（Elastic Common Schema）跨資料統一 field naming
• Sigma rule import
• 跟 07 security 模組 對照

Cluster scaling

子議題：

• Node roles：master / data / ingest / coordinating / ML / transform
• Hot-warm-cold architecture
• Shard sizing（推薦 20-40GB per shard）
• Cross-cluster search / replication

Elastic License vs OpenSearch fork

子議題：

• 2021 Elastic 改 ELv2 / SSPL（非 OSI 認可）— AWS 不能提供「Elasticsearch as a Service」
• AWS fork OpenSearch（Apache 2.0、基於 ES 7.10）
• OpenSearch 持續演進、跟 ES 功能逐漸分歧
• 選擇判讀：合規 → OpenSearch；要最新 ES feature → Elastic

Searchable Snapshots

子議題：

• 把 cold/frozen index 存 S3 / GCS / Azure Blob
• 查詢時動態 hydrate、成本降 80%+
• 適合 logs retention 長但查詢頻率低
• 對應 4.C3 Healthcare retention

Vector / Fluent Bit 採集替代

子議題：

• 為何用 Vector / Fluent Bit：更輕、resource 用量低
• Beats 在 K8s 跑起來資源耗較大
• 對應 cost 跟 maintainability 取捨

排錯快速判讀

Index mapping explosion

操作原則：dynamic mapping 對未知 field 自動建 index、大量 field 爆 ES。

1# TODO: GET /_cat/indices?v 看 field count
2# TODO: PUT index/_mapping 鎖定 fields

Cluster yellow / red

操作原則：cluster status 影響 query。

1# TODO: GET /_cluster/health
2# TODO: GET /_cat/shards?v 看 unassigned shards

Query 過慢

操作原則：query 結果 > 10K → 用 search_after / scroll；text field 上做 aggregation → 改 keyword field。

Disk pressure

操作原則：cluster disk > 85% → ES 進 read-only 模式。判讀：cluster.routing.allocation.disk.watermark。

Logstash backpressure

操作原則：Logstash queue full → upstream Beats 累積 backpressure。判讀：Logstash monitoring page。

何時改走其他服務

不在本頁內的主題

• ES query DSL 完整 reference
• Lucene scoring 演算法
• Kibana dashboard 美術
• Elastic ML / Anomaly Detection 細節

案例回寫

直接相關案例

跨 vendor 對照

下一步路由

• 上游概念：4.17 Telemetry Data Quality
• 平行 vendor：Grafana Stack（Loki 對照）、OpenTelemetry
• 下游能力：4.20 Observability Evidence Package

本章目標

學完本章後，你將能夠：

1. 分辨 structured log、domain event log 與 state repository
2. 設計穩定的 log 欄位名稱
3. 判斷哪些資料不應寫進 log
4. 用 EventLog.Append 表達事件記錄邊界
5. 測試穩定欄位，而不是測自由文字

【觀察】先判斷記錄用途

記錄邊界的核心問題是資料要服務誰。工程師除錯、系統重播、使用者查詢是三種不同用途，對應三種不同儲存與格式責任。

structured log 服務操作診斷，event log 保存 normalized fact，state repository 回答目前狀態。先分清楚用途，才知道欄位該放哪裡。這個用途判斷比選擇哪個 logging package 更關鍵 — 工具決定怎麼寫，用途決定寫什麼、放哪裡。

【判讀】structured log 是操作訊號

structured log 的核心用途是讓工程師知道系統正在發生什麼，並且能用欄位查詢。它應該記錄操作訊號，而不是完整業務資料。

1logger.Info(
2    "event accepted",
3    "layer", "adapter",
4    "event_type", string(event.Type),
5    "event_id", event.ID,
6    "subject_id", event.SubjectID,
7    "correlation_id", event.CorrelationID,
8)

message 給人讀，欄位給查詢工具使用。若未來要查某種事件是否大量進入系統，event_type 欄位比文字搜尋更可靠。

常見 log 欄位可以先定義成 helper，避免不同地方拼出不同名稱：

 1func LogAttrsForEvent(event DomainEvent) []any {
 2    return []any{
 3        "event_id", event.ID,
 4        "event_type", string(event.Type),
 5        "subject_kind", string(event.SubjectKind),
 6        "subject_id", event.SubjectID,
 7        "correlation_id", event.CorrelationID,
 8        "schema_version", event.SchemaVersion,
 9    }
10}

使用時可以展開欄位：

1logger.Info("event accepted", LogAttrsForEvent(event)...)

這個 helper 保護的是 log schema。欄位名稱穩定，查詢與 dashboard 才能穩定。

【策略】reason 欄位要像 enum

reason 的核心語意是可聚合的原因分類。它應使用小集合穩定值；完整錯誤訊息則放在 error 欄位協助診斷。

1const (
2    ReasonInvalidPayload = "invalid_payload"
3    ReasonQueueFull      = "queue_full"
4    ReasonDuplicateEvent = "duplicate_event"
5    ReasonTimeout        = "timeout"
6)

記錄拒絕事件時：

1logger.Warn(
2    "event rejected",
3    "layer", "adapter",
4    "reason", ReasonInvalidPayload,
5    "event_type", string(event.Type),
6    "error", err,
7)

reason 用來統計，error 用來診斷，message 用來讓人快速理解。這三者不要混成一個大字串。

【判讀】event log 記錄 normalized fact

domain event log 的核心責任是保存已正規化的 domain event。它記錄的是系統承認的事實；raw request、debug log 與目前狀態分別屬於不同記錄邊界。

先定義 port：

1type EventLog interface {
2    Append(ctx context.Context, event DomainEvent) error
3}

memory implementation 可以先這樣寫：

 1type InMemoryEventLog struct {
 2    mu     sync.Mutex
 3    events []DomainEvent
 4}
 5
 6func NewInMemoryEventLog() *InMemoryEventLog {
 7    return &InMemoryEventLog{}
 8}
 9
10func (l *InMemoryEventLog) Append(ctx context.Context, event DomainEvent) error {
11    l.mu.Lock()
12    defer l.mu.Unlock()
13
14    l.events = append(l.events, cloneDomainEvent(event))
15    return nil
16}

event log 應該保存 DomainEvent envelope 中的穩定欄位，例如 event ID、type、subject、schema version、occurred/received time。它不需要保存 adapter 的 raw input，除非你已經明確設計 raw audit log。

【執行】event log 要保護 copy boundary

event log 的核心資料也是內部狀態。若 event 包含 slice、map 或 json.RawMessage，append 與讀取時都要避免外部修改內部資料。

1func cloneDomainEvent(event DomainEvent) DomainEvent {
2    cloned := event
3    if event.Payload != nil {
4        cloned.Payload = append(json.RawMessage(nil), event.Payload...)
5    }
6    return cloned
7}

若要提供查詢方法，也要回傳複製資料：

 1func (l *InMemoryEventLog) List() []DomainEvent {
 2    l.mu.Lock()
 3    defer l.mu.Unlock()
 4
 5    result := make([]DomainEvent, len(l.events))
 6    for i, event := range l.events {
 7        result[i] = cloneDomainEvent(event)
 8    }
 9    return result
10}

這裡展示的是教學用記錄邊界。真正 event store 還需要持久化、排序、[schema migration](/go/backend/knowledge-cards/schema-migration)、重播策略與交易語意。

【策略】state repository 保存目前狀態

state repository 的核心責任是回答目前狀態。它可以由 event 更新，但用途不同於保存所有歷史事實的 event log。

例如：

1type JobRepository interface {
2    Apply(ctx context.Context, event DomainEvent) error
3    Get(ctx context.Context, id string) (JobProjection, bool, error)
4}

event log 和 state repository 可以在 processor 中各自被呼叫：

 1type RecordingEventProcessor struct {
 2    eventLog   EventLog
 3    repository JobRepository
 4    logger     *slog.Logger
 5}
 6
 7func (p *RecordingEventProcessor) Process(ctx context.Context, event DomainEvent) error {
 8    if err := p.eventLog.Append(ctx, event); err != nil {
 9        return fmt.Errorf("append event log: %w", err)
10    }
11
12    if err := p.repository.Apply(ctx, event); err != nil {
13        return fmt.Errorf("apply state projection: %w", err)
14    }
15
16    p.logger.Info("event processed", LogAttrsForEvent(event)...)
17    return nil
18}

這段程式展示三種記錄邊界：event log 保存事實，repository 更新目前狀態，structured log 記錄操作訊號。

【判讀】記錄位置要跟錯誤發生層一致

記錄位置的核心規則是在哪一層能提供最多上下文，就在哪一層記錄。同一個錯誤通常選擇一個主要層次記錄，避免 log 被重複訊號淹沒。

常見位置：

例如 adapter 解碼失敗：

1logger.Warn(
2    "callback rejected",
3    "layer", "adapter",
4    "reason", ReasonInvalidPayload,
5    "payload_bytes", len(body),
6)

這裡記錄 payload 大小即可診斷資料是否異常；完整 payload 可能包含敏感資料或過大內容。

【策略】敏感資料預設不進 log

敏感資料邊界的核心規則是 log 會被保存、轉發與搜尋，所以 token、password、完整 payload、完整個資應排除在 log 之外。

可以記錄：

• ID 或 opaque identifier
• payload byte length
• schema version
• 欄位是否存在
• hash 或 checksum

不應記錄：

• password
• access token
• cookie
• 完整 request body
• 完整 personal data

若需要追蹤同一筆資料，可以記錄安全識別碼：

1logger.Debug(
2    "payload received",
3    "payload_bytes", len(body),
4    "payload_sha256", sha256Hex(body),
5)

debug log 也需要遵守同樣規則；只要可能被集中收集，就要先控制敏感資料。

【執行】log helper 測試只測穩定欄位

log helper 測試的核心目標是保護欄位名稱與值。log message 文案是給人讀的內容，通常保留調整空間。

 1func TestLogAttrsForEvent(t *testing.T) {
 2    event := DomainEvent{
 3        ID:            "evt_1",
 4        Type:          EventNotificationCreated,
 5        SubjectKind:   SubjectNotification,
 6        SubjectID:     "ntf_1",
 7        CorrelationID: "corr_1",
 8        SchemaVersion: 1,
 9    }
10
11    attrs := LogAttrsForEvent(event)
12    got := attrsToMap(attrs)
13
14    if got["event_id"] != "evt_1" {
15        t.Fatalf("event_id = %v, want evt_1", got["event_id"])
16    }
17    if got["event_type"] != string(EventNotificationCreated) {
18        t.Fatalf("event_type = %v, want %s", got["event_type"], EventNotificationCreated)
19    }
20}

測試輔助函式可以把 key-value slice 轉成 map：

 1func attrsToMap(attrs []any) map[string]any {
 2    result := make(map[string]any)
 3    for i := 0; i+1 < len(attrs); i += 2 {
 4        key, ok := attrs[i].(string)
 5        if !ok {
 6            continue
 7        }
 8        result[key] = attrs[i+1]
 9    }
10    return result
11}

這個測試直接檢查 helper 輸出，不需要真的寫 log 或解析 logger output。

【執行】event log 測試要保護 append 與 copy

event log 測試的核心目標是確認事件被 append，且外部無法透過原始 payload 或回傳值修改內部紀錄。

 1func TestInMemoryEventLogAppendCopiesPayload(t *testing.T) {
 2    log := NewInMemoryEventLog()
 3    payload := json.RawMessage(`{"topic":"deployments"}`)
 4
 5    event := DomainEvent{
 6        ID:            "evt_1",
 7        Type:          EventNotificationCreated,
 8        SubjectKind:   SubjectNotification,
 9        SubjectID:     "ntf_1",
10        OccurredAt:    time.Date(2026, 4, 22, 10, 0, 0, 0, time.UTC),
11        ReceivedAt:    time.Date(2026, 4, 22, 10, 1, 0, 0, time.UTC),
12        SchemaVersion: 1,
13        Payload:       payload,
14    }
15
16    if err := log.Append(context.Background(), event); err != nil {
17        t.Fatalf("append event: %v", err)
18    }
19
20    payload[0] = '['
21
22    events := log.List()
23    if string(events[0].Payload) != `{"topic":"deployments"}` {
24        t.Fatalf("payload was modified through original slice")
25    }
26}

json.RawMessage 本質是 []byte，所以需要 copy。這類細節很容易被忽略，測試可以把邊界固定下來。

實作檢查清單

新增結構化記錄欄位時，可以依序檢查：

1. 這筆資料是給除錯、重播，還是查詢
2. structured log 是否只保存操作訊號與安全欄位
3. event log 是否保存 normalized domain event
4. state repository 是否只保存目前 projection
5. log 欄位名稱是否穩定
6. reason 是否是小集合分類
7. 是否避免完整 payload 與敏感資料
8. event log 是否保護 copy boundary
9. 測試是否檢查穩定欄位，而不是自由文字

設計檢查

檢查一：log 服務操作診斷

log 是操作診斷訊號，不是穩定查詢 API。需要使用者查詢的目前狀態，應該進 repository 或 read model。

檢查二：event log 保存 normalized fact

event log 記錄的是 normalized fact。若把暫時性錯誤、debug 訊息與 raw payload 全塞進 event log，重播與 audit 會變得不可信。

檢查三：欄位名稱維持一致

event_id、eventID、id 混用會讓查詢失效。欄位 schema 要像 API 一樣維持穩定。

檢查四：完整 payload 需要明確策略

完整 payload 可能包含敏感資料，也可能非常大。除非有明確安全與保存策略，否則只記錄大小、hash、ID 與必要欄位。

本章不處理

本章先處理 log、event log 與 repository 的分工；集中式 log 平台與可重播事件系統，會在下列章節再往外延伸：

• Go 進階：Durable queue、outbox 與 idempotency
• Go 進階：Observability pipeline、metrics 與 tracing
• Backend：可觀測性平台

和 Go 教材的關係

這一章承接的是 event log、state repository 與 log schema；如果你要先回看語言教材，可以讀：

• Go：如何新增一種 domain event
• Go：如何新增 repository port
• Go：用 interface 隔離外部依賴
• Go：結構化日誌欄位設計

可觀測性要事先設計，是因為失敗發生的當下，你能拿到的資訊就已經定型了。如果腳本只把輸出丟到終端機、失敗時只留下一句通用的錯誤，那當下你就只有那句話可看；如果它一路把帶時間戳的紀錄寫進檔案、失敗時主動印出出錯的位置，那同一個失敗就變得可定位。差別不在失敗本身，在失敗前你準備了什麼。如果你寫的是自己的 bootstrap（例如部署 dotfile 的那支 install.sh），這層要在你第一次跑它之前就設計進去，而不是等它出事才回頭加；就算腳本不是你寫的、你只是來 debug 一次失敗，下一段「找程式自己的 log」一樣適用。

為什麼會瞎找

不可觀測的腳本失敗時，你手上只有終端機捲動過的那些輸出，而那往往不足以定位真正的原因。終端機的輸出是易逝的、會被後續輸出沖掉、多個來源的訊息交錯在一起；更麻煩的是，很多失敗的「表面錯誤」離「真正原因」隔了好幾層。一個指令因為前面某個變數是空的而失敗，但它報出來的錯可能完全沒提到那個空變數——你看著一個誤導性的症狀，往上游找不到源頭。

破解這種瞎找的，常常是一份你一開始沒看的 log。很多程式在終端機只印一段摘要，卻同時把詳細的執行紀錄寫進一個 log 檔；當終端機的訊息不足以定位時，那份程式自己寫的 log 裡往往就有答案。除錯時養成「找程式自己的 log，而不是只盯著終端機捲動」的習慣，是把瞎找變成定位的關鍵一步——這也是 模組七日誌判讀 的核心。而對你自己寫的 bootstrap，你可以更進一步：在設計時就讓它產生這樣一份 log。

三個內建可觀測性的手法

讓一支 bootstrap 腳本可診斷，有三個低成本、效果明顯的手法，它們合起來把「失敗了」變成「失敗在第幾行、哪個指令、什麼狀態」。

log 落地：把全部輸出 tee 進帶時間戳的檔案

第一個手法是讓腳本的全部輸出同時進終端機跟一個 log 檔，而不是只進終端機。終端機的捲動是易逝的，log 檔是持久的——可以事後 grep、可以貼給別人看、可以比對前後兩次跑的差異。在 bash 裡，一行 exec 就能把後續所有 stdout 與 stderr 都導去 tee：

1LOG_DIR="${XDG_STATE_HOME:-$HOME/.local/state}/dotfiles"
2mkdir -p "$LOG_DIR"
3LOG_FILE="$LOG_DIR/install-$(date +%Y%m%d-%H%M%S).log"
4exec > >(tee -a "$LOG_FILE") 2>&1

帶時間戳的檔名讓每次跑各留一份、不互相覆蓋，事後可以回溯「上一次成功跟這次失敗差在哪」。log 檔放在 XDG_STATE_HOME（狀態資料的標準位置）底下，符合慣例、也不污染家目錄。

錯誤定位：用 ERR trap 印出出錯的行與指令

第二個手法是讓腳本在中斷的瞬間，主動報出「是哪一行、哪個指令、什麼結束碼」失敗的。配合 set -e（出錯即停）的腳本，預設只會默默地停，不告訴你停在哪。加一個 ERR trap，就能在 set -e 中斷之前先印出定位資訊：

1set -Eeuo pipefail   # -E 讓 ERR trap 在函式/子 shell 也生效
2trap 'log "ERROR line $LINENO: [$BASH_COMMAND] exit=$?"' ERR

$LINENO 是出錯的行號、$BASH_COMMAND 是當下正在執行的那條指令、$? 是它的結束碼。三者合起來，輸出會長這樣：

1[00:06:51] ERROR line 40: [sudo pacman -S --needed stow git zsh] exit=1

範例裡的 pacman 換發行版會不同，這裡只是示意 trap 輸出的格式——手法本身（行號 + 指令 + 結束碼）跟發行版無關。這一行直接點名元兇。前面提過的那類「表面錯誤離真正原因隔好幾層」的情況——例如某個指令因為 which 不存在而拿到空字串、最後報一個看似無關的錯——有了這行，你會直接看到是哪一行的哪條指令掛了，不必從誤導性的症狀往回猜。set -E（-E 旗標）是為了讓 trap 在函式跟子 shell 裡也照樣觸發，少了它，包在函式裡的錯誤會漏掉。

步驟標記：用帶時間戳的 log 函式標出進度

第三個手法是在關鍵步驟前印一行帶時間戳的標記，讓你能看出腳本跑到哪、哪一步慢。一個極簡的 log 函式就夠：

1log() { printf '[%s] %s\n' "$(date +%H:%M:%S)" "$*"; }
2
3log "install.sh start | OS=$OS"
4log "Installing base packages..."
5log "Stowing configs..."

時間戳的價值在於它同時給你「進度」跟「效能」兩種資訊：失敗時，最後一行成功的 log 告訴你它跨過了哪些步驟、卡在哪一步之後；正常時，相鄰兩行的時間差告訴你哪一步耗時最久。這比沒有標記、只能從一堆套件下載輸出裡猜「現在到底在幹嘛」清楚得多。

失敗可診斷是設計目標

把這三個手法合起來，一支原本「失敗時只留一句通用錯誤」的腳本，會變成「每次跑都留一份完整 log、失敗時直接點名第幾行哪個指令、過程中每步都有時間戳」。成本是腳本開頭多幾行，回報是把未來每一次除錯從瞎找變成定位。這層可觀測性是 模組八 bootstrap script 設計 的延伸——那篇給安裝腳本的骨架與套件清單，這篇給它加上失敗時的診斷能力，兩篇處理的是同一支腳本的兩個層面。

這是設計階段的決定，不是事後能補的。當一支沒有可觀測性的腳本在一台陌生機器上失敗，你沒辦法回到過去讓它記錄當時的狀態——資訊在失敗的瞬間就已經流失了。所以「失敗可診斷」要跟功能一起設計進去，把它當成 bootstrap 的基本屬性，而不是出事之後才想加的補丁。

回到系列

這幾篇合起來，是把一台機器從「空的」帶到「能接收 dotfile、且部署過程可診斷」的完整地基：安裝選項判讀 處理 OS 怎麼裝、工具驗證與補足 處理裝完缺什麼、外部連入與無 key bootstrap 處理怎麼連進去把 dotfile 弄進來，這一篇處理當部署失敗時怎麼快速看出原因。再往前一步，把這套地基用在無人值守的長任務上、讓機器在你離開後自己跑完工作，見 讓機器跑無人值守的長任務——無人盯著的任務尤其依賴這篇談的可觀測性。地基打好，後面 模組一到八 的 dotfile 管理才有立足點。

observability 跟 infra 同一套 code、同生命週期

可觀測性是基礎設施的一部分，承擔「讓資源在出事時可被追查」的責任，因此它的建立、變更與銷毀要跟被監控的資源綁在同一個生命週期裡。一個 RDS 實例、一個 Lambda、一個 ECS service 被 IaC 建立時，它的 log group、它的關鍵 metric alarm 應該在同一份 plan 裡一起 apply；這個資源被 destroy 時，對應的 alarm 也一起收掉，不留下對著空資源狂叫的孤兒告警。

把監控外掛在資源之外會製造兩種漂移。第一種是新資源沒有監控：service 透過 PR 加上去了，但 alarm 要某人事後手動進 console 點，於是有些 service 有 alarm、有些沒有，覆蓋率取決於誰記得。第二種是死資源留下殘響：資源砍了但 alarm 還在，半夜對著不存在的 target 噴 INSUFFICIENT_DATA，值班的人學會忽略它，告警疲勞讓真的事故也被一起忽略。兩種漂移的共同根因都是監控跟資源不在同一個 apply 單位裡。

判讀訊號很直接：如果有人能回答「這個服務有沒有 alarm」要去翻 console 而不是讀 code，監控就已經跟資源脫鉤了。修法是把監控宣告收進該資源的 module——模組四（環境分離與模組化）談的模組化在這裡延伸成「每個服務模組自帶它的 observability 宣告」，模組五（核心服務上 IaC）談的每個核心服務也應該在同一個 module 裡帶上自己的 log 與 alarm。

log group 與 retention 設計

Log group 是日誌的歸屬與保存單位，它要回答兩個治理問題：留多久、誰能讀。這兩個問題寫進 IaC 才能稽核，而非依賴 vendor 的隱性預設。許多雲端服務在你沒宣告 log group 時會自動建一個、套上「永久保留」的預設值，於是日誌無限堆積、帳單緩慢長大，而真正敏感的內容反而沒人管控存取。

Retention 是成本、合規與除錯需求的三方取捨。除錯通常只需要近幾天到幾週的熱資料；合規（如稽核軌跡、金流紀錄）可能要求保留數年；而每多留一天就多一天的儲存費。划算的做法是按日誌類型分層：高頻、除錯用的 application log 設短 retention（例如 14 到 30 天），稽核相關的 access log 按合規要求設長期保留，必要時再把冷資料歸檔到更便宜的物件儲存。把這些值寫進 IaC，讓「為什麼這條 log 留 90 天」是一個能在 PR 上被討論的決定。

1resource "aws_cloudwatch_log_group" "api" {
2  name              = "/app/${var.env}/api"
3  retention_in_days = var.env == "prod" ? 30 : 7
4  kms_key_id        = aws_kms_key.logs.arn
5}

「誰能讀」是 retention 之外的另一半，因為 log 經常夾帶 PII、token 或內部結構，讀取權限要跟身分地基一起管。存取控制掛在模組二（身分與憑證地基）建立的 IAM 角色上，加密金鑰則對應模組三、模組七一路延伸的金鑰治理。常見陷阱是 log 在傳輸與儲存都加密了，卻對整個團隊開放讀取，等於把敏感資料攤在所有人面前；read 權限應該縮到值班與稽核需要的最小集合。應用層該怎麼決定哪些欄位根本不該進 log，屬於資料保護的範圍，可往 /backend/07-security-data-protection/ 對齊。

metric 與 alarm 寫進 IaC

Metric 與 alarm 寫進 IaC，目的是讓「資源被建立的同時就帶著它的健康判準」。Alarm 不只是一個閾值，它是一份對「這個資源什麼狀態算不正常」的成文約定：哪條 metric、跨多長的評估窗口、超過什麼值要通知誰。把這份約定寫進 code，它就能被 review、被版本控制、被跨環境複用，而不是散落在某個人腦中或 console 的某個角落。

Alarm 的價值在於它連到動作，而非只是亮一盞燈。一條有用的 alarm 至少要綁定通知去向（on-call 的 SNS topic、PagerDuty、Slack），並寫清楚 INSUFFICIENT_DATA 怎麼處理——資料不足到底算正常還是異常，取決於這條 metric 平常是否持續有資料。閾值設計是訊號與雜訊的取捨：設太敏感會頻繁誤報、養出告警疲勞，設太鈍則錯過真正的劣化。划算的起點是針對「使用者已經受影響」的症狀型 metric 設 alarm（錯誤率、p99 延遲、佇列積壓），而把成因型指標（CPU、記憶體）留作 dashboard 上的診斷線索，避免每個成因都獨立告警。

 1resource "aws_cloudwatch_metric_alarm" "api_5xx" {
 2  alarm_name          = "${var.env}-api-5xx-rate"
 3  comparison_operator = "GreaterThanThreshold"
 4  evaluation_periods  = 3
 5  metric_name         = "5XXError"
 6  namespace           = "AWS/ApiGateway"
 7  period              = 60
 8  statistic           = "Sum"
 9  threshold           = 10
10  treat_missing_data  = "notBreaching"
11  alarm_actions       = [aws_sns_topic.oncall.arn]
12}

判讀訊號是：每次新服務上線都要有人「記得」去加 alarm，代表 alarm 還沒進 module 模板。修法是把基礎告警（錯誤率、延遲、健康檢查失敗）做成服務模組的預設輸出，讓開新服務時 alarm 跟著資源一起生出來，調整閾值才是該服務 owner 的選配。

跟 monitoring 系列的分工：基礎設施訊號 vs 客戶端行為訊號

本模組的可觀測性處理基礎設施訊號，monitoring 系列處理客戶端與業務行為訊號，兩者觀測的對象不同、生命週期也不同，因此分屬不同的 code 與不同的章節。基礎設施訊號是資源層的健康狀態：log group、CPU、佇列深度、5xx 比例、實例存活，它們跟著資源被 IaC 建立與銷毀，回答「這個系統還活著嗎、哪裡壞了」。

客戶端行為訊號則是 SDK、Collector、業務埋點那一層：使用者點了什麼、轉換漏斗、前端錯誤、自訂事件，它們跟著產品功能演進、不跟著基礎設施資源同生共滅，所以放在 /monitoring/。判讀分界的問法是：這個訊號是「資源建立時就該存在」還是「功能開發時才埋」。前者進本模組的 IaC，後者進 monitoring 那層的應用程式碼。兩者在事故排查時會合流——基礎設施 alarm 告訴你哪個資源異常，客戶端訊號告訴你使用者實際受了什麼影響——但它們的擁有者、變更節奏與部署管道不同，混在一起會讓「誰負責這條訊號」變模糊。

收斂成一句判準：資源建立時就該存在的訊號歸本模組的 IaC，功能開發時才埋的客戶端行為訊號歸另一層；各條延伸章節見下方跨分類引用。

章節文章

跨分類引用

• → Monitoring 監控體系：客戶端 SDK / Collector 那層的監控
• → 模組五：核心服務上 IaC：每個核心服務帶自己的 log 與 alarm
• → 模組七：infra 走 PR 流程：observability 變更也走 PR 與自動化護欄
• → backend 模組七：資安與資料保護：哪些欄位不該進 log、PII 處理

• SLI 設計起點：user-journey 而非 system metric
• 量測點選擇：edge / gateway / service / dependency 各自代表什麼
• Ratio metric vs latency percentile：何時用哪種
• Burn rate 訊號：multi-window multi-burn-rate alert
• Error budget 計算所需的 metric 結構
• 跟 4.2 metrics 的分工：4.2 是 counter/gauge/histogram 基礎、4.6 是 SLI 化的設計
• 跟 4.4 dashboard-alert 的分工：4.4 是 alert 規則治理、4.6 是 alert 的訊號源頭
• 反模式

概念定位

SLI 訊號設計是把可靠性目標轉成可量測資料的步驟，責任是讓 SLO 政策建立在使用者旅程與服務結果上。

CPU、memory、queue depth 可以提供系統背景，但 SLI 需要回答的是使用者層面的問題：request 是否成功、回應是否夠快、結果是否正確。SLI 量測的位置跟算式決定了 SLO 反映的是「使用者體驗」還是「基礎設施健康」— 兩者的判讀意義不同。

本章處理的是 metric 到 SLI 的轉換。4.2 定義 counter / gauge / histogram 的基礎型別；本章定義怎麼用這些型別組出代表使用者體驗的 SLI，並設計 burn rate alert 的訊號結構。SLO 政策本身（error budget freeze、release gate 決策）由 6.6 SLO 政策 處理。

SLI 設計起點：User Journey

從使用者操作推導 SLI

SLI 的設計起點是「使用者在做什麼、期待什麼結果」，不是「系統有什麼 metric 可以用」。

一個 checkout 流程的使用者期待：request 成功（不會看到 error page）、回應夠快（不會等超過 3 秒）、結果正確（扣款金額正確）。對應三種 SLI：

• Availability SLI：成功 request 的比例（successful_requests / total_requests）
• Latency SLI：回應時間在閾值內的比例（requests_under_3s / total_requests）
• Correctness SLI：結果正確的比例（需要業務邏輯判定，通常用特定 error code 或 reconciliation 結果）

每個 user journey 不需要三種 SLI 都有。Checkout 的 availability 跟 latency 是核心；correctness 靠事後對帳驗證。搜尋頁面的 latency 比 availability 更關鍵 — 使用者容忍偶發的「搜不到結果」但不容忍 5 秒的載入。

System metric 跟 SLI 的差異

CPU > 90% 不是 SLI — 它是 cause signal。CPU 高但 latency 正常，使用者沒受影響。Disk usage > 85% 也不是 SLI — 它是 capacity signal，需要處理但不代表當下使用者體驗退化。

System metric 的價值在 root cause analysis，不在 SLI。事故中先看 SLI 判斷「使用者是否受影響」，確認受影響後再看 system metric 判斷「原因是什麼」。把 system metric 當 SLI 會讓 SLO 反映基礎設施噪音而非使用者體驗。

量測點選擇

SLI 的量測點影響「看到的是誰的觀點」。同一個 request 在不同位置量測會得到不同的 latency 跟 success rate。

Edge / Load Balancer

最貼近使用者的量測點。量到的 latency 包含 network round-trip + TLS handshake + 所有 backend 處理時間。Availability 反映的是使用者實際看到的 success rate（包含 load balancer 自身的 502/503）。

優點是最能代表使用者體驗。缺點是 load balancer 的 metric 粒度有限 — 通常只有 status code 跟 latency，不帶 service-level 的維度切分。

API Gateway

比 edge 更有應用層上下文。可以按 route / method / tenant 切分 SLI。量到的 latency 不含 network round-trip（已經進入服務網路），但包含 authentication、rate limiting 跟所有下游處理。

API gateway 是多數團隊的 SLI 量測起點 — 粒度足夠、位置夠近使用者、通常已有 instrumentation。

Service level

每個服務的 handler-level metric。可以看到單一服務的 latency 跟 error rate，但不含上下游的影響。適合做 service-level SLO（「order service 的 p99 latency < 200ms」），但不直接代表 user-journey SLO。

Service-level SLI 的價值在於 SLO 階層化 — user-journey SLO 拆分成每個服務的 SLO，事故時能快速定位是哪個服務的 SLO 被打破。

Dependency level

量測外部依賴（database、cache、third-party API）的回應時間跟 error rate。Dependency metric 的角色是 SLI 退化時的歸因訊號，用來追溯因果鏈而非直接代表使用者體驗。Database latency 上升 → service latency 上升 → user-journey latency SLO 被打破 — dependency metric 幫助追溯因果鏈。

SLI 的 Metric 結構

Ratio metric：availability 跟 correctness

Availability SLI 的 metric 結構需要兩個 counter：total requests 跟 successful requests（或 failed requests）。SLI = good / total。

1# Availability SLI
2http_requests_total{service="checkout", status="2xx"} / http_requests_total{service="checkout"}

定義「good」的邊界需要明確。5xx 算 bad，4xx 呢？Client error（400）通常不算服務失敗；authentication failure（401/403）也不算。但 429（rate limit）可能代表服務容量不足，視情境可能算 bad。這個邊界要在 SLI 定義時明確寫下來。

Latency metric：threshold-based ratio

Latency SLI 用 histogram 量測，SLI 值是「在閾值內的 request 比例」。

1# Latency SLI：p99 < 500ms 的比例
2histogram_quantile(0.99, rate(http_request_duration_seconds_bucket{service="checkout"}[5m])) < 0.5
3
4# 或用 ratio 形式
5sum(rate(http_request_duration_seconds_bucket{le="0.5",service="checkout"}[5m]))
6/ sum(rate(http_request_duration_seconds_count{service="checkout"}[5m]))

Latency 閾值的選擇要對齊使用者期待而非系統能力。使用者期待 checkout 在 3 秒內完成 — 這是閾值的來源，不是「系統平均 latency 是 200ms 所以閾值設 500ms」。

Label 設計

SLI metric 的 label 需要足夠的切分能力（by service、by endpoint、by tenant），但受 cardinality 預算約束。

最小 label set：service name + method（GET/POST）+ status class（2xx/4xx/5xx）。這組 label 支撐 service-level SLO 計算。

擴展 label：endpoint path（normalize 後，例如 /api/orders/{id} → /api/orders/:id）、tenant（多租戶場景）。每增加一個 label 維度，series 數量乘法增長 — 在 4.7 cardinality 的 label 白名單中管理。

Burn Rate 與 Multi-window Alert

Burn rate 的概念

Burn rate 是「error budget 被消耗的速度」。Burn rate = 1 代表按 SLO 允許的速度正常消耗；burn rate = 10 代表消耗速度是允許值的 10 倍 — 如果持續下去，error budget 會在 SLO 週期的 1/10 內耗盡。

用 burn rate alert 取代固定閾值 alert 的好處：burn rate 自動適應流量。低流量時段的幾筆 error 可能 burn rate 很低（因為 total 也少、對 error budget 影響小）；高流量時段的相同 error rate 可能 burn rate 很高（因為 total 多、影響的使用者量大）。

Multi-window multi-burn-rate

單一時間窗口的 burn rate alert 會太吵（短窗口）或太晚（長窗口）。Multi-window 策略組合兩者：

14.4x 的來源：若 SLO 週期是 30 天、要在 1 小時內偵測到會耗盡 2% error budget 的問題，burn rate = (30 × 24) / 1 × 0.02 ≈ 14.4。6x 跟 1x 依此邏輯調整消耗比例跟偵測窗口。

短窗口（5min）抓急性：error rate 突然飆高、burn rate 衝到 14.4x。長窗口（1hr）做確認：退化確實持續、排除瞬間 spike。兩個窗口都超過閾值才觸發 alert，減少單一 spike 的 false alarm。

Recording rule 支撐 burn rate 計算

Burn rate 的計算涉及多個時間窗口的 ratio metric。每次 alert evaluate 都重算會給 TSDB 帶來查詢壓力。用 recording rule 把每個窗口的 error ratio 預計算，alert rule 讀 recording rule 的輸出：

1# Recording rule：5 分鐘窗口的 error ratio
2- record: slo:checkout:error_ratio:rate5m
3  expr: sum(rate(http_requests_total{service="checkout",status=~"5.."}[5m]))
4      / sum(rate(http_requests_total{service="checkout"}[5m]))

Alert rule 讀 recording rule 比每次重算 raw series 高效，也讓 burn rate 的計算邏輯集中管理。

Error Budget 的 Metric 結構

Error budget 是 SLO 週期內允許的錯誤量。SLO = 99.9% 代表 30 天內允許 0.1% 的 request 失敗。Error budget = total requests × 0.001。

Error budget 的 metric 結構需要：

• Total requests（rolling window）：過去 30 天的 total request count
• Failed requests（rolling window）：過去 30 天的 failed request count
• Budget consumed：failed / (total × (1 - SLO target))
• Budget remaining：1 - budget consumed

Budget remaining 作為 dashboard panel 跟 release gate 的輸入 — 餘額低於閾值時 freeze deployment。這個計算的 rolling window 用 recording rule 維護，避免每次查詢掃描 30 天的 raw data。

核心判讀

判讀 SLI 設計時，先看量測點是否貼近使用者，再看算式是否能穩定支援 error budget。

重點訊號包括：

• Edge / gateway / service / dependency 的量測點是否各自有清楚責任
• Latency percentile 與 ratio metric 是否對應不同使用者體驗
• Burn rate 是否使用多時間窗，避免太吵或太晚
• SLI label 是否有足夠切分能力，同時受 cardinality 預算約束
• Error budget 的 rolling window 是否用 recording rule 維護

判讀訊號

• Alert 用 system metric（CPU / memory）而非 user-facing 訊號
• Burn rate 只有單窗、噪音多或偵測太晚
• SLI 計算用平均、不用 percentile
• Error budget 算式分母不穩（流量低時誤觸發、高時稀釋）
• SLI 量測點離使用者太遠（內部 service 而非 edge/gateway）
• SLI 沒有定義「什麼算 good request」的邊界（4xx 算不算 bad）
• Burn rate 計算每次重算 raw series、沒有 recording rule

反模式

交接路由

• 4.2 metrics：counter / gauge / histogram 基礎型別
• 4.4 dashboard-alert：burn rate alert 的 noise control 跟 runbook
• 4.7 cardinality / cost：SLI metric 的 cardinality 預算
• 4.10 client-side / RUM：user-journey-centric SLI 的前端訊號來源
• 4.23 觀測查詢設計：recording rule 支撐 burn rate 計算
• 6.6 SLO 政策：error budget 餘額作為 freeze 條件
• 6.8 release gate：burn rate 觸發 freeze
• 8.1 incident severity：burn rate 對應 severity 門檻
• 4.14 anomaly detection：跟 SLO threshold 的訊號分工

觀察

AWS ADOT on EKS 的實務把 metrics、traces 採集策略整合到可管理的 collector pipeline。

判讀

多代理混用雖然能運作，但在規模化時會放大配置漂移與維運成本。

策略

1. 先統一 collector 部署模式。
2. 將 exporter 與 sampling 規則集中管理。
3. 以資料品質指標驗證遷移成效。

下一步路由

回 4.11 telemetry pipeline 與 4.18 observability operating model。

引用源

• AWS Distro for OpenTelemetry on EKS

本章目標

讀完本章後、你應該能：

1. 用 Honeycomb SDK 或 OTel 送 events 到 Honeycomb
2. 用 BubbleUp 找 outlier 模式（unknown-unknowns）
3. 設計 SLO + burn rate alert
4. 配置 Refinery（tail-based sampling）
5. 評估 Honeycomb vs Datadog 的選用判讀

最短路徑：5 分鐘把 Honeycomb 跑起來

1# 1. 應用程式加 instrumentation（Honeycomb SDK 或 OTel SDK）
2# TODO: HONEYCOMB_API_KEY + dataset 設定
3# TODO: 用 Beeline SDK 或 OTel + OTLP exporter
4
5# 2. 送 sample events
6# TODO: 觀察 trace 出現在 Honeycomb UI
7
8# 3. 用 query 介面查詢
9# TODO: SELECT count + visualize by service.name

日常操作與決策形狀

Events vs metrics 心智模型

Honeycomb 跟 metrics-aggregation 平台不同。子議題：

• Event = 一個 trace span（包含 dozens of attributes）
• 不預先 aggregate、查詢時 group by 任意 attribute
• High-cardinality 不是問題、是設計目標
• 對應 4.C2 Gaming peak cardinality

Instrumentation

子議題：

• Honeycomb SDK（Beeline）：簡單、Honeycomb-specific、auto-instrumentation 部分
• OTel SDK + OTLP：標準、vendor-neutral、推薦新部署用
• Manual attribute：對 business / domain context attribute 不省略
• Refinery：tail-based sampling proxy

Query 介面

子議題：

• Visualize：count / count_distinct / heatmap / p50 / p95 / p99
• Group by：任意 attribute（user_id / region / version 等）
• Filter：WHERE clause
• 對應 SLO query：heatmap(duration_ms) GROUP BY service.name WHERE http.status_code = 500

Deep Article

• High-Cardinality Query Model 與 BubbleUp：event-based 資料模型、high-cardinality 查詢設計、BubbleUp 異常偵測、SLO / burn rate、derived columns、dataset 設計與 OTLP ingestion

Migration Playbook

• Sentry 遷移到 Honeycomb：error tracking 轉 event-based observability

進階主題（按需閱讀）

BubbleUp 分析

子議題：

• 給定 heatmap 異常區、自動找區隔 outlier 跟 baseline 的 attribute
• 適合「我看到 latency spike、但不知道哪個維度造成」
• Unknown-unknowns 偵錯模式
• 跟 Datadog APM 的 service map 對照

SLO 與 burn rate alert

子議題：

• SLO 配置（service + indicator + objective + window）
• Burn rate calculation：multi-window multi-burn-rate alert
• 跟 knowledge cards burn-rate 對照
• 對應 4.C9 OTel migration signal drift

Refinery（tail-based sampling）

子議題：

• 為什麼需要 tail-based：保留有錯 / 高延遲 trace、丟正常 trace
• Refinery 部署模式（gateway in front of Honeycomb）
• Sampling rule：error / latency / per-service / dynamic
• 對應成本：100% ingestion 太貴、tail-based 平衡

OTLP integration

子議題：

• Honeycomb 接受 OTLP（gRPC / HTTP）
• 應用層用 OTel SDK、傳給 Honeycomb 不用改 SDK
• Multi-backend 支援：同一份 OTel data 送 Honeycomb + 其他
• 對應 4.C7 Datadog OTel migration

結構化 events 設計

子議題：

• 哪些 attribute 應加（user_id / request_id / business 維度）
• 哪些 attribute 不該加（PII / secrets）
• Wide events 哲學：一個 event 帶 dozens of attributes、不分散到多 metric
• 對應 PII redaction strategy

Observability-driven development

子議題：

• Charity Majors 提的 SDLC 模式：production debug 是常態
• TDD + observability：寫 code 同時思考可觀測性
• 跟 SRE 文化整合

排錯快速判讀

Events 沒到 Honeycomb

操作原則：先看 SDK 配置（API key + dataset）、再看 network、最後看 Honeycomb status page。

Query timeout

操作原則：query window 過大或 attribute cardinality 過高造成 backend slow。判讀：縮 time window、簡化 group by。

Sampling 過頭 vs 不足

操作原則：debug 時找不到 trace（sampling 過頭）vs cost 爆（sampling 不足）。Refinery 提供 dynamic sampling 解決靜態 rate 的不足。

Burn rate alert noise

操作原則：multi-window 設計避免「短暫 spike 觸發 alert」、低 burn rate window 給長期趨勢。

跟其他 backend dual ship 不一致

對應 4.C9 OTel migration signal drift。判讀：兩個 backend 數據不對齊、看 SDK 是否 dual export、attribute mapping 是否一致。

何時改走其他服務

不在本頁內的主題

• Honeycomb SDK 完整 API
• BubbleUp 內部演算法
• Refinery 詳細配置
• Honeycomb pricing 詳細

案例回寫

直接相關案例

跨 vendor 對照

待補 Honeycomb 案例：Charity Majors 的 production talks、Honeycomb customer engineering blog、Refinery scale-up case。

下一步路由

• 上游概念：4.17 Telemetry Data Quality
• 平行 vendor：OpenTelemetry、Datadog
• 下游能力：06 reliability 模組（SLO / burn rate）、4.20 Evidence Package

當 44 個 Hook 每天執行數百次，你怎麼知道它們運行正常？出了問題你怎麼找到原因？

本章從三個維度建立 Hook 系統的可觀測性：

一、日誌架構設計

1.1 需求分析

Hook 日誌系統和一般應用程式的日誌有兩個根本差異：

這些差異決定了日誌架構的選擇：不需要集中式日誌服務，但需要按 Hook 名稱隔離和按時間自動清理。

1.2 目錄結構設計

 1.claude/hook-logs/
 2├── acceptance-gate-hook/
 3│   ├── acceptance-gate-hook-20260304-091523.log
 4│   ├── acceptance-gate-hook-20260304-091845.log
 5│   └── .cleanup_trigger           # 清理觸發計數器
 6├── command-entrance-gate-hook/
 7│   ├── command-entrance-gate-hook-20260304-091523.log
 8│   └── ...
 9└── phase-completion-gate-hook/
10    └── ...

每個 Hook 有獨立的日誌目錄。每次執行產生一個獨立的日誌檔案，檔名包含時間戳。這個設計的好處：

• 隔離性：排查問題時只需看特定 Hook 的目錄
• 時間線：按檔名排序就能看到執行歷史
• 清理：按目錄或按時間清理都很容易

1.3 日誌系統初始化

 1def setup_hook_logging(hook_name: str) -> logging.Logger:
 2    """建立並設定 Hook 日誌系統"""
 3    if not hook_name:
 4        hook_name = DEFAULT_HOOK_NAME
 5
 6    sanitized_name = _sanitize_hook_name(hook_name)
 7    root_dir = _find_project_root()
 8    log_base_dir = root_dir / ".claude" / "hook-logs" / sanitized_name
 9
10    # 建立日誌目錄（失敗時降級，不拋出異常）
11    try:
12        log_base_dir.mkdir(parents=True, exist_ok=True)
13    except OSError:
14        return _create_fallback_logger(hook_name)
15
16    logger = logging.getLogger(hook_name)
17    _clear_logger_handlers(logger)
18    logger.setLevel(logging.DEBUG)
19
20    is_debug = os.getenv("HOOK_DEBUG", "").lower() == "true"
21    _setup_logger_handlers(logger, log_base_dir, sanitized_name, is_debug)
22    return logger

這段程式碼有幾個值得注意的設計決策。

Named Logger：使用 logging.getLogger(hook_name) 取得 named logger，而非 root logger。這確保每個 Hook 的日誌設定互不干擾：

1# 每個 Hook 有自己的 logger 實例
2logger_a = logging.getLogger("acceptance-gate-hook")
3logger_b = logging.getLogger("command-entrance-gate-hook")
4# 兩者的 handlers、level、format 完全獨立

Handler 清理：每次初始化前先清除舊的 handlers。這防止同一個 logger 被重複配置（例如在測試中多次呼叫 setup_hook_logging）：

1def _clear_logger_handlers(logger: logging.Logger) -> None:
2    """清除 logger 的所有 handlers"""
3    for handler in logger.handlers[:]:
4        logger.removeHandler(handler)
5        handler.close()

注意 logger.handlers[:] 的切片複製。直接遍歷 logger.handlers 並在迴圈中 removeHandler 會修改列表長度，導致跳過元素。這是 Python 中遍歷時修改集合的經典陷阱。

環境變數控制：透過 HOOK_DEBUG 環境變數切換日誌詳細程度，不需要修改程式碼：

1# 正常模式：stdout 只顯示 WARNING 以上
2python3 my-hook.py
3
4# 除錯模式：stdout 顯示所有等級
5HOOK_DEBUG=true python3 my-hook.py

1.4 雙通道輸出

每個 logger 配置兩個 handler，分別負責不同用途：

 1def _setup_logger_handlers(logger, log_base_dir, sanitized_name, is_debug):
 2    """為 logger 配置 handlers"""
 3    # 檔案 handler：記錄所有等級，供事後分析
 4    timestamp = datetime.now().strftime("%Y%m%d-%H%M%S")
 5    log_file_path = log_base_dir / f"{sanitized_name}-{timestamp}.log"
 6    file_handler = _create_file_handler(log_file_path)
 7    if file_handler:
 8        logger.addHandler(file_handler)
 9
10    # 控制台 handler：正常模式只顯示 WARNING+，除錯模式顯示全部
11    logger.addHandler(_create_stream_handler(is_debug))

為什麼 StreamHandler 輸出到 stdout 而非 stderr？這和 Claude Code 的 Hook 系統規則有關：

日誌中的 WARNING 訊息是給開發者的提醒，不是 Hook 執行失敗。如果把 WARNING 輸出到 stderr，Claude Code 會把它當成錯誤。所以 StreamHandler 必須走 stdout。

1.5 Hook 名稱淨化

Hook 名稱會用於檔案系統路徑（目錄名和檔名），所以需要淨化：

 1def _sanitize_hook_name(name: str) -> str:
 2    """淨化 hook 名稱，移除無法用於檔案系統的字元"""
 3    if not name:
 4        return DEFAULT_HOOK_NAME
 5
 6    for char in ["<", ">", "|"]:
 7        name = name.replace(char, "-")
 8    name = name.replace("/", "-").replace("\\", "-")
 9
10    # 合併連續 "-" 並移除前後
11    while "--" in name:
12        name = name.replace("--", "-")
13    name = name.strip("-")
14
15    return name if name else DEFAULT_HOOK_NAME

這是防禦性程式設計的典型例子。雖然目前所有 Hook 的名稱都是合法的檔案名（像 acceptance-gate-hook），但不能假設呼叫端一定傳入合法名稱。淨化函式確保即使傳入 <invalid|name> 也能產生合法的目錄名 invalid-name。

1.6 專案根目錄定位

日誌目錄在專案根目錄下的 .claude/hook-logs/。但 Hook 可能從不同的工作目錄被執行，所以需要動態定位：

 1def _find_project_root() -> Path:
 2    """查詢專案根目錄
 3
 4    優先順序：
 5    1. 環境變數 CLAUDE_PROJECT_DIR
 6    2. 從 cwd 向上搜尋 CLAUDE.md（最多 5 層）
 7    3. os.getcwd() fallback（永不失敗）
 8    """
 9    env_dir = os.getenv("CLAUDE_PROJECT_DIR")
10    if env_dir:
11        return Path(env_dir)
12
13    current_dir = Path.cwd()
14    for _ in range(CLAUDE_MD_SEARCH_DEPTH):
15        if (current_dir / "CLAUDE.md").exists():
16            return current_dir
17        parent = current_dir.parent
18        if parent == current_dir:
19            break
20        current_dir = parent
21
22    return Path.cwd()

三層 fallback 的設計邏輯：

注意搜尋深度限制 CLAUDE_MD_SEARCH_DEPTH = 5。不做深度限制的話，在 / 目錄執行時會遍歷整個檔案系統。5 層足以覆蓋大多數專案結構（/Users/user/projects/my-app/.claude/hooks/ 需要 4 層）。

二、錯誤可見性設計

2.1 核心問題：靜默失敗

IMP-003 事件是錯誤可見性設計的直接動機。7 個 Hook 因為變數作用域問題（NameError）靜默失敗了至少 2 個 session。失敗的流程是：

1Hook 執行 → NameError → run_hook_safely 捕獲 → 寫入日誌檔案 → 返回 EXIT_ERROR
2                                                    ↑
3                                              用戶看不到這裡

問題出在 _log_exception 的初版只寫入日誌檔案：

1# W25-005 之前的版本（有缺陷）
2def _log_exception(logger, hook_name, tb_str):
3    logger.critical(f"Unhandled exception in {hook_name}")
4    logger.critical(tb_str)
5    # 到這裡就結束了 -- 用戶完全不知道出錯

2.2 修正：stderr 強制可見

W25-005 在日誌寫入之後加了一行 stderr 輸出：

 1def _log_exception(logger, hook_name, tb_str):
 2    """記錄異常 traceback 到日誌"""
 3    # 1. 寫入日誌檔案（完整 traceback，供事後分析）
 4    try:
 5        logger.critical(f"Unhandled exception in {hook_name}")
 6        logger.critical(tb_str)
 7    except Exception as logging_error:
 8        # 日誌系統本身也可能失敗（磁碟滿了、權限問題）
 9        print(f"Failed to log exception: {logging_error}", file=sys.stdout)
10        print(tb_str, file=sys.stdout)
11
12    # 2. 輸出到 stderr，讓 Claude Code 顯示 "hook error"（W25-005 新增）
13    print(
14        f"[Hook Error] {hook_name} failed unexpectedly. "
15        f"Check hook logs for details.",
16        file=sys.stderr
17    )

這個設計的關鍵在於兩層輸出各司其職：

為什麼不把完整 traceback 輸出到 stderr？ 因為 stderr 的內容會直接顯示在 Claude Code 的對話介面中。一段 20 行的 Python traceback 對用戶來說是噪音。只需要告訴用戶「哪個 Hook 出錯了」和「去哪裡看詳情」就夠了。

2.3 日誌系統自身的 Fallback

如果日誌系統本身出了問題（例如磁碟已滿，無法寫入日誌檔案），怎麼辦？

 1# 目錄建立失敗時的 Fallback
 2try:
 3    log_base_dir.mkdir(parents=True, exist_ok=True)
 4except OSError:
 5    return _create_fallback_logger(hook_name)  # 降級為純 stdout 輸出
 6
 7def _create_fallback_logger(hook_name: str) -> logging.Logger:
 8    """建立 Fallback Logger（僅 StreamHandler）"""
 9    logger = logging.getLogger(hook_name)
10    _clear_logger_handlers(logger)
11    logger.setLevel(logging.DEBUG)
12    logger.addHandler(_create_stream_handler())
13    return logger

Fallback Logger 只有 StreamHandler（stdout），沒有 FileHandler。這表示日誌不會被儲存到檔案，但至少 Hook 能正常運行，而且重要訊息仍然會出現在控制台。

這體現了一個重要的設計原則：可觀測性基礎設施的故障不應該導致業務功能中斷。日誌系統壞了，Hook 仍然要能工作。

2.4 IMP-005 的教訓：Import 階段的可見性

IMP-005 暴露了另一個可見性盲區：import 階段的錯誤。當模組遷移後 import 路徑沒更新，ModuleNotFoundError 在 run_hook_safely 之前就發生了：

 1#!/usr/bin/env python3
 2import sys
 3from pathlib import Path
 4
 5# 這一行在 run_hook_safely 之前執行
 6# 如果失敗，run_hook_safely 根本不會被呼叫
 7from lib.common_functions import hook_output  # ModuleNotFoundError!
 8
 9from hook_utils import run_hook_safely
10
11def main() -> int:
12    # ...
13    return 0
14
15if __name__ == "__main__":
16    sys.exit(run_hook_safely(main, "my-hook"))

run_hook_safely 的保護範圍是 main() 函式內部，但 import 發生在模組載入階段。解決方案是在 import 處加入 try-except 防護：

 1#!/usr/bin/env python3
 2import sys
 3from pathlib import Path
 4
 5# Import 防護：確保失敗時有明確的 stderr 輸出
 6try:
 7    sys.path.insert(0, str(Path(__file__).parent))
 8    from hook_utils import run_hook_safely
 9    from lib.common_functions import hook_output
10except ImportError as e:
11    print(f"[Hook Import Error] {Path(__file__).name}: {e}", file=sys.stderr)
12    sys.exit(1)

2.5 IMP-006 的教訓：兩條錯誤路徑

IMP-006 案例 D 揭示了一個更隱蔽的問題：Hook 有兩條不同的「失敗路徑」，但只有一條有 stderr 輸出。

 1def main() -> int:
 2    # ...驗證邏輯...
 3
 4    if should_block:
 5        # 路徑 1：業務邏輯拒絕（有意阻止）
 6        result = {"error": error_message}
 7        print(json.dumps(result), file=sys.stdout)
 8        return 2  # 只有 stdout，沒有 stderr！
 9
10    return 0
11
12# run_hook_safely 包裝
13# 路徑 2：未預期異常 -- _log_exception 已有 stderr 輸出

開發者只考慮了「未預期異常」這條路徑（由 _log_exception 處理），忘了「有意阻止」也需要 stderr 輸出。修復：

1if should_block:
2    result = {"error": error_message}
3    print(json.dumps(result), file=sys.stdout)
4    # 新增：確保用戶在 Claude Code UI 能看到拒絕原因
5    print(f"[Agent Ticket Validation] blocked: {error_message}", file=sys.stderr)
6    return 2