三段式規則結構

每條規則由三部分組成：條件（什麼事件觸發）、動作（觸發後做什麼）、模板（動作的內容格式）。

條件

條件定義「哪些事件匹配這條規則」。條件是事件欄位的過濾器 — 事件類型、事件名稱、屬性值的比較。

1{
2  "condition": {
3    "type": "error",
4    "name": "terminal.connect.*",
5    "severity": "fatal"
6  }
7}

條件支援的匹配方式：

• 精確匹配："type": "error" — 事件類型必須是 error
• 前綴匹配："name": "terminal.connect.*" — 事件名稱以 terminal.connect. 開頭
• 數值比較："data.duration_ms": { "gt": 5000 } — 持續時間超過 5 秒
• 組合條件：多個欄位條件同時滿足（AND 邏輯）

動作

動作定義「條件匹配後做什麼」。常見的動作類型：

通知：發送訊息到指定管道（email、Slack webhook、Telegram bot、桌面通知）。

寫 summary：把匹配的事件摘要寫入 summary 檔案，供定期 review。和逐筆事件不同，summary 是聚合後的結果（例如「過去一小時有 15 個 terminal.connect.failed」）。

觸發 webhook：向外部 URL 發送 HTTP POST，讓其他系統可以接收事件並做進一步處理。

執行腳本：在 collector server 上執行預定義的 shell script。適合自動化回應（重啟服務、清理暫存檔、輪替 log）。執行腳本的安全風險需要控制 — 只允許白名單內的腳本。

模板

模板定義動作的內容格式。通知的訊息內容、webhook 的 request body — 用模板語法（Go template 或 mustache）把事件欄位填入。

1{{ .name }} 發生於 {{ .ts }}
2嚴重度：{{ .data.severity }}
3訊息：{{ .data.message }}

模板讓同一個動作類型適用不同的事件 — 不需要為每種事件寫不同的通知函式。

規則評估時機

即時評估

每個事件寫入後立即評估所有規則。適合需要即時回應的規則（fatal error 通知）。

即時評估的成本和規則數量成正比 — 100 條規則代表每個事件寫入後做 100 次條件匹配。規則數量在數十條以內時，評估時間可以忽略。

批次評估

定期（每分鐘、每小時）掃描一段時間內的事件，評估聚合類規則。適合基於統計的規則（「過去 5 分鐘 error 數量超過 10」「過去 1 小時某 endpoint 的 P95 回應時間超過 2 秒」）。

批次評估需要時間窗口的概念 — 規則條件中包含時間範圍和聚合函式（count、avg、max、percentile）。

混合策略

即時評估用於單一事件觸發的規則（fatal error → 立即通知），批次評估用於聚合觸發的規則（error rate 異常 → 定期檢查）。兩者可以共存。

規則管理

規則以 JSON 或 YAML 檔案儲存在 collector 的設定目錄中。新增、修改、刪除規則是編輯檔案 + 重新載入 collector（signal 或 API call）。

1rules:
2  - name: fatal-error-notify
3    condition:
4      type: error
5      data.severity: fatal
6    action:
7      type: slack
8      webhook: https://hooks.slack.com/...
9      template: "FATAL: {{ .name }} at {{ .ts }}"

規則檔案版本控制在 git 中，和 collector 的其他設定一起管理。規則變更歷史可追溯。

Shell 執行的安全邊界

Rule engine 的「執行腳本」動作在 collector 主機上執行 shell command。這個能力和 collector 的認證狀態組合後產生不同的風險等級。

攻擊鏈

無認證模式下，攻擊者可以向 collector 的 /v1/events endpoint 注入偽造事件。如果偽造事件匹配了一條規則、且規則的動作是執行 free-form shell command，攻擊者等於取得了 collector 主機的命令執行權（RCE — Remote Code Execution）。

攻擊路徑：注入假事件 → 匹配 rule → 執行 shell → RCE。

防護措施

Rule 定義不可透過 API 新增。Rule 只能由管理員透過配置檔或 CLI 設定，collector 的 HTTP API 不提供 rule CRUD endpoint。攻擊者即使能注入事件也無法新增 rule — 但現有 rule 的條件如果太寬（例如 type: error 沒有進一步限定 name），偽造的 error 事件仍可能匹配。

Shell command 使用 allowlist。Rule 的 action 指定 command name（如 restart-ttyd），command 的實際路徑在配置檔的 allowlist 中定義。Rule 不接受 free-form shell string（如 sh -c "rm -rf /"）。

 1# 配置檔
 2allowed_commands:
 3  restart-ttyd: /usr/local/bin/restart-ttyd.sh
 4  notify-slack: /usr/local/bin/notify-slack.sh
 5
 6rules:
 7  - name: fatal-error-response
 8    condition:
 9      type: error
10      data.severity: fatal
11    action:
12      type: command
13      command: restart-ttyd  # 只接受 allowlist 中的 name

無認證模式下的額外限制。Collector 無認證時（同區網信任），建議禁用 command 類型的動作、只允許通知和 webhook。認證啟用後才解鎖 command 動作 — 認證確保只有授權的 SDK 實例能送事件，降低偽造事件觸發 rule 的風險。

下一步路由

• Collector 的完整架構 → Collector 架構
• 規模成長後的演進路徑 → 規模演進
• 事件的分類和命名 → 監控心智模型 四類事件
• Rule engine 在偽造流量偵測的應用 → Client-side SDK 認證

理解這個框架後，監控就不是「裝一套很重的東西」，而是分層選擇：從 systemd 內建的失敗鉤子（不裝任何額外服務），到推播管道，到「整台機器死掉」的體外心跳，到完整的指標儀表板。多數人只需要前一兩層。

你現在手動在做的事（要被取代的基線）

在自動化之前，先認清手動版本——這也是所有告警底層讀的同一個權威來源：

1systemctl --failed          # 現在有哪些 unit 處於 failed（開機後系統怪怪的先掃這個）
2systemctl is-failed <unit>  # 單一 unit 明確判失敗（比 is-active 直接）
3journalctl -u <unit> -f     # 即時跟一個 unit 的 log

systemctl --failed 就是「服務死活」的權威清單。手動版的問題不是不準，是你得記得去看。下面每一層都是把「記得去看」換成「壞了它來找你」。

第一層：systemd 原生 OnFailure 鉤子（不裝額外服務）

systemd 每個 unit 進入 failed 狀態時，可以自動觸發另一個 unit。這是最正統、零額外依賴的做法——告警邏輯就寫成一個普通的 systemd service。它由三塊組成：一個負責送通知的處理器 unit、一個實際送出的腳本、以及在你要監控的 unit 上掛一行 OnFailure=。

通知處理器是一個 template unit（@ 表示可帶參數），參數 %i 會是失敗的那個 unit 名：

1# /etc/systemd/system/alert@.service
2[Unit]
3Description=Alert on failure of %i
4[Service]
5Type=oneshot
6ExecStart=/usr/local/bin/notify-failure %i

送出腳本負責把「哪個 unit、在哪台機、什麼時候」推出去。這裡有個實測踩到的坑：在 systemd service 的執行環境下，hostname 指令可能回傳空字串，要改用 uname -n 或讀 /etc/hostname 才穩：

 1#!/bin/bash
 2# /usr/local/bin/notify-failure   （記得 chmod +x）
 3unit="$1"
 4# 只在「真正放棄」時告警：OnFailure 每次失敗都觸發（含 auto-restart 中途，見下節實測），
 5# auto-restart 中途 ActiveState 是 activating、撞重試上限才進 failed。gate 掉中途避免洗告警。
 6state="$(systemctl show "$unit" -p ActiveState --value)"
 7[ "$state" = failed ] || exit 0
 8host="$(uname -n)"                     # 不要用 hostname，systemd 環境下可能回空
 9ts="$(date -Is)"
10topic="你的私密topic"
11curl -fsS \
12  -H "Title: $host: $unit failed" \
13  -d "$unit 於 $ts 進入 failed" \
14  "https://ntfy.sh/$topic"

在要監控的 unit 掛上鉤子。針對單一 unit，加一行：

1[Unit]
2OnFailure=alert@%n.service    # %n 是本 unit 的全名，會展開成 alert@<本unit>.service

要一次套用到所有 service，用 top-level drop-in（放在 service.d/ 這個型別目錄下的設定會套用到每個 .service）：

1# /etc/systemd/system/service.d/onfailure.conf
2[Unit]
3OnFailure=alert@%n.service

改完 sudo systemctl daemon-reload。一個必須注意的遞迴陷阱：全域 drop-in 也會套到 alert@ 自己，它若失敗會觸發自己。給 alert@.service 一個清空 OnFailure= 的 override（[Unit] 段寫 OnFailure=）擋掉。

這條鏈是實測驗證過的：故意讓一個 ExecStart=/bin/false 的測試 service 失敗，systemd log 出現 Triggering OnFailure= dependencies、alert@ 處理器被觸發跑完、curl 推到 ntfy 回 HTTP 200——通知確實送出，全程沒有肉眼介入。

先自動重啟、放棄了才吵你

多數暫時性失敗（一次連線抖動、一個 race）自己重試就好，不值得半夜叫醒你。把「自動復原」跟「告警」分兩段：讓 systemd 先重啟幾次，撐過重試上限才真的算放棄。

1[Service]
2Restart=on-failure
3RestartSec=5
4[Unit]
5StartLimitBurst=3          # 重試 3 次
6StartLimitIntervalSec=60   # 60 秒內都失敗才進 failed（start-limit-hit）

這裡有個實測踩到、跟直覺相反的坑：OnFailure 不是「放棄才觸發」，而是每一次失敗都觸發——包含 Restart=on-failure 的每次 auto-restart 中途。實測一個反覆 crash 的服務（重試 3 次後放棄）觸發了 4 次 OnFailure（3 次 auto-restart + 1 次最終 start-limit-hit）。所以只靠 Restart= + StartLimit= 這段 config，你會被每次瞬斷洗告警。

真正做到「只在放棄才吵」，靠的是上面送出腳本開頭那道 gate：systemctl show <unit> -p ActiveState 在 auto-restart 中途是 activating、撞上限進 failed 才是 failed，腳本只在 failed 才送。加上 gate 後同一個 crash 測試從 4 次告警降到 1 次（只剩最終放棄那次）。config 負責「重試幾次」，handler 的 gate 負責「只在終局告警」——兩段合起來才是完整的「先重啟、放棄才吵」。

抓「進程活著但沒在做事」：外部健康探針

OnFailure 抓的是「進程狀態變了」——crash、exit、被 kill。但服務可能進程還在、卻沒在做事：hung、deadlock、內部子系統壞掉。這種 systemd 看它還 active、不會觸發任何告警——正是「進程活著 ≠ 在運作」那條，搬到監控場景。

要抓這種，得從外面主動戳它、看它回不回應：一個 timer 定時對服務發一個健康請求（HTTP 服務就 curl 它的 /health）並設逾時；戳不動、逾時失敗，就讓「那個檢查」自己 failed，一樣走 OnFailure 告警。

1# health-check.service（oneshot）+ 一個每 2 分鐘跑的 .timer
2[Service]
3Type=oneshot
4ExecStart=/usr/bin/curl -fsS --max-time 5 http://127.0.0.1:8899/health

實測對照最清楚：讓一個健康服務卡在 sleep（進程還在、單執行緒不再回應），systemctl is-active 仍顯示 active——systemd 沒察覺；但這個外部探針 curl /health 5 秒逾時、check 失敗、告警發出。systemd 抓進程死、外部探針抓進程活著但 hung，兩層互補、缺一漏一種。

canary：先證明告警管線本身是好的

監控最怕的失效模式是「出事時才發現它早就不會叫了」。防這個的辦法是養一隻 canary——一個你可控的假服務，專門用來確認整條管線是活的。它一物兩用：

• 驗證管線：故意弄掛它，看「失敗 → OnFailure → 推送」真的一路通到你手機，不必拿 sshd 這種真服務去冒險。
• 當活性訊號：它自己若無故失敗告警，等於告訴你告警系統本身還在運作。

做法是一個極簡 HTTP 服務（stdlib 就夠、不必框架），留幾個測試入口：/health 正常回、/crash 故意退出（測 OnFailure）、/hang 進程活著但不回應（測外部探針）。這樣任何時候都能一鍵重驗監控沒有默默失效。

第二層：推去哪裡（關鍵是能離開這台機器）

處理器腳本裡那一段 curl 可以換成任何管道：

• ntfy（ntfy.sh 或自架）：一行 curl 推到手機，最省事，上面的例子就是。它怎麼運作、公共站 vs 自架、以及「topic 名稱就是唯一的密碼」這個安全模型，見 ntfy：推送通知服務。
• email：要先設好一個 MTA（如 msmtp），腳本改成 mail / sendmail。
• Telegram bot、Apprise（一個工具打多個目標）等。

判準只有一條：告警要送到機器外。送桌面 notify-send 只有你正盯著螢幕時才有用；送手機或 email，離開座位、人在外面也收得到。一台跑正事的機器，告警管道應該落在它之外。

第三層：整台機器死掉怎麼辦（監控自己的盲點）

OnFailure 有個根本限制：它靠 systemd 觸發，機器整台掛了（當機、斷電、kernel panic），systemd 自己都沒了，發不出任何告警。 這是所有「機器自己監控自己」方案的共同盲點——它報得了服務的死，報不了自己這台的死。

覆蓋這一層要反過來做：讓機器定時對一個體外的服務「報平安」，平安訊號一停，由那個體外服務替你告警。這叫 dead-man’s switch（心跳監控）。

1# /etc/systemd/system/heartbeat.service
2[Service]
3Type=oneshot
4ExecStart=curl -fsS https://hc-ping.com/<你的-uuid>
5# 搭配一個 heartbeat.timer，OnUnitActiveSec=5min 定時打

心跳超過設定時間沒到，healthchecks.io（或自架的 Uptime Kuma）就通知你。體內的監控管不了自己這台的死亡，一定要有體外的一隻眼睛——這跟本系列 機器連不到或起不來 是同一個問題的兩面：那篇是機器已經不回應時從外面怎麼查，心跳是讓「不回應」這件事本身自動觸發告警。

第四層：要指標、趨勢、門檻（不只是 up/down）

當你要的不只是「掛了沒」，而是 CPU、記憶體、磁碟、延遲的趨勢與門檻告警（例如磁碟用量超過 80% 就先警告，接上本系列反覆出現的「磁碟滿連鎖」），就進到完整監控堆疊：

這一層不是每個人都需要。單機、只想知道某個服務死活，第一層就夠；要看趨勢、跨機、設門檻，才值得付這層的設定與維運成本。

先確認有沒有，沒有就從最簡單開始

監控最好在出事之前就建好，不是等第一次沒人發現的當機才想到。有兩個時機該主動確認這台機器有沒有在監控自己：裝好一台新機器時，跟發現自己反覆在除同一個服務的失敗時。確認的方式就是讀權威狀態：

1systemctl --failed                      # 現在有沒有 failed 的
2systemctl show sshd -p OnFailure        # 關鍵服務有沒有掛告警鉤子

沒有任何監控的話，從最簡單那層開始建，別一開始就上重的：第一層的 OnFailure + ntfy 就能讓「服務掛了」主動找上你，零額外 daemon、幾個檔案就設好。遠端機器至少把 sshd 掛上——它掛了你就失聯，是最該先監控的一個。等你真的需要趨勢圖、跨機、或告警內容不能經過第三方時，再往自架 ntfy（帳號 + ACL）跟完整監控堆疊爬。多數單機、個人用的情境，停在第一層就夠。

依情境選

把上面四層對回你實際要監控的東西：

• 某個 service 掛了想被通知 → 第一層 OnFailure drop-in + ntfy。不裝額外 daemon，最貼近 systemd。
• 希望先自動重啟、救不回來才告警 → 第一層再加 Restart=on-failure + StartLimit*。
• 怕整台機器當掉沒人知道 → 第三層心跳 / dead-man switch。這層體內方案覆蓋不到，必須體外。
• 要看資源趨勢、跨多台、設門檻告警 → 第四層，單機用 Netdata、多機用 Prometheus 堆疊。

判準是先分清你要監控的層級：單一 service 的死活、整台機器的死活、還是資源的趨勢——三種對應不同層，別拿其中一種去蓋另一種。最常見的誤區是以為體內的 OnFailure 能報自己這台的當機，那正是它的盲點。

下一步

• 告警把你叫來之後，怎麼判那個服務到底是什麼狀態（failed、restart loop、還是活著但子系統 wedged）→ 程序、服務與狀態怎麼判。
• 機器完全不回應、心跳斷掉之後從外面怎麼查 → 機器連不到或起不來。
• 底層那套「讀權威狀態、不靠肉眼猜」的判讀紀律 → 診斷心法。

五種查詢場景各自需要不同的事件類型、欄位和查詢模式。每種場景的查詢模式也決定了需要 SQLite 層還是 PostgreSQL 層（見 功能分層與 Backend 選擇）。

Debug 查詢

Debug 查詢回答「問題出在哪」。觸發時機是使用者回報問題或 error alert 觸發後，開發者需要還原問題的 context。

查詢場景

剛才使用者回報的問題

查詢模式：用 session_id 過濾，拉出該 session 的全部事件，按時間排序。

1-- SQLite
2SELECT type, name, ts, data
3FROM events
4WHERE session_id = 'abc-123'
5ORDER BY ts;

需要的事件欄位：session_id（關聯同次使用的事件）、ts（排序）、error 的 stack trace 和 step（定位失敗點）。

這個 error 多常發生

查詢模式：按 error name 分群計數，看時間趨勢。

1-- SQLite
2SELECT name, COUNT(*) as count,
3       strftime('%Y-%m-%d', ts) as day
4FROM events
5WHERE type = 'error'
6  AND ts >= datetime('now', '-7 days')
7GROUP BY name, day
8ORDER BY day, count DESC;

需要的事件欄位：type=‘error’、name（分群鍵）、ts（時間分桶）。

需要的事件

Alerting 查詢

Alerting 查詢回答「需要注意嗎」。分兩種機制：rule engine 的即時評估（事件到達時逐筆比對規則）和事後查詢的趨勢分析。

查詢場景

Error 數量突然上升

查詢模式：最近 1 小時的 error 計數 vs 前一天同時段，偏差超過閾值則告警。

1-- SQLite
2SELECT COUNT(*) as recent_count
3FROM events
4WHERE type = 'error'
5  AND ts >= datetime('now', '-1 hour');

Rule engine 的即時版：每收到一筆 error 事件，遞增計數器，計數器超過閾值觸發動作。

特定 error 首次出現

查詢模式：收到 error 時查是否有歷史記錄。

1-- SQLite
2SELECT COUNT(*) FROM events
3WHERE type = 'error' AND name = ?
4  AND ts < ?;

結果為 0 代表首次出現 — 觸發「新 error 類型」告警。Sentry 的核心功能之一就是這個查詢。

Rule engine vs 事後查詢

Rule engine 逐筆評估，延遲在毫秒級，適合「error 出現就通知」。事後查詢用 SQL 聚合，延遲在秒到分鐘級，適合「過去一小時的 error 趨勢」。兩者互補 — rule engine 做即時告警、SQL 查詢做事後分析。

需要的事件

產品決策查詢

產品決策查詢回答「使用者怎麼用產品」。從簡單的功能使用率到複雜的 funnel 分析。

查詢場景

新功能有多少人用

查詢模式：按 event name 計數。SQLite 層即可。

1-- SQLite
2SELECT name, COUNT(*) as count,
3       COUNT(DISTINCT session_id) as unique_sessions
4FROM events
5WHERE type = 'event'
6  AND name LIKE 'new_feature.%'
7  AND ts >= datetime('now', '-7 days')
8GROUP BY name;

註冊流程在哪流失

查詢模式：session 級 funnel JOIN。需要 PostgreSQL 層。

 1-- PostgreSQL
 2WITH session_steps AS (
 3  SELECT session_id, name,
 4         ROW_NUMBER() OVER (PARTITION BY session_id ORDER BY ts) as step_order
 5  FROM events
 6  WHERE name IN ('signup.start', 'signup.email', 'signup.verify', 'signup.complete')
 7    AND ts >= NOW() - INTERVAL '30 days'
 8)
 9SELECT name, COUNT(DISTINCT session_id) as sessions
10FROM session_steps
11GROUP BY name
12ORDER BY MIN(step_order);

完整的 funnel 分析方法論見 從 collector 資料做基礎 funnel 分析。

需要的事件

安全審計查詢

安全審計查詢回答「有沒有非預期的存取」。重點是偵測異常模式而非單筆事件。

查詢場景

有沒有異常登入

查詢模式：auth 失敗事件按 session 分群計數，短時間內大量失敗 = 暴力破解嘗試。

1-- SQLite
2SELECT session_id, COUNT(*) as fail_count,
3       MIN(ts) as first_attempt, MAX(ts) as last_attempt
4FROM events
5WHERE type = 'error' AND name = 'auth.login.failed'
6  AND ts >= datetime('now', '-1 hour')
7GROUP BY session_id
8HAVING fail_count > 5;

誰存取了什麼敏感資料

查詢模式：敏感操作的 audit trail — 按時間列出所有敏感操作事件。

1-- SQLite
2SELECT ts, session_id, name, data
3FROM events
4WHERE type = 'event'
5  AND name IN ('data.export', 'admin.user_lookup', 'config.secret_read')
6ORDER BY ts DESC;

需要的事件

安全事件的取樣率必須是 1.0（全收）— 取樣會讓攻擊嘗試在統計上隱形。見 感測器生命週期管理 的取樣率設計段。

效能查詢

效能查詢回答「系統有多快」和「哪裡變慢了」。

查詢場景

P95 回應時間趨勢

查詢模式：時間分桶 + percentile 聚合。需要 PostgreSQL 層。

1-- PostgreSQL
2SELECT date_trunc('hour', ts) as hour,
3       percentile_cont(0.95) WITHIN GROUP (ORDER BY (data->>'duration_ms')::int) as p95
4FROM events
5WHERE type = 'metric' AND name = 'api.response.duration'
6  AND ts >= NOW() - INTERVAL '7 days'
7GROUP BY hour
8ORDER BY hour;

SQLite 沒有內建 percentile 函數。SQLite 層的替代方案是排序後取第 95% 位置的值，但在大資料量時效能差。

哪個版本變慢了

查詢模式：按 source.version 分群比較效能。

1-- SQLite / PostgreSQL
2SELECT source_version, AVG((data->>'duration_ms')::int) as avg_ms,
3       COUNT(*) as sample_count
4FROM events
5WHERE type = 'metric' AND name = 'api.response.duration'
6  AND ts >= datetime('now', '-7 days')
7GROUP BY source_version;

需要的事件

查詢 → 事件反推表

設計事件時用這張表反向確認：每種查詢場景需要什麼事件、什麼欄位、什麼 storage 層級。

這張表和 事件枚舉與補齊檢查 的事件表互補 — 事件枚舉從操作端正向推導「要收什麼」，本表從查詢端反向確認「收的夠不夠」。

下一步路由

• 從操作端正向推導事件 → 事件枚舉與補齊檢查
• 動機和事件的對應關係 → 動機驅動的事件設計
• SQLite vs PostgreSQL 的查詢能力分界 → 功能分層與 Backend 選擇
• Rule engine 的即時評估 → Rule engine 設計

使用模式是混合型：平時靠告警被動通知，收到通知後到 dashboard 查看細節。日常監控視圖提供「一眼確認系統正常」的能力，告警觸發視圖提供「出事了去哪裡查」的排障路徑。

日常監控視圖

服務狀態卡

一個狀態卡顯示 collector 的存活狀態和各 SDK 實例的最後心跳時間。狀態卡的設計是「綠色代表正常、紅色代表異常」的二元判斷 — 不需要使用者解讀數字。

Collector 存活的判斷依據是 health endpoint 回應。各 SDK 實例的狀態依據是最後一次 sdk.heartbeat 事件的時間 — 超過設定的逾時閾值（預設 10 分鐘）標為離線。

需要的事件：collector.health.check（collector 自身定期產生）、sdk.heartbeat（各 SDK 定期送出）、sdk.init（SDK 啟動時送出、標記上線）。

吞吐量曲線

折線圖顯示過去 24 小時每分鐘收到的事件數量。多個 SDK 實例用不同顏色區分。吞吐量的正常範圍由歷史資料建立基線 — 突然下降代表某個 SDK 停止送資料，突然上升代表 error storm 或重複送出。

需要的事件：collector.ingestion.count（collector 每分鐘記錄收到的事件數，按 source.app 分群）。

儲存用量

磁碟使用率的趨勢圖 + 保留策略的執行狀態。開發者需要知道「磁碟什麼時候會滿」和「purge 有沒有正常跑」。

需要的事件：collector.storage.disk_usage（定期取樣、metric 類型）、collector.storage.purge.completed（每次 purge 完成時記錄清了多少空間）。

SDK 連線列表

表格列出所有已知的 SDK 實例，每行顯示：app 名稱、版本、平台、最後回報時間、最後一次 init 時間。表格按「最後回報時間」排序 — 最久沒回報的在最上面，方便發現異常。

需要的事件：sdk.init（帶 source 完整資訊）、sdk.heartbeat（定期更新最後回報時間）。

Heartbeat 的觸發機制是 flush timer 的副作用 — SDK 的 flush timer 觸發時，如果 buffer 為空且距上次 heartbeat 超過設定間隔（預設 5 分鐘），自動注入一筆 sdk.heartbeat 事件後送出。不需要獨立的 heartbeat timer。App idle 時 heartbeat 仍會送出，dashboard 的 SDK 連線列表因此能偵測 SDK 是否仍存活。

告警觸發視圖

告警由 rule engine 觸發，觸發後開發者進入 dashboard 查看細節。每種告警條件對應一個排障路徑。

Health check 失敗

Collector 的 health endpoint 連續 N 次回應失敗（由外部 uptime check 偵測、如 cron + curl）。

進入 dashboard 後看：最後一次 collector.health.check 的時間和結果、collector 的 stderr log（systemd journal）、process 是否存活。如果 collector 已經掛了，dashboard 本身也不可達 — 這時的排障路徑是 SSH 到主機查 systemd 狀態。

SDK 停止回報

某個 SDK 實例超過逾時閾值沒有送 sdk.heartbeat。可能原因：被監控 app 當掉、網路斷開、SDK 初始化失敗。

進入 dashboard 後看：該 SDK 的最後事件（什麼類型、什麼時間）、最後 sdk.init 的 source 資訊（版本、平台）、同時段其他 SDK 是否正常（區分「單一 SDK 問題」和「collector 端問題」）。

磁碟用量超過閾值

collector.storage.disk_usage 超過 80%。

進入 dashboard 後看：各 backend 的空間佔比（SQLite DB 大小 + 匯出檔大小）、最近一次 purge 的執行時間和清理量、保留策略的設定值。如果 purge 正常執行但空間仍不足，代表事件產生速度超過清理速度 — 需要調整保留策略或擴容磁碟。

事件吞吐量異常下降

每分鐘事件數從正常基線突然下降超過 50%。

進入 dashboard 後看：吞吐量曲線標注「下降起始時間」、SDK 連線列表確認哪些 SDK 在該時間點後停止回報、collector 的 ingestion error log。

需要的事件總表

這些事件是 collector 自身的營運事件，和被監控 app 的事件走同一個 Storage interface 儲存。Collector 同時是事件的生產者和消費者 — collector.ingestion.count 由 collector 自己產生、自己儲存、自己在 dashboard 顯示。

deployment.started / deployment.completed 這兩個 lifecycle event 在 server-side 部署流程中對應 Backend 5.8 Deployment Rollout 的 evidence package——rollout 的每一批切換需要可判讀的部署事件作為證據。自架 collector 場景的部署追蹤規模遠小於 production server-side rollout，但 event schema 設計（timestamp / version / environment / result）可以跟 server-side 的 evidence 欄位對齊，讓未來規模成長時 event 格式不用重新設計。

自動恢復設計

自用工具場景下「凌晨三點 collector 掛了」的處理策略是自動恢復，不需要人介入。

自動恢復後 collector 送出 collector.started 事件，dashboard 的服務狀態卡從紅轉綠。如果連續重啟（10 分鐘內重啟 3 次以上），systemd 的 StartLimitBurst 阻止無限重啟、改為發送告警通知人工介入。

存取控制

Day-one 的 dashboard 預設無認證 — 同區網內的任何裝置都能打開 dashboard URL。這是同區網信任模型的設計選擇，和 collector 的 HTTP endpoint 無認證一致。

風險告知

無認證的 dashboard 暴露以下資訊給同區網的所有裝置：

• DevOps dashboard：SDK 版本、平台、IP、collector 的磁碟用量
• Developer dashboard：error stack trace（可能包含檔案路徑和程式碼片段）、session 回放（使用者操作序列）
• 中台 dashboard：行為事件明細、funnel 轉換率

家用 LAN 的場景下，家裡的其他裝置（IoT、家人的電腦）也能存取這些資訊。

最小防護

Go 的 net/http middleware 可以用幾行程式碼加 basic auth：

 1func basicAuth(next http.Handler, user, pass string) http.Handler {
 2    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 3        u, p, ok := r.BasicAuth()
 4        if !ok || u != user || p != pass {
 5            w.Header().Set("WWW-Authenticate", `Basic realm="monitor"`)
 6            http.Error(w, "Unauthorized", 401)
 7            return
 8        }
 9        next.ServeHTTP(w, r)
10    })
11}

帳密在 collector 的配置檔設定。Day-one 可選（不設就不啟用），但配置檔中應有 commented-out 的範例讓使用者知道這個選項存在。

Tripwire

Collector 暴露到公網或跨網路存取時，dashboard 的認證從可選變成必要。公網上的無認證 dashboard 等於公開了 error stack trace 和行為資料。

下一步路由

• Developer dashboard 設計 → Developer Dashboard 設計
• 中台 dashboard 設計 → 中台 Dashboard 設計
• Rule engine 的告警設計 → Rule engine 設計
• Collector 自我監控的 bootstrapping 問題 → 規模演進
• 服務探活與自動恢復 → DevOps 服務探活

本文是 AWS CloudWatch 的 vendor deep article，深化 overview「Alarm + Composite alarm + EventBridge rule」段。初次接觸 CloudWatch 的讀者建議先讀 CloudWatch 服務頁。

問題情境

CloudWatch Alarm 是 AWS 原生的告警機制，跟 Prometheus Alertmanager 或 Datadog Monitor 的定位相同 — 把 metric 異常轉成可操作通知。CloudWatch Alarm 的特性是跟 AWS 服務深度整合（Auto Scaling、SNS、Lambda、Systems Manager），但告警邏輯表達力比 PromQL alerting rule 弱。Composite Alarm 是 CloudWatch 用來降低 alert noise 的方式，把多個 alarm 的布林組合當成觸發條件。

Metric Alarm 基礎

Alarm 參數

每個 metric alarm 由五個參數決定行為：

Evaluation periods 的意義是「連續 N 個 period 都違反閾值才進入 ALARM 狀態」。設太低（1 個 period）容易 flapping，設太高（10 個 period）會延遲告警。多數場景 3 個 period × 60 秒 = 3 分鐘是合理起點。

Datapoints to Alarm

除了 evaluation periods，CloudWatch 還有 Datapoints to Alarm 參數 — 在 evaluation periods 的窗口中，至少幾個 datapoint 超過閾值就觸發。例如 3 of 5 代表最近 5 個 period 中有 3 個超過閾值就觸發。

這個設計讓告警在有缺失 datapoint 的環境下更穩健。容器重啟、Lambda cold start 或 scrape timeout 都可能造成某些 period 沒有 datapoint，M of N 模式避免因為缺失資料而延遲告警。

Anomaly Detection Alarm

用途

Anomaly Detection alarm 用機器學習模型建立 metric 的 baseline band，metric 偏離 band 就觸發。適合沒有固定閾值的 metric — 例如 request count 在白天高、晚上低，用固定閾值會在晚上誤報或白天漏報。

設定

1aws cloudwatch put-anomaly-detector \
2  --namespace AWS/ApplicationELB \
3  --metric-name RequestCount \
4  --dimensions Name=LoadBalancer,Value=app/my-alb/xxx \
5  --stat Sum

Anomaly Detection 需要至少兩週的歷史資料才能建立可靠 baseline。新服務上線初期先用固定閾值 alarm，等累積足夠資料後再切換。

Band width 控制

Anomaly Detection band 的寬度用標準差倍數控制（預設 2）。band 太窄（1x）容易誤報，太寬（3x）漏報。生產經驗是 API latency 用 2x、batch job duration 用 3x（batch 的自然波動較大）。

Composite Alarm

問題：Alert noise

單一 metric alarm 太多時，on-call 會收到大量相關但重複的通知。一個下游服務故障可能同時觸發 latency alarm、error rate alarm、timeout alarm、queue lag alarm — 都指向同一個根因，但各自通知。

解法：布林組合

Composite Alarm 用布林表達式組合多個 alarm，只在組合條件成立時觸發。

1ALARM("checkout-latency-high")
2AND ALARM("payment-error-rate-high")
3AND NOT ALARM("scheduled-maintenance-window")

這個組合代表：checkout latency 高且 payment error rate 也高，但排除了計畫維護視窗 — 才通知 on-call。

設計原則

Composite Alarm 的設計應該反映事故判讀邏輯，而非機械式組合。三個常見模式：

Symptom + cause 組合：外部症狀（latency 高）加上內部原因（DB connection pool 飽和）同時成立才通知。避免 latency 短暫抖動就告警。

Cross-service correlation：多個服務同時出現異常時觸發「可能是 shared dependency 問題」的 composite alarm。一個服務異常可能是部署問題，多個同時異常更可能是共用依賴（load balancer、DNS、shared database）。

Suppression window：用 maintenance window alarm 做 NOT 條件，在計畫維護期間抑制告警。

限制

• Composite Alarm 最多引用 5 個 child alarm
• 巢狀深度最多 1 層（composite 不能引用另一個 composite）
• Composite Alarm 本身不產生 metric，只做觸發邏輯

超過 5 個 child alarm 時，需要把相關 alarm 先組成一個 composite，再讓上層 composite 引用。但因為不支援巢狀，實際能組合的 alarm 數量有限。複雜告警邏輯需要用 EventBridge rule 搭配 Lambda 處理。

Alarm actions

常見 action 類型

Alarm 進入 ALARM 狀態時可以觸發多種 action：

生產環境通常同時設定 ALARM 跟 OK action — ALARM 時通知 on-call，回到 OK 時自動 resolve incident。忘記設 OK action 會造成 on-call 收到告警但不知道何時恢復。

跟 EventBridge 整合

CloudWatch Alarm 狀態變更會自動送到 EventBridge（事件類型 CloudWatch Alarm State Change）。EventBridge rule 可以做更靈活的路由：

• 根據 alarm name pattern 路由到不同 SNS topic
• 根據 alarm description 中的 severity tag 決定通知管道
• 多個 alarm 同時進入 ALARM 時觸發 incident 建立

EventBridge 的路由能力彌補了 CloudWatch Alarm 本身路由邏輯簡單的限制。

Missing data 處理

四種策略

Alarm evaluation 遇到缺失 datapoint 時，有四種處理方式：

breaching 適合 heartbeat 類型的 metric — 服務應該持續回報 metric，停止回報代表服務掛了。notBreaching 適合流量驅動的 metric — 凌晨沒有 request 時自然沒有 latency datapoint，不應該觸發告警。

選錯 missing data 策略是 alarm flapping 的常見原因。Lambda function 的 metric 在沒有 invocation 時沒有 datapoint，用預設的 missing 或 breaching 都會造成問題。Lambda metric alarm 應該用 notBreaching。

Cross-region 限制

CloudWatch Alarm 跟 metric 綁定在同一個 region。跨 region 告警的兩種方式：

Cross-account observability：monitoring account 可以看到 source account 的 CloudWatch 資料，但 alarm 仍然必須建在 metric 所在的 region。

Custom metric replication：用 Lambda 或 Kinesis 把 metric 從 source region publish 到 central region，在 central region 建立統一 alarm。增加複雜度跟延遲，但能集中管理告警。

多數團隊選擇在每個 region 建各自的 alarm，用統一的 SNS topic（跨 region publish 到 central topic）收斂通知。告警邏輯去中心化，通知管道集中化。

Cost 考量

CloudWatch Alarm 的主要成本來自：

數量控制的判準：每個服務 10-30 個 metric alarm 加 2-5 個 composite alarm 是合理範圍。超過 100 個 alarm 時先檢查是否有冗餘（同一 metric 不同 period 的重複 alarm）。

整合與下一步

• 告警設計原則：alarm 跟 dashboard 的搭配，見 4.4 Dashboard 與 Alert 設計
• SLI/SLO 對齊：把 alarm 閾值跟 SLO 對齊，見 4.6 SLI 量測與 SLO 訊號設計
• Log-based alerting：從 log 產生 metric 再建 alarm，見 CloudWatch Logs Insights 查詢與日誌治理
• 事故響應整合：alarm → EventBridge → PagerDuty / incident tool，見 08 Incident Response 模組