五段處理鏈路

第一段：HTTP endpoint 接收

Collector 對外提供一個 HTTP POST endpoint（例如 /v1/events），接收 SDK 送來的 JSON body。每個 request 可以是單一事件或批次事件陣列。

Endpoint 的職責只有兩件事：驗證 HTTP 層面的基本條件（Content-Type、body size limit、認證 token），然後把 body 傳給下一段。HTTP 層面的錯誤（413 body too large、401 unauthorized）在這裡回應，不進入後續處理。

自用工具場景下，Go 的 net/http 標準庫提供的 HTTP server 已足夠。一個 http.HandleFunc("/v1/events", handler) 加上 json.NewDecoder(r.Body).Decode(&events) 就完成接收。不需要 framework。

第二段：JSON Schema 驗證

收到的 JSON body 用 JSON Schema 驗證結構正確性 — 必要欄位是否存在、型別是否正確、值是否在合法範圍內。驗證失敗的事件被拒絕並記錄原因，通過的事件進入下一段。

Schema 驗證是 collector 的品質閘門。沒有驗證的 collector 會累積格式不一致的資料，查詢時需要處理各種邊界條件。驗證在寫入前攔截問題，比寫入後清理成本低。

驗證的粒度是事件級 — 批次中的一個事件驗證失敗不影響其他事件。回應中標明哪些事件被接受、哪些被拒絕及原因。

Ingestion 回應格式

回應格式把「接受了幾筆、拒絕了幾筆、拒絕原因」三件事用一套一致的結構表達。SDK 端只需要判斷 status code 就知道怎麼處理 buffer。

 1// 200 OK — 單筆成功或批次全部成功
 2{ "accepted": 1 }
 3
 4// 207 Multi-Status — 批次部分失敗
 5{
 6  "accepted": 1,
 7  "rejected": 1,
 8  "errors": [
 9    { "index": 1, "message": "missing required field: type", "fields": ["type"] }
10  ]
11}
12
13// 400 Bad Request — 單筆失敗或批次全部失敗
14{
15  "error": "schema validation failed",
16  "details": [
17    { "field": "type", "message": "missing required field" }
18  ]
19}
20
21// 503 Service Unavailable — 寫入端暫時不可用
22{ "error": "service temporarily unavailable", "retry_after": 5 }

設計選擇：207 的 errors 陣列用 index 標明失敗事件在原始 batch 中的位置（0-based），SDK 可以用 index 對照原始事件做 debug log。合法事件不因部分失敗而被丟棄 — 部分成功是 batch 收集的核心價值。400 和 207 的差異是「全軍覆沒 vs 部分存活」，SDK 端的處理策略不同：400 直接清 buffer（schema 問題重試也不會過），207 只清成功的部分。

Health endpoint 回應

Health endpoint 回傳 collector 自身的運行狀態，不包含事件內容。用途是 SDK 端確認 collector 可達、監控腳本定期探測。

1// GET /health → 200 OK
2{
3  "status": "ok",
4  "uptime_seconds": 3600,
5  "total_events": 1234,
6  "storage_bytes": 5242880,
7  "version": "0.1.0"
8}

total_events 和 storage_bytes 讓監控腳本判斷 collector 的負載趨勢。version 讓 SDK 確認 collector 版本（schema 不匹配時的第一個 debug 線索）。

第三段：儲存

通過驗證的事件寫入 Storage Backend。Collector 使用可插拔的 Storage interface — day-one 預設用 SQLite（零依賴、嵌入式），分析需求觸發時切換到 PostgreSQL。具體的 backend 選擇和功能分層見 功能分層與 Backend 選擇，可插拔架構見 規模演進。

第四段：查詢

儲存的事件透過 CLI 指令或 HTTP 查詢 endpoint 存取。SQLite backend 下用 SQL 查詢；匯出為 JSONL 格式後也可用 grep + jq 做臨時分析。

查詢設計見 查詢 API 設計。

第五段：Rule engine

Rule engine 在事件寫入後觸發，檢查事件是否匹配預定義的規則。匹配時執行對應的動作（發通知、寫 summary、觸發 webhook）。

Rule engine 設計見 Rule engine 設計。

多獨立 client 併發寫入

上述五段鏈路描述的是單一 request 的路徑。實際運行時，多個 SDK 會同時送事件——以下先描述場景，下方並發寫入策略再詳述 collector 如何處理。

常見部署場景中，多個完全獨立的 SDK 實例同時送事件到同一個 collector——不同 process、不同 app、甚至不同語言的 SDK。這和「一個 app 內的多 thread 併發」不同：每個 SDK 有自己的 buffer 和 HTTP 連線，不共享任何狀態。

SDK 端不需要知道其他 SDK 的存在。每個 SDK 獨立 init、獨立 buffer、獨立 flush、獨立 close。SDK 端的唯一接觸點是 collector 的 HTTP endpoint——併發安全由 storage backend 的併發策略保證（見下方並發寫入策略），不需要 SDK 端協調。多 client 同時 flush 時的背壓機制見 Ingestion 背壓與流量管控。

例如 CI pipeline 的多個 job 同時送 build 事件，或微服務架構中多個 service 各自送事件到同一個 collector。另一個具體案例是 Claude Code 的 Hook 系統——多個 Hook 同時觸發時，每個 Hook 是獨立的 Python process，各自初始化 SDK、產生事件、flush 到同一個 collector。

並發寫入策略

Go 的 HTTP server 為每個 request 分配一個 goroutine。多個 SDK 同時 flush 時，collector 同時收到多個寫入請求。Storage Backend 的並發能力決定了這些 goroutine 怎麼協調。

SQLite Backend：單寫者模型

SQLite 的 WAL mode 允許一個 writer 和多個 concurrent reader — 讀寫不互相阻塞，但多個 writer 之間是序列化的。Go 端有兩種處理 pattern：

Single-writer goroutine + channel：所有 Store() 呼叫把事件送進一個 Go channel，由一個專屬的 goroutine 從 channel 讀取並序列寫入 SQLite。HTTP handler 送完 channel 後等待確認（或用 buffered channel 異步）。優點是背壓控制清晰 — channel 滿時 HTTP handler 自然阻塞，可以回 503。缺點是多一層間接。

Busy timeout fallback：不在 Go 層管序列化，讓 SQLite driver 自己處理。設定 _pragma=busy_timeout(5000)，多個 goroutine 同時呼叫 Store() 時，SQLite 讓等待的 goroutine block 直到寫入鎖釋放（最多 5 秒）。優點是實作簡單（不需要 channel 和額外 goroutine）。缺點是背壓不可控 — goroutine 數量可能累積。

自用工具場景推薦 busy timeout（簡單）、寫入量增長到出現超時錯誤時切換到 channel pattern。

PostgreSQL Backend：連線池

PostgreSQL 透過連線池（database/sql 的 SetMaxOpenConns）支援並行寫入。多個 goroutine 可以同時寫入不同的連線，不需要額外的序列化機制。

Go 單一 binary 的設計選擇

Collector 用 Go 編譯成單一 binary，不依賴外部 runtime（JVM、Python interpreter、Node.js）。部署是複製一個檔案，啟動是執行一個指令。

這個選擇在自用工具場景下有特定優勢：server 和 collector 在同一台機器上，部署流程是 scp collector user@host: + ssh user@host ./collector。不需要 package manager、不需要 container registry、不需要 orchestration。

Go 的 net/http 標準庫提供 production-ready 的 HTTP server，JSON 處理用標準庫的 encoding/json，SQLite 用 modernc.org/sqlite（pure Go、無 CGO 依賴）。整個 collector 的核心邏輯可以在 500 行以內完成。

具體的部署步驟（systemd service 檔案、啟動參數、設定檔格式）和 Quick Start（從零到第一筆事件出現在 collector）見 monitor repo 的 deployment guide。

下一步路由

• 功能分層與 Backend 選擇 → 功能分層與 Backend 選擇
• 可插拔 Storage Backend 架構 → 規模演進
• JSONL 匯出與備份格式 → JSONL 儲存設計
• 查詢 API 的設計 → 查詢 API 設計
• Rule engine → Rule engine 設計
• 背壓與流量管控的基礎概念 → DevOps 流量管控
• 端到端資料完整性 → 端到端資料完整性
• Error fingerprint 與去重分群 → Error Fingerprint 與去重分群

JSONL 的格式是每行一個 JSON 物件。作為匯出格式，核心優勢是工具鏈成熟 — grep 過濾、jq 結構化查詢、tail -f 即時監控，不需要 database client。

一天一檔

事件按日期分檔：events-2026-06-19.jsonl、events-2026-06-20.jsonl。每天零點（或 UTC 日期變更時）切換到新檔案。

一天一檔的好處：

時間範圍查詢直接對應到檔案。查「昨天的 error」只需要讀一個檔案，不需要掃描整個資料集。

保留策略按檔案操作。保留 30 天的資料 = 刪除 30 天前的檔案。不需要 database 的 TTL 機制或 partition pruning。

備份和搬移按檔案操作。rsync 一個目錄就完成備份；搬移特定日期的資料 = 搬移對應檔案。

一天一檔的風險是單日資料量過大時，單一檔案的 grep 查詢會變慢。自用工具場景下，單日事件量通常在數千到數萬筆，檔案大小在 MB 級，grep 查詢在秒級完成。當單日事件量超過百萬筆時，需要考慮演進到更適合的儲存方案（見 規模演進）。

Append-only 寫入

JSONL 的寫入模式是 append-only — 新事件追加到檔案尾端，已寫入的事件不修改。

Append-only 的操作特性：

寫入不需要鎖。os.OpenFile 用 O_APPEND flag 開啟，OS 保證每次 write 是 atomic 的（在 write size 不超過 PIPE_BUF 的前提下，Linux 上是 4096 bytes）。單一事件的 JSON 通常在這個限制內。

不會損壞既有資料。寫入失敗（磁碟滿、程序崩潰）最多造成最後一行不完整，不影響前面的行。恢復時刪除最後一行的不完整片段即可。

支援 tail -f 即時監控。tail -f events-2026-06-19.jsonl | jq . 即時顯示新寫入的事件，不需要額外的 streaming 機制。

Gzip 壓縮

歷史檔案（非當天的）用 gzip 壓縮。JSON 文字的壓縮率通常在 80-90%（10MB 壓縮到 1-2MB）。

壓縮策略：

當天的檔案不壓縮。保持 append-only 和 tail -f 的能力。

日期切換時壓縮前一天的檔案。用 cron job 或 collector 啟動時檢查，把 events-2026-06-18.jsonl 壓縮為 events-2026-06-18.jsonl.gz。

查詢壓縮檔用 zgrep / zcat。zgrep "error" events-2026-06-18.jsonl.gz 不需要先解壓。

JSONL 備份的保留

JSONL 備份檔的保留策略和 SQLite 主要儲存的分層保留獨立 — JSONL 是最後的重建來源，保留期限可以比 SQLite 中的原始事件更長。

典型配置：JSONL 備份保留 30 天（即使 SQLite 中的原始事件只保留 7 天），提供 SQLite 損壞時的 30 天重建窗口。超過 30 天的 JSONL 壓縮檔用 cron job 清理：

1find /var/lib/collector/events/ -name "events-*.jsonl.gz" -mtime +30 -delete

主要儲存的查詢驅動分層保留策略見 規模演進。

匯出的實作注意

匯出使用 streaming — 從 storage 逐筆讀取、逐行寫出，記憶體使用和事件總量無關。300 萬筆事件（約 900MB JSONL）不需要整批載入記憶體。

匯出的 JSONL 檔案包含事件明文（已 redaction 的欄位除外）。匯出後的檔案不受 collector 的存取控制保護，注意存放位置和存取權限。

下一步路由

• Collector 的完整架構 → Collector 架構
• 查詢設計 → 查詢 API 設計
• 儲存撐不住時的演進 → 規模演進

CLI 查詢：grep + jq

JSONL 格式的最大優勢是原生支援 Unix 文字處理工具。不需要額外的查詢語言、不需要客戶端工具、不需要連線到 database。

常見查詢模式

按事件類型過濾：

1grep '"type":"error"' events-2026-06-19.jsonl | jq .

按 namespace 過濾：

1grep '"name":"terminal.connect' events-2026-06-19.jsonl | jq .

按時間範圍過濾（跨檔案）：

1cat events-2026-06-1{8,9}.jsonl | jq 'select(.ts >= "2026-06-18T18:00:00")'

統計每種事件的數量：

1jq -r '.name' events-2026-06-19.jsonl | sort | uniq -c | sort -rn

grep 友好的 JSONL 設計

JSONL 的每行 JSON 結構影響 grep 的查詢效率和準確性。

把常用過濾欄位放在 JSON 的前面。grep 是字串匹配，把 type 和 name 放在行首讓 grep pattern 更簡單、誤匹配更少。

避免 JSON 值中包含雙引號。事件名稱和型別用簡單字串（不含特殊字元），讓 grep 的 pattern 不需要處理 escape。

每行 JSON 不換行。JSONL 的定義就是每行一個 JSON，但格式化工具可能自動加換行。寫入時用 json.Marshal（Go）或 JSON.stringify（JS）確保單行輸出。

HTTP 查詢 endpoint

HTTP 查詢 endpoint 讓非 CLI 使用者（dashboard、自動化腳本、其他服務）能查詢事件資料。

Endpoint 設計

1GET /v1/events?type=error&name=terminal.connect.*&from=2026-06-18T00:00:00Z&to=2026-06-19T00:00:00Z&limit=100

查詢參數：

回應格式

 1{
 2  "events": [
 3    {
 4      "v": 1,
 5      "type": "error",
 6      "timestamp": "2026-06-19T08:42:00Z",
 7      "source": { "sdk": "python", "platform": "macos", "app": "claude-hooks" },
 8      "name": "hook.failure",
 9      "level": "error",
10      "data": { "hook": "branch-status-reminder", "step": "validation" },
11      "error": { "message": "KeyError: 'status'", "stack": "Traceback...", "type": "KeyError" },
12      "context": { "session_id": "sess-abc-123" }
13    }
14  ],
15  "total": 42,
16  "limit": 100,
17  "offset": 0
18}

events 陣列按 timestamp 降序排列。total 是符合篩選條件的全量筆數（不受 limit 截斷），讓呼叫端計算分頁（total_pages = ceil(total / limit)）。分頁用 offset-based（offset=100 取第二頁），適合資料量在十萬筆以下的場景。資料量大到 offset 效能不足時，改用 cursor-based（after=<last_event_id>），但 cursor-based 是 PostgreSQL 層的演進，SQLite 層用 offset 足夠。

實作策略

HTTP 查詢 endpoint 的底層實作可以直接讀取 JSONL 檔案 — 根據 from/to 確定要讀哪些日期的檔案，逐行 parse 並過濾。這個實作在資料量小（單日萬筆以下）時足夠快。

當查詢效能成為問題時，在 JSONL 之上加一層索引（按 type/name 建立反向索引），或演進到 SQLite 儲存（見 規模演進）。

聚合查詢

逐筆查詢回答「發生了什麼」，聚合查詢回答「發生了多少」。Error 調查的第一步是定位最頻繁的 error — 「哪些 error 最多」需要按 name 分群計數的聚合結果，逐筆列表在這個階段資訊量太大。

Endpoint 設計

1GET /v1/events/summary?type=error&from=2026-06-18T00:00:00Z&to=2026-06-19T00:00:00Z&group_by=name

回傳按 name 分群的統計：

1{
2  "groups": [
3    { "name": "hook.failure", "count": 15, "last_seen": "2026-06-19T08:42:00Z" },
4    { "name": "terminal.connect.failed", "count": 3, "last_seen": "2026-06-19T07:10:00Z" }
5  ],
6  "total": 18,
7  "from": "2026-06-18T00:00:00Z",
8  "to": "2026-06-19T00:00:00Z"
9}

查詢參數和逐筆查詢共用（type、name、from、to），額外的 group_by 指定分群欄位（name 或 type）。

SQL 實作

SQLite backend 下直接用 GROUP BY：

1SELECT name, COUNT(*) as count, MAX(timestamp) as last_seen
2FROM events
3WHERE type = 'error' AND timestamp BETWEEN ? AND ?
4GROUP BY name
5ORDER BY count DESC
6LIMIT 100

有 type + timestamp 複合索引時，這個查詢在 10 萬筆資料內的效能和逐筆查詢相當 — GROUP BY 在索引掃描後做，不需要全表掃描。

和逐筆查詢的定位差異

兩者是互補的工作流 — 聚合查詢定位問題方向，逐筆查詢深入細節。Dashboard 的 Error 列表頁面直接消費聚合查詢的結果。

CLI vs HTTP 的定位

兩種介面共存 — CLI 用於開發者日常 debug，HTTP endpoint 用於自動化和遠端存取。兩者底層讀取同一份 JSONL 檔案，結果一致。

下一步路由

• JSONL 儲存的設計 → JSONL 儲存設計
• Rule engine 的自動化處理 → Rule engine 設計
• Collector 的完整架構 → Collector 架構

三段式規則結構

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

條件

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

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 認證

待寫章節

• Collector 架構（HTTP endpoint → JSON Schema 驗證 → 儲存 → 查詢 → rule engine）
• JSONL 匯出與備份格式（匯出格式、gzip 壓縮、備份保留）
• 查詢 API 設計（CLI grep 友好 vs HTTP 查詢 endpoint）
• Rule engine 設計（條件 → 動作 → 模板）
• 規模演進：可插拔 Storage Backend（SQLite 預設 / PostgreSQL 觸發）
• 功能分層與 Backend 選擇（SQLite 層 vs PostgreSQL 層的功能邊界）
• SQLite Backend 效能基準（寫入吞吐 / 查詢延遲 / 資源消耗的量化預期）
• Ingestion Scaling（四層防線 — SDK 取樣 → Collector 背壓 → 水平擴展 → Queue 解耦）
• 查詢消費模式（Debug / Alerting / 產品決策 / 安全審計 / 效能監控）
• DevOps Dashboard 設計
• Developer Dashboard 設計
• 中台 Dashboard 設計
• Container 部署設計（SQLite 在 container 中的 I/O 考量、volume mount、graceful shutdown）
• 讀寫分離與查詢擴展（讀寫競爭辨識、Read Replica、預聚合、CQRS 判讀訊號）
• 端到端資料完整性（資料損失地圖、完整性指標、被自己 SDK DDoS 的防護）
• Error Fingerprint 與去重分群（fingerprint 演算法、message normalization、error_groups 表）

跨分類引用

• → backend 01 資料庫：PostgreSQL backend 的資料庫設計、State Ownership 與 Query Boundary
• → backend 04 觀測查詢設計：觀測領域的讀取路徑設計、CQRS 特化應用
• → backend 09 效能容量：高併發寫入 / 大資料查詢的效能挑戰
• → DevOps 流量管控：背壓、rate limit、熔斷的基礎概念
• → DevOps 突發流量：突發流量分類、降級策略、queue 緩衝
• → 斷網環境的監控：Collector 在斷網環境的部署方式——endpoint 改指 self-hosted backend、SDK 的 offline buffer 更重要
• 實作 repo：tarrragon/monitor 的 collector/ + docs/challenges/（撞牆記錄）

 1type BasicStorage interface {
 2    Store(event Event) error
 3    Query(filter QueryFilter) ([]Event, error)
 4    Close() error
 5    Downsample() error
 6    Purge() error
 7}
 8
 9type AnalyticsStorage interface {
10    BasicStorage
11    Aggregate(spec AggregateSpec) (AggregateResult, error)
12    Funnel(steps []string, timeWindow Duration) (FunnelResult, error)
13    Cohort(groupBy string, metric string) (CohortResult, error)
14}

SQLite implementation 只實作 BasicStorage。PostgreSQL implementation 實作 AnalyticsStorage。Dashboard 用 Go 的 type assertion（if as, ok := storage.(AnalyticsStorage); ok { ... }）判斷能力 — funnel/cohort 視圖在 SQLite 模式下不顯示入口，而非顯示後報錯。

選擇哪個 backend 取決於部署場景和查詢需求：

SQLite Backend（day-one 預設）

SQLite 是嵌入式資料庫，編譯進 collector binary 中，不需要額外 server。Go 用 modernc.org/sqlite（pure Go、無 CGO 依賴、效能約為 CGO driver mattn/go-sqlite3 的 60-80%，自用規模下足夠），開源使用者 go build && ./collector 就能跑，部署步驟為零。WAL mode 允許讀寫並行 — dashboard 的 SELECT 查詢不會被 ingestion 的 INSERT 阻塞，反之亦然。寫入之間的競爭由 busy_timeout 處理。

能力範圍

• 索引查詢：按 type、name、timestamp 建索引，查詢從全表掃描變成索引查找
• SQL 聚合：SELECT name, COUNT(*) FROM events WHERE type='error' GROUP BY name — 一行 SQL 完成分群計數
• 跨欄位過濾：WHERE type='error' AND name LIKE 'terminal.%' AND ts > '2026-06-18'
• 寫入：WAL mode 下每秒數千筆 append 寫入

Events 主表 DDL

Events 表的欄位從 event.schema.json 的 JSON 結構推導。Source 的 nested object 攤平成獨立 column — 方便 SQL 查詢和索引，不需要每次從 JSON 裡 extract。

 1CREATE TABLE events (
 2    id INTEGER PRIMARY KEY AUTOINCREMENT,
 3    v INTEGER NOT NULL DEFAULT 1,
 4    type TEXT NOT NULL,
 5    name TEXT NOT NULL,
 6    ts TEXT NOT NULL,
 7    source_sdk TEXT,
 8    source_app TEXT,
 9    source_version TEXT,
10    source_platform TEXT,
11    source_os TEXT,
12    session_id TEXT,
13    session_started TEXT,
14    level TEXT,
15    data TEXT,
16    error_message TEXT,
17    error_stack TEXT,
18    error_type TEXT,
19    receive_ts TEXT
20);

source_sdk 獨立成 column 讓「按 SDK 來源篩選」（WHERE source_sdk = 'python'）不需要從 JSON extract。data 用 TEXT 存 JSON。SQLite 沒有原生 JSON 型別，但 3.38+ 支援 json_extract() 函式做查詢（WHERE json_extract(data, '$.duration_ms') > 1000）。session_id 獨立成 column 讓 session 回放的 JOIN 不需要 JSON extract。error_stack 獨立成 column 讓 error 調查時全文搜尋 stack trace 不需要 JSON extract。receive_ts 是 collector 收到事件的時間，和 SDK 端的 ts 對照可估算 clock drift。

PostgreSQL 版本的差異：data 改成 JSONB 型別（原生索引和查詢）、source_* 可保持為 nested JSON（PostgreSQL 的 JSONB 查詢效能足夠）或維持攤平（和 SQLite 版本保持一致）。

建議索引

建表時一起建索引，覆蓋 dashboard 的核心查詢模式：

1CREATE INDEX idx_type_ts ON events(type, ts);    -- 按 type + 時間過濾（error 列表、趨勢圖）
2CREATE INDEX idx_session ON events(session_id);   -- 按 session 回放
3CREATE INDEX idx_name ON events(name);            -- 按 name 分群計數（功能使用排行）

Day-one 建表時就建，不是效能出問題後才加。

適用規模

單日事件量在十萬筆以下、SQLite 資料庫在 1GB 以下。索引查詢在毫秒級完成。自用工具和小型團隊的日常使用通常在這個範圍。

分層保留與降採樣

保留策略從查詢需求反推，每一種查詢需要的資料粒度和回溯深度不同。回溯越深的查詢需要的粒度越粗 — debug 需要最近幾天的逐筆事件，cohort 留存需要一整年的資料但每週一筆聚合數字就夠。

SQLite 中的實作是三張摘要表加定期 job：

 1-- 摘要表
 2CREATE TABLE hourly_summary (
 3    hour TEXT, type TEXT, name TEXT,
 4    count INTEGER, error_count INTEGER,
 5    UNIQUE(hour, type, name)
 6);
 7CREATE TABLE daily_summary (
 8    date TEXT, type TEXT, name TEXT,
 9    count INTEGER, unique_sessions INTEGER,
10    UNIQUE(date, type, name)
11);
12
13-- 降採樣（Downsample，每小時跑一次，幂等 — 重跑只更新不重複）
14INSERT OR REPLACE INTO hourly_summary (hour, type, name, count, error_count)
15SELECT strftime('%Y-%m-%dT%H:00:00', ts), type, name,
16       COUNT(*), SUM(CASE WHEN type='error' THEN 1 ELSE 0 END)
17FROM events
18WHERE ts >= datetime('now', '-1 hour')
19GROUP BY 1, 2, 3;
20
21-- 清理（Purge，每天跑一次，分批刪除避免長時間鎖定）
22DELETE FROM events WHERE rowid IN (
23  SELECT rowid FROM events WHERE ts < datetime('now', '-7 days') LIMIT 10000
24);
25-- 重複執行直到影響行數為 0
26DELETE FROM hourly_summary WHERE hour < datetime('now', '-90 days');
27DELETE FROM daily_summary WHERE date < datetime('now', '-365 days');

保留期限由 collector config 設定，數字的來源是「哪些查詢需要回溯多遠」：

1retention:
2  raw_events: 7d
3  hourly_summary: 90d
4  daily_summary: 365d
5  monthly_summary: forever

Storage interface 的 Downsample() 和 Purge() 由 collector 的定時排程觸發（Go 的 time.Ticker）。每個 storage backend 各自實作 — SQLite 用上述 SQL、PostgreSQL 用相同邏輯但可以加 partial index 加速、時間序列 DB 的 continuous aggregate 和 retention policy 原生支援。

為什麼是聚合而非抽樣

原始事件的保留期到期後，需要決定如何保留歷史統計。降採樣有兩種思路。抽樣保留是同事件名稱（name 欄位）同小時保留一筆原始事件、刪除其餘，保留了逐筆查詢能力但喪失準確計數。聚合摘要是把一小時內的事件壓成一筆計數記錄，喪失逐筆細節但保留準確統計。

Collector 選擇聚合摘要——捨棄逐筆細節，換取準確計數。降採樣後的資料用途是趨勢圖和長期統計，這些查詢需要「過去 30 天每小時的 error 總數」而非「某一筆原始 error 的 stack trace」。

這意味著原始事件 purge（定期清理過期事件）後，超過保留期的逐筆查詢會回傳空結果。Dashboard 在回溯超過原始事件保留期的時間範圍時，應切換到上方的摘要表（hourly_summary/daily_summary）查詢——顯示趨勢圖而非事件列表。設計方向是查詢 API 的 from 參數超過 retention.raw_events 時自動降級到摘要表，或回傳提示告知 client 該時間範圍只有聚合資料（初版 collector 尚未實作此降級邏輯）。

觸發切換到 PostgreSQL 的訊號

寫入爭搶：SQLite 是單寫者模型。高併發寫入（多個 SDK 同時 flush、每秒數百筆以上持續發生）會出現 database is locked 錯誤。WAL mode 能緩解但不能根治。

聚合查詢效能不足：Dashboard 需要的聚合查詢（「過去 30 天每小時的 error 數量趨勢」「funnel 的每步轉換率」）在資料量成長後變慢。SQLite 沒有 parallel query 和 partial index 等進階 OLAP 能力。

跨實例需求：需要多個 collector 實例共用同一個資料庫時，SQLite 的單檔案模型無法跨主機存取。

PostgreSQL Backend（分析觸發）

PostgreSQL 是獨立的資料庫 server，提供多連線並行寫入、進階索引（GIN for JSONB、partial index）和完整的 SQL 分析能力。切換到 PostgreSQL 意味著 collector 從「零依賴單一 binary」變成「binary + 外部 DB」，運維複雜度上升。

觸發條件

SQLite 的寫入爭搶或聚合效能成為瓶頸時切換。具體訊號：database is locked 錯誤頻率超過每分鐘一次、或 dashboard 的聚合查詢超過 3 秒。

切換方式

切換是 config change：把 --storage=sqlite 改成 --storage=postgres --dsn=postgres://...。資料遷移用匯出 + 匯入完成：

1. 從 SQLite 匯出事件為 JSONL（monitor export --format=jsonl）
2. 在 PostgreSQL 建立 events 表（schema 和 SQLite 相同，data 欄位改用 JSONB）
3. 匯入 JSONL 到 PostgreSQL（monitor import --storage=postgres --file=events.jsonl）
4. 切換啟動參數、確認查詢正常後停用 SQLite 檔案

Storage interface 保證 collector 的 ingestion、query、rule engine 邏輯不需要改動 — 只有 storage implementation 層切換。

能力增量

• 並行寫入：多個 SDK 同時 flush 不會 lock
• JSONB 索引：對 data 欄位的特定 key 建索引（CREATE INDEX ON events ((data->>'name'))）
• Window function：funnel 和 cohort 分析的 SQL 基礎
• Read replica：寫入和查詢分離，dashboard 的查詢不影響 ingestion 效能

時間序列 DB Backend（長期演進）

時間序列資料庫（TimescaleDB、InfluxDB、VictoriaMetrics）專門為高頻 append 寫入和時間分桶聚合設計。TimescaleDB 基於 PostgreSQL 擴展，Storage interface 的 PostgreSQL implementation 可以直接複用、加上 hypertable 和 continuous aggregate。

觸發條件

每秒數萬筆以上的持續寫入、或需要自動 downsampling（每分鐘的原始資料保留 7 天、每小時的聚合保留 90 天、每天的聚合永久保留）。多數自用工具和小型團隊不會到達這個規模。

能力增量

• 時間分桶原生操作：time_bucket('1 hour', ts) 替代手動 DATE_TRUNC
• Continuous aggregate：預計算的聚合結果自動更新
• 壓縮：歷史資料自動壓縮，TB 級資料可查詢
• Retention policy：按時間自動清理舊資料

JSONL 匯出（debug 用途）

JSONL 不作為主要 storage backend，而是作為匯出格式保留人類可讀性和 grep 友好性。monitor export --format=jsonl 把 storage 中的事件匯出為每行一個 JSON 物件的檔案，讓開發者可以用 grep / jq 做臨時查詢或把資料搬到其他工具。

JSONL 匯出也是備份和遷移的中介格式 — SQLite 損壞時從 JSONL 重建、切換到 PostgreSQL 時從 JSONL 匯入。

匯出使用 streaming — 從 storage 逐筆讀取、逐行寫出檔案，記憶體使用和事件總量無關。300 萬筆事件（約 900MB JSONL）的匯出不需要載入全部資料到記憶體。匯出的 JSONL 檔案包含事件明文（已 redaction 的欄位除外），匯出後不受 collector 的存取控制保護，應注意存放位置和存取權限。

演進原則

按觀察到的瓶頸切換。database is locked 錯誤頻率、聚合查詢延遲、磁碟使用量 — 這些是可觀察的訊號。「未來可能有百萬筆事件」是預測。按訊號行動，不按預測行動。

切換是 config change。Storage interface 確保切換 backend 時 collector 的其他邏輯（ingestion、query API、rule engine、dashboard）不需要改動。切換的成本是資料遷移，不是程式碼重寫。

SQLite 是安全的起點。多數開源使用者會停留在 SQLite backend — 單日萬筆以下、索引查詢毫秒級、零依賴部署。只有明確的效能瓶頸才值得引入外部 DB 的運維成本。

下一步路由

• Collector 的整體架構 → Collector 架構
• 查詢 API 的設計（跨 backend 統一） → 查詢 API 設計
• 資料庫選型的通用指南 → backend 01 資料庫
• 效能瓶頸的判讀方法 → backend 09 效能容量
• 水平擴展的基礎概念 → DevOps 水平擴展
• Error fingerprint 的 DDL 擴充 → Error Fingerprint 與去重分群

SQLite 層：開發者工具

SQLite 層提供的功能聚焦在「開發者自己 debug 和監控」。所有查詢都是單一維度的 — 按時間、按類型、按名稱過濾，不需要跨事件 JOIN 或跨使用者聚合。

承載的功能

這些功能覆蓋開發者日常 debug 和監控的核心操作 — 查錯誤、看時間軸、回放 session、設規則告警。

對應的 Dashboard 視圖

對應的事件消費

SQLite 層消費所有四類事件，但消費方式是「單筆或單 session 級查詢」：

PostgreSQL 層：行為分析

PostgreSQL 層在 SQLite 層的基礎上加入「跨 session、跨使用者的聚合分析」。這些查詢需要 JOIN 多張表、計算時間窗口、處理大量資料的 GROUP BY — SQLite 的單寫者模型和有限的查詢最佳化器在這些場景下效能不足。

觸發引入 PostgreSQL 的功能需求

判斷公式

1需要 funnel / cohort / RFM 任一 → PostgreSQL
2需要跨使用者聚合（不只看自己的資料） → PostgreSQL
3需要高併發寫入（多個 SDK 同時 flush 且持續出現 database is locked 錯誤） → PostgreSQL
4以上都不需要 → SQLite 足夠

對應的 Dashboard 視圖（SQLite 層不提供）

對應的事件消費

PostgreSQL 層消費的事件和 SQLite 相同（Ingestion 不變），但消費方式從「單筆/單 session」擴展到「跨 session/跨使用者」：

Domain 的分層影響

Ingestion 和 Rule 兩個 domain 和 storage backend 無關 — 事件進來的方式和規則評估的邏輯不因 backend 改變。Query 和 Dashboard 是分層影響最大的兩個 domain — PostgreSQL 層的查詢能力決定了 Dashboard 能提供什麼視圖。

實作邊界

Storage interface 用 Go 的 interface composition 分成兩層：

 1type BasicStorage interface {
 2    Store(event Event) error
 3    Query(filter QueryFilter) ([]Event, error)
 4    Close() error
 5    Downsample() error
 6    Purge() error
 7}
 8
 9type AnalyticsStorage interface {
10    BasicStorage
11    Aggregate(spec AggregateSpec) (AggregateResult, error)
12    Funnel(steps []string, timeWindow Duration) (FunnelResult, error)
13    Cohort(groupBy string, metric string) (CohortResult, error)
14}

SQLite implementation 只實作 BasicStorage。PostgreSQL implementation 實作 AnalyticsStorage。Dashboard 用 Go 的 type assertion（if as, ok := storage.(AnalyticsStorage); ok { ... }）判斷能力 — funnel/cohort 視圖在 SQLite 模式下不顯示入口，而非顯示後報錯。

下一步路由

• 可插拔 Storage Backend 的架構 → 規模演進
• 事件枚舉方法（哪些事件要收） → 事件枚舉與補齊檢查
• 分層保留策略 → 規模演進的分層保留段
• Funnel 分析的完整方法論 → Funnel analysis
• 查詢消費模式（各場景需要什麼事件）→ 查詢消費模式

五種查詢場景各自需要不同的事件類型、欄位和查詢模式。每種場景的查詢模式也決定了需要 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 服務探活

定義 funnel 步驟

Funnel 分析的第一步是列出每一步和對應的事件名稱。以一個透過 WebSocket 連接遠端終端機的 app 連線流程為例：

SQLite 層：每步事件計數

SQLite backend 能做的 funnel 是「每步有多少事件觸發」— 單表 GROUP BY，不需要跨事件 JOIN。

1SELECT name, COUNT(*) as count
2FROM events
3WHERE name IN ('terminal.connect.start', 'auth.biometric.success',
4               'terminal.connect.done', 'terminal.input.submit')
5  AND ts >= datetime('now', '-7 days')
6GROUP BY name;

步驟 N 的轉換率 = 步驟 N 的事件數 / 步驟 N-1 的事件數。流失率 = 1 - 轉換率。

能做的

• 每步事件計數（單表 GROUP BY）
• 按 source.version 或 source.platform 分群（加 WHERE 條件）
• 按天/按週看趨勢（strftime 分桶 + GROUP BY）

做不到的

• Session 級轉換率：「同一個 session 完成步驟 1 到步驟 4 的比例」需要 JOIN 同 session 的多個事件、跨所有 session 聚合。SQLite 能做這個 JOIN，但在大量 session 時效能不足。
• 步驟間耗時：「使用者在步驟 1 和步驟 2 之間等了多久」需要 self-join on session_id + timestamp 差值計算。
• 漏斗順序驗證：確認使用者是按 1→2→3→4 順序完成、不是跳步。

PostgreSQL 層：Session 級 funnel

PostgreSQL backend 提供 window function 和高效 JOIN，能做完整的 session 級 funnel 分析。

 1WITH session_steps AS (
 2  SELECT session_id, name,
 3         ROW_NUMBER() OVER (PARTITION BY session_id ORDER BY ts) as step_order
 4  FROM events
 5  WHERE name IN ('terminal.connect.start', 'auth.biometric.success',
 6                 'terminal.connect.done', 'terminal.input.submit')
 7    AND ts >= NOW() - INTERVAL '7 days'
 8),
 9session_max_step AS (
10  SELECT session_id, MAX(step_order) as reached
11  FROM session_steps
12  GROUP BY session_id
13)
14SELECT reached, COUNT(*) as sessions
15FROM session_max_step
16GROUP BY reached
17ORDER BY reached;

新增能力

• Session 級轉換率：每個 session 到達了哪一步、在哪一步流失
• 步驟間耗時：LAG window function 計算相鄰步驟的 timestamp 差值
• 漏斗順序驗證：用 ROW_NUMBER + CASE 確認步驟順序
• Cohort 分群的 funnel：按使用者註冊日期 / 版本 / 平台分群看不同 cohort 的 funnel 差異

JSONL 匯出後的臨時分析

Collector 的 monitor export --format=jsonl 可以匯出事件為 JSONL 格式。匯出後用 grep + jq 做一次性的臨時分析：

1for step in terminal.connect.start auth.biometric.success terminal.connect.done terminal.input.submit; do
2  count=$(grep "\"name\":\"$step\"" exported-events.jsonl | wc -l)
3  echo "$step: $count"
4done

JSONL 臨時分析適合「快速看一眼大概數字」的場景。持續性的 funnel 監控應該用 SQLite 或 PostgreSQL 的 SQL 查詢，結果穩定且可重現。

自架 vs 商業方案

自用工具場景下，SQLite 層的每步事件計數通常足夠。商業產品需要 session 級分析時，PostgreSQL 層的 SQL 能力和商業方案的分析能力在功能上對等，差異在 UI 和設定便利性。

下一步路由

• Funnel 分析的完整方法論 → Funnel analysis
• 事件設計如何影響分析品質 → 行為事件設計
• 功能分層定義 → 功能分層與 Backend 選擇
• 去識別化是分析的入場條件 → 模組七 資安與隱私

和 DevOps dashboard 的差異：DevOps 看「基礎設施是否健康」，Developer 看「程式碼是否正確」。Error 趨勢上升在 DevOps 眼中是「事件量異常」，在 Developer 眼中是「程式碼 bug」。

日常監控視圖

Error 摘要

一個數字卡顯示最近 24 小時的 error 總數 + 和前一天的比較（上升 / 下降 / 持平）。旁邊標注「新 error」數量 — 過去 24 小時首次出現的 error name。

新 error 的偵測邏輯：error.name 在最近 24 小時的事件中存在、但在更早的事件中不存在。這是開發者最需要立即注意的 — 新版本引入的 bug 通常表現為「之前沒見過的 error name」。

Error 列表

表格按 error.name 分群，每行顯示：error 名稱、最近 24 小時出現次數、影響的 session 數、首次出現時間、最近出現時間。按出現次數降序排列。

點擊某行進入 Error 詳情視圖。

 1-- SQLite 層可用
 2SELECT name,
 3       COUNT(*) as count,
 4       COUNT(DISTINCT session_id) as sessions,
 5       MIN(ts) as first_seen,
 6       MAX(ts) as last_seen
 7FROM events
 8WHERE type = 'error'
 9  AND ts >= datetime('now', '-1 day')
10GROUP BY name
11ORDER BY count DESC;

Error 趨勢

折線圖顯示過去 7 天每天的 error 數量。可選按 error.name 過濾看單一 error 的趨勢，或看全部 error 的總趨勢。

趨勢的判讀訊號：

• 穩定持平 → 已知的 recurring error，排優先處理
• 新版本部署後突然上升 → 該版本引入的 regression
• 逐漸上升 → 累積性問題（記憶體洩漏、資源耗盡）

版本健康

按 source.version 分群的 error 率比較。每個版本顯示：error 數量、error rate（error / 總事件比）、最常見的 error name。

版本健康視圖幫助判斷「這個版本該不該 rollback」— 如果新版本的 error rate 顯著高於前一版，rollback 決策有數字依據。

Debug 深入視圖

從日常監控的 Error 列表點擊某個 error 進入深入視圖。

Error 詳情

單個 error name 的完整資訊：

• Stack trace（最近一次出現的 error.data.stack_trace）
• 首次出現時間和總出現次數
• 影響的 session 數和佔比
• 按版本分佈（哪些版本有、哪些沒有）
• 按平台分佈（iOS / Android / Web）
• 最近 10 次出現的時間軸

Session 回放

選擇一個受影響的 session，顯示該 session 的完整事件序列。事件按時間排列，每筆事件顯示類型、名稱、時間、data 摘要。Error 事件用顯眼的樣式標記，讓開發者快速定位「error 發生前使用者做了什麼」。

Session 回放需要同一個 session_id 的所有四類事件。這是 event-enumeration-method 中「Debug — 最近操作」事件的核心消費場景。

1-- SQLite 層可用
2SELECT type, name, ts, data
3FROM events
4WHERE session_id = ?
5ORDER BY ts;

平台分佈

某個 error name 在不同平台和 OS 版本的分佈圖。幫助判斷「這個 error 是全平台問題、還是特定平台的 bug」。

1-- SQLite 層可用
2SELECT json_extract(source, '$.platform') as platform,
3       json_extract(source, '$.os') as os_version,
4       COUNT(*) as count
5FROM events
6WHERE type = 'error' AND name = ?
7GROUP BY platform, os_version;

事件覆蓋確認

Developer dashboard 需要的所有事件在目前的事件設計中已完整覆蓋：

SQLite 層 vs PostgreSQL 層

Developer dashboard 的多數視圖在 SQLite 層就能運作 — 都是單表 GROUP BY 和 WHERE 過濾。

開發者 debug 場景不需要 PostgreSQL — SQLite 層的查詢能力已涵蓋所有核心視圖。PostgreSQL 的需求來自效能指標的高級分析（P95 趨勢），但這屬於效能監控動機而非 debug 動機。

下一步路由

• DevOps dashboard 設計 → DevOps Dashboard 設計
• 中台 dashboard 設計 → 中台 Dashboard 設計
• Error 事件的枚舉方法 → 事件枚舉與補齊檢查
• 功能分層與 Backend 選擇 → 功能分層與 Backend 選擇
• Error fingerprint 分群取代 name 分群 → Error Fingerprint 與去重分群

中台 dashboard 的所有深入分析視圖都需要 PostgreSQL 層（功能分層與 Backend 選擇），因為它們依賴跨 session 的 JOIN 和大規模聚合查詢。SQLite 層只能提供基礎的事件計數。

日常監控視圖

DAU / MAU

每日活躍使用者數（DAU）和每月活躍使用者數（MAU）的趨勢折線圖。活躍使用者的定義是「該時間段內至少有一筆 session.start 事件的唯一 session」。

DAU / MAU 比值（粘性指數）是產品健康的基本訊號 — 比值越高代表使用者回訪越頻繁。一般 SaaS 產品的 DAU/MAU 在 10-20% 為正常範圍，社交類產品期望 50% 以上。

1-- PostgreSQL
2SELECT date_trunc('day', ts) as day,
3       COUNT(DISTINCT session_id) as dau
4FROM events
5WHERE type = 'lifecycle' AND name = 'session.start'
6  AND ts >= NOW() - INTERVAL '30 days'
7GROUP BY day
8ORDER BY day;

核心漏斗

主要業務流程的每步轉換率。漏斗的步驟從 動機驅動的事件設計 的商業動機段定義。

日常視圖顯示最近 7 天的整體轉換率 — 營運人員每天看「昨天的漏斗有沒有異常」。轉換率突然下降是產品問題的早期訊號（UI 改版影響操作流程、第三方服務異常阻擋流程）。

功能使用排行

按 event.name 計數的排行榜。營運用它判斷「哪些功能有人用、哪些沒人用」— 功能投資的 ROI 判斷依據。

1-- SQLite 層可用（基礎計數）
2SELECT name, COUNT(*) as usage_count
3FROM events
4WHERE type = 'event'
5  AND ts >= datetime('now', '-7 days')
6GROUP BY name
7ORDER BY usage_count DESC
8LIMIT 20;

功能使用排行是 SQLite 層就能提供的視圖 — 單表 GROUP BY。

分析深入視圖

日常視圖發現異常後，營運人員進入分析視圖深入探究。所有分析視圖都需要 PostgreSQL 層。

Funnel 漏斗圖

互動式漏斗圖：選擇步驟 → 看每步轉換率 → 點擊某步看流失使用者的行為。

Funnel 需要 session 級 JOIN — 「同一個 session 完成了步驟 1 到步驟 N 中的哪些步驟」。完整的 SQL 查詢見 從 collector 資料做基礎 funnel 分析。

Cohort 留存表

按「使用者首次出現日期」分群的留存率矩陣。行是 cohort（第 N 週註冊的使用者），列是「第 1/2/3/…週的回訪率」。

需要的事件：user.first_seen（cohort 分群依據）+ session.start（回訪判定）。

user.first_seen 是 collector 端計算的衍生事件 — 當某個 session_id 或 user identifier 在系統中第一次出現時記錄。和 SDK 端送來的原始事件不同，它的產生者是 collector 的計算邏輯。

A/B 測試結果

實驗的 variant 間轉換率比較 + 統計顯著性指標（p-value、信賴區間）。

需要的事件：experiment.{name}.assigned（分組）+ experiment.{name}.converted（轉換）。這些事件在 動機驅動的事件設計 的 A/B 測試段定義。統計分析的方法見 A/B test 的統計基礎。

RFM 分群散佈圖

三維度（Recency / Frequency / Monetary）的使用者分群。每個使用者計算 R/F/M 分數，按分數分群後在散佈圖上顯示。

需要的事件：event 類的購買/使用事件 + lifecycle 的 session 事件。計算方法見 RFM 分群。

通路歸因

使用者從哪裡來（哪個廣告、哪個推薦連結、自然流量），每個通路帶來多少轉換。

需要的事件：attribution.install_source（SDK 首次啟動時從 referrer / UTM 參數 / deep link 取得安裝來源）+ conversion.{type}（轉換事件）。

attribution.install_source 只在 SDK 首次啟動時送一次。來源資訊的取得方式依平台不同 — Web 從 URL 的 UTM 參數取、mobile app 從 deferred deep link 或 install referrer API 取。

需要的缺口事件

中台 dashboard 暴露了三個目前事件表未覆蓋的事件：

這三個事件的共同特徵：前兩個是「只發生一次」的事件（首次出現、首次安裝），第三個是 collector 端的即時計算結果。操作盤點和四類補齊檢查聚焦在「反覆發生的使用者操作」，容易遺漏「只發生一次」的生命週期轉折點和 collector 端的衍生計算。

中台的權限隔離

營運和行銷人員看行為資料，但不需要也不應該看到 stack trace、raw error message、session 級別的原始事件明細。權限隔離在 collector 的查詢 API 層實作 — 不同的 API scope 回傳不同粒度的資料。

Scope 的實作可以是 API key 分級（不同 key 有不同 scope）、或 HTTP header 帶 role。Day-one 可以跳過（自用場景只有 developer 一個角色），tripwire 是「第一個非開發者要看 dashboard 時加入 scope 機制」。

下一步路由

• DevOps dashboard 設計 → DevOps Dashboard 設計
• Developer dashboard 設計 → Developer Dashboard 設計
• Funnel 分析的完整方法 → Funnel analysis
• 功能分層與 Backend 選擇 → 功能分層與 Backend 選擇
• 去識別化是中台 dashboard 的入場條件 → 模組七 資安與隱私
• 畫面狀態矩陣定義了 funnel 步驟的操作來源 → 畫面狀態矩陣

本文是 OpenTelemetry 的 vendor deep article，深化 overview「Collector 部署模式」段。初次接觸 OpenTelemetry 的讀者建議先讀 OpenTelemetry 服務頁，再回到本文。指令於 2026-06-16 用 otel/opentelemetry-collector-contrib:0.154.0 在 docker 實機驗證。

應用程式產生的 telemetry 跟最終存放的 backend 之間需要一個中介層 — OTel Collector 就是這個中介。應用只負責用 OTLP 把資料吐給 collector，collector 負責接收、處理、轉發，兩邊解耦。部署這個 collector 的第一個決策是它擺在哪裡（同 host、集中 gateway、還是 pod sidecar），而非配置細節。位置決定了 buffer 能力、enrichment 時機與失效影響面。

問題情境：telemetry 直送 backend 的三個代價

應用程式直接用 vendor SDK 把 telemetry 送到後端，會在規模變大時撞到三個問題。第一是耦合：每個服務都寫死了某個 backend 的 endpoint 與認證，換 backend 要改所有服務重新部署。第二是缺乏 buffer：backend 短暫不可用時，telemetry 直接丟失，因為應用程式不會為了觀測資料保留重試佇列。第三是 enrichment 分散：每個服務各自加 resource attribute、各自做 sampling，標準難統一。

Collector 把這三件事收斂到一個中介層。應用只認 collector 的 OTLP endpoint，換 backend 只改 collector 配置；collector 有 queue 與重試；enrichment 與 sampling 在 collector 統一做。但這個中介層擺在哪裡，決定了它各自解掉多少。

服務數少、backend 單一且穩定時，應用直送 backend 是合理起點 — 上述三個代價在小規模下可控。Collector 是規模化後的升級：當 backend 要換、服務數成長到 enrichment 要統一、或 sampling 需求出現時，再引入 collector 補這一層。

核心概念：三種部署位置的責任分工

Collector 的部署位置分三種，差別在「離應用多近」與「聚合多少來源」。

Agent 模式把 collector 跟應用程式放在同一個 host 或同一個 K8s node（DaemonSet）。它的責任是做 local buffer 與 host 層 enrichment：應用透過 localhost 把 telemetry 吐給同機的 collector，延遲極低、不跨網路；collector 補上 host name、container id 這類只有在本機才知道的 resource attribute。agent 的價值是「離應用最近」，應用送出 telemetry 後就不必管後續，buffer 與重試由同機 collector 承擔。

Agent 解了「離應用近、不丟資料」的問題，但它只看得到本機 — 需要全域視野的處理放不進去。Gateway 模式補這一塊：把 collector 集中部署成一個獨立的服務叢集，跨多個 agent 或多個應用接收 telemetry，負責需要全域視野的處理：tail-based sampling（要看完整 trace 才決定採不採）、跨來源的 routing（不同 telemetry 送不同 backend）、集中的 rate limit 與成本控制。gateway 的價值是「集中決策」，把只有匯流後才做得到的處理放在這一層。

Sidecar 模式在 K8s 把 collector 當成跟應用 pod 同生命週期的 sidecar container。它的責任跟 agent 相似（local buffer、pod 層 enrichment），差別在隔離粒度是 pod 而非 node：比 DaemonSet agent 更貼近單一 pod（共享 pod 網路、隨 pod 起停），適合需要 pod 級獨立配置或強隔離的場景，代價是每個 pod 都多一份 collector 的資源開銷。

常見部署是兩層組合：agent（DaemonSet）做 local buffer + host enrichment，再把資料送到 gateway 叢集做 tail sampling 與 routing。agent 解掉「離應用近、不丟資料」，gateway 解掉「需要全域視野的處理」，兩層各司其職。

pipeline 模型：receivers / processors / exporters

不論擺在哪個位置，collector 的內部都是同一個 pipeline 模型：telemetry 從 receivers 進來、經過 processors 加工、由 exporters 送出。三者用 service.pipelines 依訊號類型（traces / metrics / logs）串接。以下是最小可驗證配置，三個區塊（receivers / processors / exporters）對應 pipeline 的三個階段，各自職責在後面逐段說明。這份配置在 docker 驗證過可正常啟動並端到端流通（validate --config 回傳 0、送 5 條 trace 後 debug exporter 完整輸出 spans）：

 1receivers:
 2  otlp:
 3    protocols:
 4      grpc:
 5        endpoint: 0.0.0.0:4317
 6processors:
 7  memory_limiter:
 8    check_interval: 1s
 9    limit_mib: 256
10    spike_limit_mib: 64
11  batch:
12    timeout: 5s
13    send_batch_size: 1024
14exporters:
15  debug:
16    verbosity: detailed
17service:
18  pipelines:
19    traces:
20      receivers: [otlp]
21      processors: [memory_limiter, batch]
22      exporters: [debug]

receivers 定義「資料怎麼進來」，OTLP（gRPC 4317 / HTTP 4318）是標準入口。processors 定義「資料怎麼加工」，順序有意義：memory_limiter 放最前面，先擋住記憶體爆掉；batch 放後面，把零散 span 攢成批次再送，降低下游請求數。此處 256 / 64 MiB 是 demo 用量，production 應依 container memory limit 按比例設定（常見做法是 limit_mib 設為 container memory 的 80%、spike 設為 limit 的 20-25%）。exporters 定義「資料送到哪」，正式環境會是 OTLP 到 backend 或某 vendor exporter，這裡用 debug 驗證流通。service.pipelines 才是真正生效的接線：只有被掛進某個 pipeline 的元件才會運作，定義了卻沒掛進 pipeline 的元件不生效。

processor 順序是常見踩雷點。memory_limiter 要排在第一個，讓它在資料進入後續 processor 前就有機會審查與拒收；batch 排在它之後，因為如果 batch 先跑，telemetry 會先在 batch processor 累積成大批，等觸發記憶體限制時壓力已經更高、拒收效果下降。需要 sampling 時，head sampling 可以放 agent 層的 pipeline，tail sampling 必須放 gateway 層（它要匯流完整 trace），且同一 trace 的所有 span 要路由到同一個 gateway 實例（用 trace-id 維度的 load balancing exporter），否則各 gateway 節點各看片段、tail 決策仍不完整。

Production 故障演練

Collector 失效的影響面取決於部署模式，這是選位置時要先想清楚的。agent 模式下，單一 node 的 collector 掛掉只影響該 node 的應用，且應用送往 localhost 失敗可以 fail-fast；gateway 模式下，gateway 叢集掛掉會影響所有上游 agent，因此 gateway 必須多副本 + 負載均衡，不能單點；sidecar 模式下，失效影響面比 agent 更窄（只影響同 pod 的應用），但每個 pod 各自是獨立失效點，pod 數多時同時出狀況的機率也高。演練時要分別注入「單 agent 掛」與「gateway 叢集不可用」，確認前者影響被局限、後者有 agent 層 buffer 兜著。

記憶體壓力是 collector 最常見的故障。telemetry 流入速度超過 exporter 送出速度時，資料在 collector 內累積、記憶體上升，沒有保護會 OOM 被 kill、整段 telemetry 全丟。memory_limiter processor 是這道防線，它定期（check_interval）檢查記憶體並用兩個閾值分級反應：記憶體超過軟上限（limit_mib 減去 spike_limit_mib）時強制觸發 GC 並開始拒收，給回收一個緩衝區間；超過硬上限（limit_mib）時全面拒收新資料。只設 limit_mib、不設 spike_limit_mib 是不完整的配置，等於沒有軟性緩衝、直接撞硬牆。演練時用高於 exporter 吞吐的速率灌資料，確認 memory_limiter 在軟上限就介入、collector 存活，而不是 OOM。

Backpressure 的傳遞要驗證到底。當 backend 變慢、exporter queue 滿，collector 的 OTLP receiver 會回壓給上游（gRPC 層用 resource-exhausted 拒收）。在 agent 模式這個回壓會傳到應用的 OTLP exporter，應用 SDK 的 queue 也會滿——此時 SDK 的反應取決於 exporter 配置，要確認 queue-full 策略設為 drop 而非 block，讓 telemetry 被丟棄而非阻塞業務執行緒（各語言 SDK 預設不同，不能假設一定是 drop）。演練要確認「backend 慢 → collector 回壓 → 應用丟 telemetry 但業務不受影響」這條鏈成立，避免觀測系統的壓力反噬主流程。

Capacity / cost 邊界

agent 與 gateway 的成本曲線不同，選型要對著規模看。agent（DaemonSet）的成本是「每個 node 一份 collector」的固定開銷：node 多時總開銷隨 node 數線性成長，但每份 collector 只處理本機流量、單份負載可控。gateway 的成本是「集中叢集」：份數少但每份要扛匯流後的總流量，要按總 telemetry 吞吐量做容量規劃與水平擴展。

兩層架構的成本判讀是：agent 層用最小配置（夠做 buffer + enrichment 即可，limit_mib 設小），把重處理（tail sampling、大量 routing）集中到 gateway，讓 gateway 的擴展跟總流量綁定、agent 的開銷跟 node 數綁定。把 tail sampling 誤放在 agent 層是常見的成本錯誤——agent 看不到完整 trace、做不了正確的 tail sampling，還白白吃掉每個 node 的記憶體。

gateway 層的 processor 是攔截高 cardinality attribute 的有效位置：在 telemetry 流入 backend 前用 attributes / transform processor 把高 cardinality label（user id、request id 當 metric label）移除或降維，比讓它流到 backend 後才治理便宜。高 cardinality 的 attribute 會在下游 backend 炸開成本，是另一條要在 collector 攔截的成本線。這條跟 4.7 Cardinality 治理與成本邊界 對齊。

整合 / 下一步

Collector 部署模式是 OTel 落地的第一個決策，它的下游是 sampling 策略與 backend 選型。決定了 agent + gateway 兩層後，tail sampling 的設計接到 gateway 層的 pipeline；exporter 指向哪個 backend 則回到 何時改走其他服務 的 vendor portability 判讀。

pipeline 的訊號治理與資料品質回到 4.11 Telemetry Pipeline 架構 與 4.17 Telemetry Data Quality；cardinality 攔截回到 4.7 Cardinality 治理與成本邊界。

相關連結

• OpenTelemetry 服務頁
• 4.11 Telemetry Pipeline 架構
• 4.7 Cardinality 治理與成本邊界
• 4.3 tracing 與 context link

四層防線

每一層在不同規模觸發，由近到遠依序啟用。前一層能擋住的流量不需要啟用後一層。本章的四層按防線位置劃分（SDK / Collector / 基礎設施兩層）。DevOps 的規模分級應對表按 events/sec 量級劃分（Tier 1-4），兩者視角不同但覆蓋相同的擴展路徑。

第一層：SDK 端的流量控制

流量控制的最有效位置是事件產生的源頭。SDK 端減少的事件量，後面每一層都不需要處理。

動態取樣

SDK 在收到 collector 的 HTTP 429（Too Many Requests）回應時，自動降低取樣率。恢復正常後逐步回升。

1正常 → sampling 1.0
2收到 429 → sampling 降到 0.5
3持續 429 → sampling 降到 0.1
4連續 10 次成功 → sampling 回升到 0.5
5連續 30 次成功 → sampling 回到 1.0

動態取樣的控制邏輯在 SDK 端實作，不需要 collector 端額外支援 — 429 回應碼就是觸發訊號。和感測器生命週期管理的靜態取樣率互補 — 靜態取樣在 config 中設定、動態取樣在執行期自動調整。

聚合前移

SDK 端累積一段時間的同名事件，送出摘要而非逐筆。適合 metric 類的高頻取樣。

例：原本每 100ms 送一筆 render.frame_drop，改成每 5 秒送一筆 render.frame_drop_summary（帶 count + min + max + avg）。事件數從 50 筆/5s 降到 1 筆/5s。

聚合前移犧牲事件粒度換取吞吐量。只適合「趨勢比每筆細節重要」的 metric 類事件。Error 和 lifecycle 事件不做聚合 — 每筆的 stack trace 和狀態轉換都有 debug 價值。

優先級丟棄

SDK 的離線 buffer 滿時，按優先級丟棄。Error 的 debug 價值最高，最後丟。

第二層：Collector 單機的防護

Collector 在自身能力範圍內保護自己不被壓垮。和 architecture.md 的並發寫入策略直接相關 — 寫入 channel 是背壓的實作基礎。背壓和流量管控的通用概念見 DevOps 流量管控。

寫入 channel 容量 + 背壓

Single-writer goroutine pattern 的 Go channel 有固定容量（如 10,000）。Channel 滿時 HTTP handler 無法送入事件，此時回 429：

1select {
2case writeCh <- event:
3    w.WriteHeader(http.StatusAccepted) // 202
4default:
5    w.Header().Set("Retry-After", "5")
6    w.WriteHeader(http.StatusTooManyRequests) // 429
7}

Channel 容量的設定依據：容量 × 每筆事件的記憶體大小 = 背壓 buffer 的記憶體上限。10,000 筆 × 每筆 ~1KB = ~10MB，對多數機器微不足道。

Per-SDK rate limiting

按 source.app（或 API key，啟用認證後）限制每個 SDK 實例的請求速率。防止單一 SDK 的 bug（無限迴圈送事件）打爆 collector。

1// 每個 source.app 一個 rate limiter
2limiter := rateLimiters.GetOrCreate(sourceApp, rate.Limit(100)) // 100 events/sec
3if !limiter.Allow() {
4    w.WriteHeader(http.StatusTooManyRequests)
5    return
6}

Error 快通道

Error 事件不經 rate limit — 它們的 debug 價值最高，且在正常情況下數量遠少於其他類型。Error storm（app 出 bug 導致大量 error）時，error 的量可能暴增，但這正是最需要記錄的時刻。

Error 快通道用獨立的 channel 或跳過 rate limiter 的 check。如果 error 量也超出承載，用第一層的 SDK 端優先級丟棄處理。

第三層：水平擴展

單機的 CPU、記憶體或網路頻寬飽和時，水平擴展 — 多個 collector 實例分攤流量。水平擴展的通用模式見 DevOps 水平擴展。

前提：已切換到 PostgreSQL

SQLite backend 不支援水平擴展。每個 collector 實例有各自的 SQLite 檔案，無法合併查詢。水平擴展的前提是所有 collector 寫入同一個 PostgreSQL。

架構

 1SDK ──→ Load Balancer (nginx / HAProxy)
 2             │
 3        ┌────┴────┐
 4        ▼         ▼
 5   Collector A  Collector B
 6        │         │
 7        └────┬────┘
 8             ▼
 9        PostgreSQL
10             │
11             ▼
12         Dashboard

Collector 實例是 stateless 的 — 不在記憶體保存查詢狀態，所有持久化資料在 PostgreSQL。任何 collector 接收的事件都能被任何 dashboard 查到。

Load balancer 用 round-robin 或 least-connections 分配。不需要 sticky session — collector 不保存 session 狀態。

多機的 Downsample 和 Purge

Downsample 和 Purge job 只能由一個 collector 實例執行（避免重複處理）。用 PostgreSQL 的 advisory lock 或外部的 distributed lock 確保單一執行者。

第四層：Queue 解耦

突發流量超過 collector 群的即時處理能力時，在 collector 和 storage 之間插入 message queue 做緩衝。Queue 緩衝的通用概念見 DevOps 突發流量應對，message queue 的選型見 Backend 模組三 非同步與訊息佇列。

架構

 1SDK ──→ Collector (ingestion only)
 2             │
 3             ▼
 4        Queue (Kafka / NATS / Redis Streams)
 5             │
 6        ┌────┴────┐
 7        ▼         ▼
 8    Worker A   Worker B
 9        │         │
10        └────┬────┘
11             ▼
12        PostgreSQL

Collector 的職責簡化為「接收 → 驗證 → 寫入 queue → 回 202」。寫入 queue 比寫入 DB 快得多（append-only、不需要索引更新），collector 的吞吐上限大幅提升。

Worker 從 queue 消費、寫入 PostgreSQL。Worker 按自己的速度處理 — 高峰時 queue 積壓，高峰過後 worker 消化積壓。Queue 的持久化保證事件不遺失。

Queue 的選擇

自架監控工具的 queue 層級推薦 NATS JetStream — Go 原生 client、單 binary 部署、JetStream 提供持久化和 replay。

觸發條件

Queue 解耦的引入時機是「collector 群已水平擴展但仍無法處理突發流量」。如果日常流量 collector 群能處理，只有行銷活動 / 新聞曝光的短暫高峰需要 queue 緩衝，queue 的維護成本可能高於收益 — 考慮用第一層的動態取樣在源頭降量。

功能分層整合

擴展 功能分層與 Backend 選擇 的分層表，加入 ingestion 維度：

每一層是前一層的超集 — Queue 層包含 PostgreSQL 層的所有查詢能力，加上 ingestion 的 queue 緩衝。

下一步路由

• Collector 的並發寫入策略 → Collector 架構
• Storage 端的擴展設計 → 規模演進
• 功能分層的定義 → 功能分層與 Backend 選擇
• 背壓和流量管控的通用概念 → DevOps 流量管控
• 水平擴展的通用模式 → DevOps 水平擴展
• 突發流量應對 → DevOps 突發流量
• Message queue 選型 → Backend 模組三 非同步與訊息佇列
• 端到端資料完整性（資料損失地圖、完整性指標）→ 端到端資料完整性

寫入吞吐

寫入吞吐決定 collector 每秒能消化多少事件。SQLite 的寫入效能主要受 fsync 頻率和 WAL checkpoint 影響。

單筆 INSERT

每筆 INSERT 獨立一個 transaction 時，每次 commit 都會 fsync。WAL mode 的 fsync 成本比 journal mode 低（append-only），但仍是寫入的主要瓶頸。

modernc.org/sqlite（pure Go）的效能約為 CGO driver（mattn/go-sqlite3）的 60-80%。上表數字基於 CGO driver，pure Go 需打八折。Go HTTP handler 的開銷（JSON 解碼、schema 驗證、goroutine 調度）再扣 10-20%。

批次 INSERT

一個 transaction 包裹多筆 INSERT，只做一次 fsync。Collector 接收 SDK 的 flush batch（一個 HTTP request 帶一批事件）天然適合批次寫入。

吞吐提升幅度和批次大小的關係：

提升來自 fsync 次數從「每筆一次」降到「每批一次」。超過 100 筆/tx 後邊際收益遞減。

實際預期

結合 pure Go driver、HTTP handler 開銷和批次寫入，不同環境下的預期吞吐：

和事件產生速率的對照

burst 和持續的差異在於：burst 是短暫的高峰（flush batch 到達後數秒內消化完），持續是長時間的穩定高流量。SQLite 的 WAL mode 對 burst 容忍度高（write lock 等待時間短），對持續高流量容忍度有限（write lock 等待累積）。

查詢延遲

查詢延遲決定 dashboard 的刷新體驗。SQLite 的查詢效能取決於索引覆蓋和掃描行數。

有索引的查詢

建議的索引（見 規模演進 的建議索引段）覆蓋 dashboard 的核心查詢模式。有索引時的預期延遲：

無索引的查詢

無索引時 SQLite 做全表掃描。掃描速度約 50-100 MB/sec（SSD）、10-30 MB/sec（HDD）。

超過 100 萬筆無索引查詢會超出 dashboard 可接受的刷新延遲 — 這是 day-one 就建索引的理由。

Dashboard 刷新頻率 vs 查詢延遲

Dashboard 的每個視圖有不同的刷新間隔和可接受延遲。查詢延遲超過可接受值時，dashboard 體驗變差（等待轉圈、資料過時）。

「需要預聚合」代表原始事件的聚合查詢超過可接受延遲，應該依賴分層保留策略中的 hourly_summary / daily_summary 表（見 規模演進 的分層保留段）。

資源消耗

記憶體

Raspberry Pi（1 GB RAM）上建議把 page cache 調小（PRAGMA cache_size = -512 = 512 KB），避免大結果集查詢（加 LIMIT），dashboard 刷新頻率降低。

CPU

磁碟

WAL 檔案通常 < 10 MB（auto-checkpoint 在 WAL 達到 1000 pages 時觸發）。分層保留策略下，原始事件只保留 7 天，長期佔用由聚合摘要表決定（遠小於原始事件）。

邊緣設備場景

Raspberry Pi、低配 VPS（1 核 / 1 GB RAM）、甚至 NAS 上跑 collector 時的特殊考量：

SD card 的隨機寫入：SD card 的隨機寫入 IOPS 極低（100-500 IOPS），WAL mode 的 checkpoint（把 WAL 內容合併回主資料庫檔案）可能卡住 1-5 秒。期間新的寫入等待 checkpoint 完成。建議調高 wal_autocheckpoint 的閾值（如 5000 pages），讓 checkpoint 頻率降低但每次時間更長 — 在非活躍時段（凌晨）手動觸發 PRAGMA wal_checkpoint(TRUNCATE)。

1 GB RAM：cache_size 調小（512 KB）、避免 SELECT * 不帶 LIMIT、GROUP BY 的結果集用 HAVING 條件過濾減少暫存。Dashboard 的長期聚合直接查 hourly_summary 表而非原始事件。

ARM CPU：pure Go SQLite driver（modernc.org/sqlite）在 ARM 上的效能差距可能比 x86 更大（pure Go 的 C-to-Go 翻譯在 ARM 的指令最佳化較少）。實測確認。

建議配置：邊緣設備上 collector 的 dashboard 刷新頻率從預設值降低（即時狀態卡 5 秒 → 30 秒，趨勢圖 30 秒 → 5 分鐘），降採樣 job 頻率從每小時改為每 6 小時。

實測方法指引

教學的預期數字是推導值，實際效能取決於使用者的硬體和 workload。Collector 提供內建的 benchmark 命令讓使用者在自己的環境實測。

寫入 benchmark

1# 單筆寫入：10000 筆，每筆獨立 transaction
2./collector benchmark write --events=10000 --batch=1 --storage=sqlite
3
4# 批次寫入：10000 筆，每 100 筆一個 transaction
5./collector benchmark write --events=10000 --batch=100 --storage=sqlite

輸出：total duration、events/sec、p50/p95/p99 latency per event。

查詢 benchmark

1# 先灌入測試資料
2./collector benchmark seed --events=100000 --storage=sqlite
3
4# 跑查詢 benchmark
5./collector benchmark query --type=error --group-by=name --storage=sqlite
6./collector benchmark query --session-id=random --storage=sqlite

輸出：query duration、rows scanned、rows returned。

Production 觀察指標

部署後用 DevOps dashboard（見 DevOps Dashboard 設計）觀察 collector 自身的效能 metric：

• collector.storage.write_duration_ms：每次寫入的延遲。P95 超過 100ms 是瓶頸訊號。
• collector.storage.query_duration_ms：每次查詢的延遲。P95 超過 dashboard 刷新間隔是瓶頸訊號。
• collector.storage.db_size_bytes：資料庫大小。接近磁碟可用空間的 80% 時觸發 purge 或擴容。
• collector.storage.wal_size_bytes：WAL 檔案大小。持續 > 50 MB 代表 checkpoint 跟不上寫入速度。

下一步路由

• 切換到 PostgreSQL 的觸發條件 → 規模演進
• SQLite 和 PostgreSQL 的功能分層 → 功能分層與 Backend 選擇
• Ingestion 端的擴展設計 → Ingestion Scaling

讀寫競爭的具體場景

Monitor 的 PostgreSQL 層同時承擔三種負載，各自的資源消耗特性不同。

寫入負載

SDK flush 是 Monitor 的主要寫入來源。多個 SDK 同時 flush 時，collector 透過連線池並行寫入 PostgreSQL。每筆 INSERT 涉及主表寫入 + 索引更新（idx_type_ts、idx_session、idx_name）。寫入量隨 SDK 數量和 flush 頻率線性成長。

Downsample job 是另一種寫入：定期把原始事件聚合到 hourly_summary / daily_summary。Downsample 執行時同時做大量 SELECT（讀原始事件）和 INSERT（寫摘要），佔用連線和 I/O。

Dashboard 讀取負載

Dashboard 是穩定的高頻背景負載。總覽頁每 30 秒刷新、Error 列表每分鐘刷新、趨勢圖每分鐘重算。每次刷新執行一到多個聚合查詢（GROUP BY name、COUNT(*)、時間分桶）。

Dashboard 查詢的掃描量隨資料累積成長。「過去 7 天每小時的 error 數量」在第一週掃描幾千筆，三個月後掃描幾十萬筆。如果沒有用 hourly_summary 摘要表、而是直接查原始 events 表，查詢時間會隨資料量線性增加。

Debug 即席讀取負載

Debug 查詢是偶發的突增負載。開發者在排查問題時，可能用 session_id 拉出整條事件鏈、用 error name 掃描最近 N 筆 stack trace、或用 data->>'duration_ms' 做 ad-hoc 效能分析。這些查詢的特徵是不可預測、偶發但延遲敏感 — 開發者在等結果。

競爭發生在哪

三種負載打同一個 PostgreSQL 時，競爭集中在兩個資源：

連線池：collector 的 SetMaxOpenConns 是固定值（例如 20）。如果 ingestion 佔用 15 條連線做批次 INSERT、dashboard 需要 3 條做聚合查詢、debug 需要 2 條做 ad-hoc 查詢 — 剛好佔滿。這時 downsample job 啟動需要連線，會排隊等待。

I/O 頻寬：聚合查詢需要掃描大量資料（sequential scan 或 index scan + heap access），跟 INSERT 的隨機寫入搶磁碟 I/O。在 HDD 或低階 SSD 上，一個 heavy 聚合查詢可以讓同時進行的 INSERT latency 從毫秒跳到十毫秒。

鎖競爭：PostgreSQL 的 MVCC 讓 SELECT 跟 INSERT 不互相阻塞（reader 不等 writer），但 Downsample 的 INSERT OR REPLACE 跟 ingestion 的 INSERT 可能在同一張表上競爭 row-level lock。長時間的 aggregation query 也可能觸發 idle in transaction 問題，佔住連線不釋放。

辨識訊號

讀寫競爭的辨識訊號是「寫入跟讀取的效能同時退化，而且退化是交互的」：

• Ingestion 的 INSERT latency 在 dashboard 刷新時段（每 30 秒）出現週期性尖峰
• Dashboard 的聚合查詢在 SDK 高峰 flush 時段（例：每整點、app 啟動潮）變慢
• Debug 即席查詢在 downsample job 執行期間 timeout
• PostgreSQL 的 pg_stat_activity 顯示多個 idle in transaction 或 waiting 狀態
• 連線池使用率持續高於 80%，偶發 too many connections 或連線等待

單純的寫入慢（沒有讀取影響）或單純的查詢慢（沒有寫入影響）不是讀寫競爭，可能是索引缺失或查詢效率問題。讀寫競爭的特徵是「兩邊同時退化、一邊忙的時候另一邊也變慢」。

Read Replica 分離

Read replica 是 Monitor 在 PostgreSQL 層後的第一步讀寫分離。概念簡單：寫入走 primary、讀取走 replica，兩者物理隔離。

架構

 1SDK ──→ Collector
 2             │
 3        ┌────┴──────────┐
 4        ▼                ▼
 5   Primary (write)   Replica (read)
 6        │                │
 7        │  replication →  │
 8        │                │
 9        ▼                ▼
10   Ingestion        Dashboard + Debug
11   Downsample       聚合查詢

Collector 持有兩個連線池 — 一個連 primary（用於 Store()、Downsample()、Purge()），一個連 replica（用於 Query()、Aggregate()、Dashboard 的所有讀取）。

Storage interface 的調整

現有的 BasicStorage interface 不需要改動。實作層在初始化時接收兩個 DSN（primary + replica），內部根據操作類型選擇連線池：

1type PostgresStorage struct {
2    primary *sql.DB  // write operations
3    replica *sql.DB  // read operations (nil = use primary)
4}

當 replica DSN 未設定時，所有操作走 primary — 行為跟目前一樣，不破壞 single-instance 部署。

Replica lag 對各查詢場景的影響

PostgreSQL streaming replication 的 lag 在同 AZ 通常 < 100ms，跨 AZ 可能到秒級。各查詢場景對 lag 的容忍度不同：

Debug 即席查詢的 lag 問題是 read-after-write 一致性 — 開發者從 SDK 送出 test event 後立刻查詢，如果查 replica 可能還沒同步到。解法是讓 debug query API 提供 consistency=strong 參數，強制走 primary。預設走 replica（大部分 debug 查的是歷史資料），只有需要 read-after-write 時切 primary。

引入時機

Read replica 的引入時機是「辨識訊號」段列出的讀寫競爭訊號持續出現，而且已經做過基本最佳化（索引補齊、dashboard 改讀 summary 表、downsample job 調整執行時段避開高峰）仍然不夠。

引入 read replica 的成本是多一台 PostgreSQL 實例（或 managed service 的 read replica 選項）和 replication 設定。Monitor 的 PostgreSQL 層已經承擔外部 DB 的運維成本，加 replica 是增量而非從零開始。

預聚合作為讀取面的第一道防線

在引入 read replica 之前，預聚合是降低讀取負載最有效的方式 — 不改架構、不加機器、只改查詢的資料來源。

Monitor 已經有 hourly_summary 跟 daily_summary 兩張摘要表（見 規模演進）。Dashboard 的趨勢圖跟 Error 計數應該讀摘要表而非原始 events 表。

預聚合沒處理到的讀取負載是「需要原始事件的查詢」— Debug 即席查詢（看 stack trace）、Session 回放（看事件序列）、Funnel 分析（跨 session JOIN）。這些查詢必須掃描原始資料，預聚合無法取代。當這類查詢的負載開始擠壓寫入時，才是引入 read replica 的時機。

概念上，預聚合就是 recording rule 在關聯式資料庫的實作。Downsample job 定期執行 aggregation query、把結果寫入 summary 表，dashboard 讀 summary 表而非重算 raw data。Monitor 的 hourly_summary 等同於 Prometheus 的 recording rule output、PostgreSQL 的 materialized view 等同於 TSDB 的 continuous aggregate。

CQRS 的判讀訊號

Read replica 解決的是「讀寫搶同一台機器的 I/O 跟連線」。當問題不只是資源競爭、而是讀寫的資料形狀根本不同時，read replica 不夠 — 需要獨立的 read model。

CQRS 的完整概念見知識卡。以下是 Monitor 情境下，什麼訊號出現時該考慮從 read replica 往 CQRS 方向演進。

訊號一：讀取需要的資料形狀跟 events 表差異太大

Monitor 的 events 表是 append-only 的正規化結構（一筆事件一個 row）。如果讀取面需要的是：

• 每個 user 的行為摘要（最近登入、最常用功能、累計 error 數）— 需要跨所有事件聚合成 per-user profile
• 即時的 error fingerprint 索引（相同 stack trace 的 error 自動分群、計數、追蹤首次出現時間）— 需要維護一張反正規化的 error group 表
• 跨 session 的 funnel conversion 快照 — 需要維護一張 pre-computed funnel 表

這些讀取形狀無法用 SELECT FROM events + 索引高效產生，需要獨立的 read model 持續從 events 推算。

訊號二：預聚合的種類和刷新頻率失控

Summary 表從 2 張（hourly + daily）增長到 5 張、10 張，每張的刷新頻率從每小時變成每分鐘。Downsample job 的執行時間從秒級增長到分鐘級，開始擠壓 ingestion。

這時候 summary 表已經不只是「摘要」，而是事實上的 read model — 專門為讀取需求設計的獨立資料結構。承認這個事實、把 summary 表的維護從 Downsample job 拆出來成為獨立的 projection consumer，就是進入 CQRS 的起點。

訊號三：讀取跟寫入需要獨立擴展

寫入量穩定（SDK 數量不變），但讀取面因為新增 dashboard、新增分析維度、新增使用者而持續成長。Read replica 可以加多台分攤讀取，但每台 replica 仍然存的是跟 primary 一樣的 events 表結構 — 讀取查詢的複雜度不變，只是分攤到更多機器。

獨立的 read model 可以用完全不同的 schema（反正規化、pre-joined、pre-aggregated），讓讀取查詢從 O(N) 的聚合變成 O(1) 的 lookup。這是 CQRS 的核心價值 — 讀取面的效能不再受限於寫入面的資料結構。

Monitor 目前的位置

Monitor 目前在「SQLite → PostgreSQL → Read Replica」這條路徑的前半段。MVP 用 SQLite、功能需求觸發 PostgreSQL、讀寫競爭觸發 Read Replica。CQRS 是更遠的演進方向，只有上述三個訊號明確出現時才值得引入。

1SQLite（零依賴）
2  → PostgreSQL（聚合分析觸發）
3    → 預聚合 summary 表（讀取負載觸發）
4      → Read Replica（讀寫競爭觸發）
5        → 獨立 read model / CQRS（資料形狀不對稱觸發）

每一步都是被具體的效能訊號或功能需求推動的，跟 Monitor 整體的「按觀察到的瓶頸切換」原則一致。教學的價值在於讓讀者在每一步都知道「下一步是什麼、什麼訊號出現時該走」— 而不是在 SQLite 階段就預先設計 CQRS。

跟 Backend 的概念對照

Monitor 的讀寫分離路徑跟 backend 教材的概念有直接對應：

Monitor 的規模演進路徑是 backend 概念的具體實例 — 從自用工具到小型服務、從單機到讀寫分離、從 summary 表到可能的 CQRS，每一步都能回到 backend 教材找到概念基礎。

下一步路由

• Storage backend 的可插拔架構 → 規模演進
• 功能分層的定義 → 功能分層與 Backend 選擇
• Ingestion 端的流量防線 → Ingestion Scaling
• 讀寫分離的通用概念 → CQRS 知識卡
• 資料庫層的讀寫分離設計 → 1.8 State Ownership 與 Query Boundary
• 觀測領域的讀取路徑設計 → 4.23 觀測查詢設計

Dockerfile 設計

Multi-stage build 把編譯環境和執行環境分離。Build stage 用 Go 官方 image 編譯 binary，runtime stage 只包含 binary 和必要的 CA 憑證。

 1FROM golang:1.22-alpine AS build
 2WORKDIR /src
 3COPY go.mod go.sum ./
 4RUN go mod download
 5COPY . .
 6RUN CGO_ENABLED=0 go build -o /collector ./cmd/collector
 7
 8FROM alpine:3.20
 9RUN apk add --no-cache ca-certificates tzdata
10COPY --from=build /collector /usr/local/bin/collector
11RUN adduser -D -u 1000 monitor
12USER monitor
13EXPOSE 8080
14ENTRYPOINT ["collector"]

最終 image 包含 Go binary（~15MB）+ alpine base（~7MB）+ ca-certificates，總大小目標 < 25MB。用 scratch 替代 alpine 可以再小 7MB，但失去 shell debug 能力。

SQLite 在 Container 中的 I/O 考量

Docker 的 overlay2 storage driver 在每次 fsync 時經過 overlay 層。SQLite 的 WAL mode 依賴 fsync 確保寫入持久性 — 每筆 transaction commit 觸發一次 fsync。Overlay 層增加的延遲讓每筆 fsync 慢 20-40%（取決於 host 的 storage driver 和檔案系統）。

Volume mount 繞過 overlay

把 SQLite 的資料目錄掛載為 host volume（-v /host/data:/data），SQLite 直接寫 host 檔案系統、繞過 overlay 層。寫入效能和同機部署的 binary 版本相當。

不用 volume mount 的風險：container 刪除時 overlay 層的資料一起消失。docker rm = 所有事件資料消失。即使只是 docker run 新版本的 image 也會建立新 container，舊 container 的資料不會自動遷移。

Volume Mount 設計

兩個目錄分開掛載，職責和權限不同：

Container 內用非 root user（UID 1000）執行。Host 的 volume 目錄 ownership 需要對應：

1mkdir -p monitor-data monitor-config
2chown 1000:1000 monitor-data

Graceful Shutdown

docker stop 送 SIGTERM → collector 收到後執行 shutdown 序列：

1. 停止接受新的 HTTP request（listener close）
2. 等待 in-flight request 完成（5 秒 context timeout）
3. Flush pending writes（尚未寫入 storage 的事件，5 秒）
4. 停止定期 job（downsample / purge / rule engine 定期評估）
5. SQLite WAL checkpoint（TRUNCATE mode，15 秒）
6. 關閉 DB connection
7. 退出

步驟 2-5 合計超時上限 25 秒。這個序列對應 Backend 5.6 Platform Lifecycle Contract 的 shutdown → drain 狀態：步驟 1-2 是 drain（停接新工作、等在途完成），步驟 3-6 是 shutdown（flush 狀態和釋放資源）。Collector 屬於短 request API 的 workload 類型（drain 窗口 5-30 秒），但多了 WAL checkpoint 步驟，讓 shutdown 時間可能超過一般 HTTP 服務。PID 1 信號處理的設計考量（exec form、避免 shell 攔截 SIGTERM）見 Backend 5.1 PID 1 與信號處理。

docker stop 預設等 10 秒後送 SIGKILL。如果 WAL checkpoint 在大量未 checkpoint 的資料下需要超過 10 秒，Docker Compose 可以調 stop_grace_period: 30s。

SQLite 的 WAL 設計支援 crash recovery — SIGKILL 後 WAL 檔案仍在，下次開啟 DB 時自動 replay。但非 graceful shutdown 可能丟失 channel 中尚未寫入的事件（已收到 HTTP 202 但還在 buffer 中的事件）。

資源限制

Memory 限制設太緊會觸發 OOMKill — container 突然消失且無 log。設定 memory limit 前先觀察 collector 的 baseline 記憶體使用（docker stats），再乘以 1.5 安全係數。CPU request/limit 的設定策略（guaranteed vs burstable QoS）和 memory limit 與 OOM 的判讀見 Backend 5.1 Resource Limit。

Docker Compose 範例

 1services:
 2  collector:
 3    image: tarrragon/monitor:latest
 4    ports:
 5      - "8080:8080"
 6    volumes:
 7      - ./monitor-data:/data
 8      - ./monitor-config:/config:ro
 9    environment:
10      - MONITOR_STORAGE=sqlite
11      - MONITOR_DB_PATH=/data/events.db
12    restart: unless-stopped
13    stop_grace_period: 30s
14    deploy:
15      resources:
16        limits:
17          memory: 256M
18          cpus: '0.5'
19    healthcheck:
20      test: ["CMD", "wget", "-q", "--spider", "http://localhost:8080/health"]
21      interval: 30s
22      timeout: 5s
23      retries: 3

restart: unless-stopped 讓 container 在 crash 或 host 重啟後自動恢復。healthcheck 讓 Docker 偵測 collector 是否真的在回應 — 只有 process 活著但 HTTP 不回應的場景也會被標記為 unhealthy。

和同機部署的效能對照

Volume mount 後效能差異只有 ~10%（Go HTTP handler 的 overhead 大於 volume mount 的 overhead）。不用 volume mount 時 overlay fs 的 fsync 開銷顯著 — 寫入吞吐降 40%。

何時用 container、何時用 binary

斷網環境的部署考量

Collector 在斷網環境（air-gapped）裡的部署跟連網環境的主要差異有三點。第一，SDK 的 endpoint 從外部 URL（https://collect.example.com）改為內網地址（http://collector.internal:8080），SDK 設定檔裡的 endpoint 要能按環境切換。第二，Collector 的 container image 無法從 Docker Hub 拉取——需要透過 content ferry 搬運映像、推送到內網的 private registry（Harbor 或 Docker Registry），Dockerfile 的 base image 來源也要改指 private registry。第三，Collector 的 storage backend 只能用本地磁碟或 NFS，不能用雲端物件儲存——SQLite backend 在斷網環境反而是優勢（零外部依賴），儲存容量規劃要在部署前就確定，因為斷網環境的磁碟擴容流程可能需要數週。

SDK 的 offline buffer（見SDK 設計：offline-buffer）在斷網環境更重要——如果 Collector 重啟或暫時不可達，SDK 端的 buffer 是唯一能保住事件的機制。

斷網環境的 infra 層監控（Prometheus / Grafana / Loki）設定見斷網環境的監控與可觀測性。

下一步路由

• SQLite 效能基準的詳細數字 → SQLite Backend 效能基準
• 可插拔 Storage Backend 架構 → 規模演進
• Container runtime 通用原則（base image 選擇、build 可重現性、PID 1 信號處理）→ Backend 5.1 Container 與 Runtime
• 生命週期合約（startup / readiness / drain / shutdown 的責任分類）→ Backend 5.6 Platform Lifecycle Contract
• 容器化資源設計的通用原則 → DevOps 容器化資源設計
• 服務探活和自動恢復 → DevOps 服務探活

監控資料和交易資料的根本差異在這裡：交易資料的損失會直接造成商業損害（少了一筆訂單），監控資料的損失影響的是可觀測性的覆蓋率（少了幾筆 event 不影響趨勢判斷，但漏了 error 可能讓 bug 晚幾天被發現）。這個差異決定了完整性設計的方向 — 追求的是「損失可控且可觀測」，而非「零損失」。合規稽核 log、billing event 和安全事件不適用這個假設 — 它們的損失有法規或商業後果，需要 at-least-once delivery 和獨立的持久化保證，通常用 transaction log 而非監控管線處理。

資料損失地圖

一筆事件從產生到持久化，依序經過四個環節。每個環節的損失類型、發生條件和影響範圍各不同。

1事件產生 → [SDK buffer] → HTTP POST → [Collector pipeline] → [Storage]
2     ①          ②            ③              ④                   ⑤

環節一：事件產生階段

事件在 SDK 的 monitor.event() / monitor.error() 被呼叫時產生，進入記憶體 buffer。這個階段的損失來自取樣和 SDK 初始化時序。

靜態取樣：SDK config 中設定的取樣率（例如 metric 類 0.1 = 每 10 筆只收 1 筆）是設計內的損失。取樣後的事件量直接影響後續所有環節的負載。取樣率的設定依據見感測器生命週期管理。

SDK 未初始化：app 啟動後到 monitor.init() 完成之間的事件會被丟棄。如果 init 排在其他初始化邏輯之後，啟動階段的 crash 可能漏捕。商業 SDK（Sentry、Crashlytics）用 native crash handler 在 SDK 層之外攔截這類 crash，自架方案通常接受這個損失。

環節二：SDK buffer 階段

事件進入記憶體 buffer 後，等待 flush 觸發。Buffer 溢出和 app 強制終止是這段路徑上的兩個風險。

FIFO 丟棄：記憶體 buffer 有容量上限（典型值 200-500 筆）。離線時間過長或事件產生速率過高時，buffer 滿了會丟棄最舊的事件。丟棄策略見離線 buffer 與重試，優先級丟棄見 Ingestion Scaling 第一層。

App 強制終止：iOS 的 kill、Android 的 process death、Python 的 SIGKILL — 記憶體 buffer 中未 flush 的事件全部遺失。攢批送出策略的 close flush 嘗試在 app 正常退出時送出剩餘事件，但強制終止時連 close callback 都不會執行。

動態取樣：收到 collector 的 HTTP 429（Too Many Requests，表示 collector 過載）後，SDK 自動降低取樣率（從 1.0 降到 0.5 → 0.1）。這是對 collector 過載的回饋反應 — 損失的事件量隨背壓程度增加。和靜態取樣的差異是動態取樣在正常情況下不生效，只在過載時啟用。

環節三：Transport 階段

SDK flush 時透過 HTTP POST 送出 batch。網路故障和重試耗盡構成 transport 層的主要損失。

HTTP 超時 / 連線失敗：collector 不可達時，batch 保留在 SDK buffer 等待下次 flush 重試。重試次數有上限（3 次），超過後丟棄 batch 並記錄 sdk.flush.dropped metric。重試策略見攢批送出策略。

離線補發擁塞：離線恢復後，SDK 一次補發大量累積事件。如果補發速率過高（一批 500 筆 × 多個 SDK 同時恢復），collector 可能觸發背壓回 429，SDK 又進入動態降採樣 — 補發本身造成新的損失。離線 buffer 與重試的分批補發（每批 50-100 筆、間隔 1-2 秒）用來避免這個問題。

環節四：Collector pipeline 階段

Collector 收到 HTTP request 後，事件進入處理鏈路。背壓、驗證拒絕和 pipeline 內部的 buffer 溢出都可能在這裡造成損失。

Channel 背壓：Collector 內部用一個專屬的寫入 goroutine 搭配 Go channel 做序列化寫入（Collector 架構的並發寫入策略段），channel 有固定容量。Channel 滿時 HTTP handler 回 429，事件被拒絕。SDK 收到 429 後保留事件在 buffer 等待重試，但如果 SDK buffer 也快滿，部分事件會被 FIFO 丟棄。這裡的損失是 SDK 層和 collector 層的連鎖反應 — collector 的背壓壓力最終由 SDK 的 buffer 承擔。

Schema validation reject：事件格式不符合 JSON Schema 的事件被拒絕（400 或 207 中的 rejected 部分）。這是品質閘門而非容量限制 — 被拒絕的事件無論重試多少次都不會通過，SDK 應該清除這些事件並記錄 warning。問題在 SDK 端的事件建構邏輯（程式碼 bug），需要修 SDK 而非重試。

429 後事件已回 202 但未寫入：collector 回了 202（已接受）但事件還在 channel buffer 中未寫入 storage 時，如果 collector crash 或被 SIGKILL，channel 中的事件遺失。這是「已承諾但未持久化」的窗口。Container 部署設計的 graceful shutdown 序列嘗試在 shutdown 時 flush pending writes，但非 graceful shutdown（OOMKill、硬體故障）無法保護。

環節五：Storage 階段

事件從 channel 寫入 storage backend。寫入失敗和資料管理操作（downsample / purge）構成最後一段損失。

SQLite database is locked：busy timeout 到期後寫入失敗。Single-writer pattern 降低發生機率但不能完全消除 — downsample / purge job 執行期間持有 write lock，如果 job 跑太久（數秒以上），ingestion 的寫入可能逾時。

磁碟空間不足：SQLite 寫入需要磁碟空間（WAL 檔案 + 主資料庫 + 臨時檔案）。磁碟滿時寫入失敗，事件遺失。保留策略的 purge job 負責控制磁碟使用量，但如果 purge 頻率低於寫入增長速率，磁碟可能在兩次 purge 之間被填滿。

Downsample / purge 的設計內損失：保留策略到期的原始事件被刪除（purge），只保留聚合摘要（hourly_summary / daily_summary）。這是設計內的損失 — 原始事件的 stack trace、完整 JSON data 在 purge 後不可回復，只剩下計數。保留策略見規模演進的分層保留段。

設計內損失 vs 異常損失

上述損失點可以分成兩類，處理方式根本不同。

設計內損失的目標是讓損失量可控 — 取樣率設 0.1 代表預期丟 90%，FIFO buffer 容量 200 代表離線超過 20 分鐘（每分鐘 10 筆）後開始丟棄。這些數字是 config 參數，可以根據業務需求調整。

異常損失的目標是儘早偵測 — collector crash 後 channel 中有多少筆未寫入？磁碟使用率到多少該告警？下方的完整性指標段專門處理偵測異常損失的方法。

品質閘門的處理在 SDK 端而非 collector 端 — schema validation reject 的事件無論重試多少次都不會通過，問題在事件建構邏輯。具體的 reject 行為和回應格式見環節四的 Schema validation reject 段。

監控損失本身的方法

監控系統的完整性需要「監控自己的監控」— 用獨立的指標追蹤每個環節的進出量，損失量 = 進量 - 出量。

SDK 端指標

SDK 內部維護計數器，每次 flush 成功後一起送出（作為 metric 類事件）：

produced - sampled = 取樣損失（設計內）。sampled - sent - dropped 如果不為零，代表有事件卡在 buffer 中尚未送出或未被計入任何分類。

Collector 端指標

Collector 在 /metrics endpoint（或 health endpoint 的擴展欄位）暴露處理計數器：

received - rejected - stored - backpressure 如果不為零，代表有事件在 pipeline 中遺失（channel buffer 中的事件在 crash 時丟失就會造成這個差距）。

端到端比對

SDK 的 sent 和 collector 的 received 之間的差距是 transport 層的損失 — 網路丟包、中間件攔截（reverse proxy 的 body size limit）或 collector 重啟期間的連線失敗。

這個比對在自用場景下用手動 spot check 就夠（SDK log 的 sent count vs collector dashboard 的 received count）。小型以上規模需要自動化：一個定期 job 比對兩邊的計數器，差距超過閾值時告警。

損失率的可接受範圍

閾值的推導邏輯：event 類的損失影響統計精度 — 取樣率 0.9 加上 transport 和 collector 層的少量損失，自用場景合計 < 10% 是合理的上限；funnel 分析用取樣校正（除以取樣率）仍然有效。Error 類的損失直接影響 bug 發現速度 — 容忍度比 event 低一個數量級。中型以上規模的 < 1% / < 0.1% 接近商業方案（Sentry / Datadog）的 SLA 水準。

Ingestion Scaling 的 error 快通道設計就是基於這個優先級差異。

被自己的 SDK DDoS

「SDK 產生的流量壓垮自己的 collector」是自架監控系統最常見的可靠性事故。來源是自家 SDK 的異常行為或正常行為在特定條件下的放大效應 — 內部流量失控，而非外部攻擊。外部偽造流量的防護見 Client-side SDK 認證。

本段按觸發場景分類（SDK bug / 部署推送 / 使用者暴增），和 Ingestion Scaling 的四層防線（SDK 端 / collector 單機 / 水平擴展 / queue 解耦）是不同切面。四層防線按防護位置劃分、說明機制怎麼做；本段按場景劃分、說明什麼時候哪些機制會被觸發。

SDK bug：事件風暴

SDK 程式碼 bug 導致事件無限迴圈 — 常見於事件處理器內再次觸發事件（error handler 中呼叫 monitor.event() 又觸發 error），或 UI 事件綁定錯誤導致每個 frame 產生一筆事件（60 fps = 每秒 60 筆）。

損失路徑：事件風暴首先填滿 SDK buffer → 觸發高頻 flush → collector 收到大量 request → channel 滿觸發 429 → SDK 動態降採樣。如果 SDK 的動態降採樣邏輯本身也有 bug（降到 0.1 後不再降），collector 仍然會持續承壓。

防護層級：

SDK 端 — 事件產生速率上限。SDK 內部維護每秒事件計數器，超過閾值（例如 100 events/sec）後的事件直接丟棄，不進 buffer。這個上限獨立於取樣和背壓機制，是防止 SDK 自身 bug 的最後一道防線。

1// SDK 端的 rate limiter（偽碼，各語言實作不同）
2count = atomicIncrement(eventCounter)
3if count > maxEventsPerSecond:
4    atomicIncrement(droppedCounter)
5    return  // 不進 buffer

Collector 端 — per-key rate limit。每個 API key（或 source.app）的請求速率獨立限制。一個失控的 SDK 被限速時，其他 SDK 的事件不受影響。這和 Ingestion Scaling 的 per-SDK rate limiting 是同一個機制。

Collector 端 — circuit breaker。如果某個 API key 的 429 回應次數在短時間內超過閾值，collector 暫時拒絕該 key 的所有請求（回 503），不再逐筆檢查 rate limit。冷卻期過後自動恢復。這降低了 rate limit 本身的 CPU 開銷 — 高頻 429 回應也有成本。閾值需高於正常 burst 的 per-key 429 頻率 — 如果正常 flush 在 burst 時每分鐘最多觸發 N 次 429，circuit breaker 閾值設為 5N-10N 避免誤觸。具體數字（例如 50 次/分鐘、5 分鐘冷卻）依部署規模調整。

部署推送：補發風暴

100 台機器同時重啟（rolling deploy），每台機器的 SDK 在啟動時：

1. 讀取本地 persistence 中的離線事件
2. 初始化後立即 flush 離線事件 + 新的 lifecycle 事件

100 個 SDK 在幾秒內同時發起離線補發 + 正常 flush，collector 瞬間承受 100 倍的正常流量。

防護方式：init jitter — SDK 初始化後不立即 flush，而是等待一個隨機延遲（0 到 flush_interval 之間的均勻分佈）。100 個 SDK 的首次 flush 分散在 0-30 秒內，流量從一個尖峰變成斜坡。

1import random
2initial_delay = random.uniform(0, flush_interval_seconds)
3# 第一次 flush 延遲 initial_delay 秒，後續按正常 interval

離線補發也加 jitter — 每批補發之間的間隔從固定的 1 秒改為 1-3 秒的隨機值。100 個 SDK 的補發批次在時間軸上交錯，避免所有 SDK 以相同節奏同時送出。

使用者行為高峰：同時在線暴增

行銷活動、媒體報導、季節性高峰 — 同時在線使用者從 100 人暴增到 10,000 人。每個使用者的 SDK 正常運作，但總量超出 collector 的處理能力。

這個場景和 SDK bug 的差異：每個 SDK 的行為完全正常，問題在總量。Per-key rate limit 不會觸發（每個 SDK 的速率在正常範圍），需要的是全域流量控制。

防護方式：Collector 端的全域 channel 背壓（Ingestion Scaling 第二層）是第一道防線 — channel 滿時所有 SDK 收到 429，各自動態降採樣。如果動態降採樣後流量仍然過大，水平擴展（多 collector + load balancer）或 queue 解耦是解法。

行銷活動的可預測性是優勢 — 活動日期已知，可以提前擴展 collector 容量（加機器或調高 channel 容量）。突發的媒體報導則依賴動態降採樣和背壓的自動調節。

三種場景的防護對照

資料恢復 vs 接受損失

每個損失點都可以投入工程努力降低損失量。問題是恢復的工程成本是否值得 — 監控資料不是交易紀錄，恢復的價值取決於損失的事件類型和數量。

值得恢復的場景

Error 事件：每筆 error 都可能對應一個需要修的 bug。Error 的損失代表 bug 可能更晚被發現、在更多使用者身上發生後才被注意到。值得投入本地 persistence、優先級丟棄（error 最後丟）、error 快通道等機制降低損失。

Lifecycle 事件：session 邊界（session.begin / session.end）是 cohort 分析和 session replay 的基礎。丟失 session 邊界會讓整個 session 的事件無法正確歸屬。Lifecycle 事件量低（每 session 幾筆），保留成本小、損失影響大。

接受損失的場景

高頻 metric 事件：render.frame_time 每秒 60 筆，丟幾筆對趨勢分析的影響在統計誤差範圍內。聚合前移（SDK 端每 5 秒送一筆 summary）比逐筆保留更有效率。

行為 event 事件：button.click、page.view 在取樣後丟幾筆，funnel 的轉換率計算用取樣校正（除以取樣率）仍然有效。單筆行為事件的 debug 價值低 — 知道某使用者點了某按鈕通常不影響決策。

超過保留期的原始事件：purge 後只剩聚合摘要。如果分析需求發現需要更長的原始事件保留期，調整 retention config，不要嘗試從聚合摘要「恢復」原始事件 — 那是不可能的。

恢復成本的判斷

本地 persistence（SDK 端把 buffer 寫到檔案系統）的實作成本和收益：

MVP 階段用記憶體 FIFO。本地 persistence 作為第二階段功能，在離線損失率超出可接受範圍時投入。

下一步路由

• SDK 端的離線保護 → 離線 buffer 與重試
• Collector 端的流量防護 → Ingestion Scaling
• Collector 的處理鏈路 → Collector 架構
• Container 環境的 graceful shutdown → Container 部署設計
• 保留策略和降採樣 → 規模演進
• SDK 認證和偽造流量防護 → Client-side SDK 認證

Collector 搭配的 Developer Dashboard 在 Error 列表中用 GROUP BY name 做分群 — 同名的 error 歸為一行。這在 error name 設計良好時（terminal.connect.failed / auth.biometric.timeout）可以運作，但在以下情境會失效：

• 同一個 name 對應多個不同的 root cause — app.exception 的 stack trace 指向完全不同的程式碼位置
• 不同 name 其實是同一個 root cause — ws.connect.failed 和 ws.reconnect.failed 都是同一個 server 下線造成

Fingerprint 提供比 name 更精確的分群維度。

Fingerprint 演算法

Fingerprint 從 error 事件中提取關鍵欄位、計算 hash，相同 hash 的事件歸為同一組。欄位的選擇決定分群的粒度。

基礎版：type + message

1fingerprint = SHA256(error_type + ":" + error_message)

用 error_type（NullPointerException / TypeError / ConnectionError）加上 error_message 做 hash。實作最簡單，大多數情況下能正確分群。

問題在 error message 包含動態值時。同一個 bug 產生的 error 因為動態值不同而分裂成多組：

1"User 12345 not found"  → fingerprint A
2"User 67890 not found"  → fingerprint B

這兩筆是同一個 bug（查無使用者），但 message 中的 user ID 不同導致 fingerprint 不同。動態值的處理見下方 message normalization。

進階版：type + stack trace top frames

1fingerprint = SHA256(error_type + ":" + top_3_frames)

用 error_type 加上 stack trace 最頂端的 N 個 frame（函式名 + 檔案名 + 行號）做 hash。Stack trace 的頂端通常是 error 發生的直接位置，相同位置的 error 歸為同組。

1// 兩筆 error 的 stack trace 頂端相同 → 同一個 fingerprint
2TypeError: Cannot read property 'name' of null
3  at UserProfile.render (UserProfile.js:42)    ← frame 1
4  at Component.update (framework.js:108)       ← frame 2
5  at scheduler.flush (framework.js:203)        ← frame 3

N 的選擇是粒度 vs 穩定性的取捨。N=1 過粗（不同 bug 可能在同一個函式裡），N=5 過細（重構移動程式碼後行號改變，同一個 bug 的 fingerprint 分裂）。N=3 是常見的預設值。

Stack trace 版本的前提是 error 事件帶有結構化的 stack trace。如果 SDK 只送 error message 不送 stack trace，只能用基礎版。

Sentry 的做法

Sentry 的策略核心是只用應用程式自身的 frame 做 hash，排除 framework / library 的 frame，並 normalize message 中的動態值。具體做法：

1. 取 in-app frame：忽略 framework / library 的 frame（framework.js、node_modules/），只用應用程式自身的 frame。同一個 bug 在不同版本的 framework 上觸發時，framework frame 可能不同，但 app frame 相同。
2. Normalize message：移除動態值（數字、UUID、email）後再 hash。
3. 取最後一個 in-app frame 的函式名：而非取前 N 個 frame。最後一個 in-app frame 是「error 在應用程式碼中實際發生的位置」。

Sentry 的策略對 web 前端（大量 framework frame）和行動 app（大量 OS / runtime frame）的分群效果好，但實作複雜度高 — 需要維護「什麼算 in-app frame」的規則。

SDK 端自定義 fingerprint

SDK 端可以手動指定 fingerprint，覆蓋 collector 的自動計算。用途是讓開發者把「技術上不同但業務上同因」的 error 歸為同組。

1monitor.error("API timeout", data={
2    "fingerprint": "api-gateway-timeout",
3    "endpoint": "/v1/users",
4    "duration_ms": 30000
5})

所有帶 fingerprint: "api-gateway-timeout" 的 error，無論 message 和 stack trace 是否相同，都歸入同一組。

自定義 fingerprint 的處理邏輯：collector 收到事件時，先檢查 data.fingerprint 欄位是否存在。存在則直接用這個值做 hash（或直接用作 fingerprint），不走自動計算。

Message normalization

動態值讓相同 bug 的 message 不同，導致 fingerprint 分裂。Normalization 在計算 fingerprint 前把動態值替換成 placeholder。

替換規則

後兩個屬進階規則 — 基礎五個（數字 / UUID / email / IP / 長字串）在多數場景足夠，file path 和 timestamp 在 error group 分裂嚴重時再加。

 1var normalizers = []struct {
 2    pattern *regexp.Regexp
 3    replace string
 4}{
 5    {regexp.MustCompile(`\b[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\b`), "{uuid}"},
 6    {regexp.MustCompile(`\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b`), "{email}"},
 7    {regexp.MustCompile(`\b\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}\b`), "{ip}"},
 8    {regexp.MustCompile(`\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}`), "{ts}"},
 9    {regexp.MustCompile(`(?:/Users/|/home/|C:\\Users\\)[^/\\]+`), "{path}"},
10    {regexp.MustCompile(`\d{3,}`), "{N}"},
11}
12
13func normalizeMessage(msg string) string {
14    for _, n := range normalizers {
15        msg = n.pattern.ReplaceAllString(msg, n.replace)
16    }
17    return msg
18}

Normalization 的風險

過度 normalize：把實際不同的 error 歸為同組。例如 HTTP status code 404 和 500 都被替換成 {N}，導致 "HTTP {N}" 把 404 和 500 混在一起。對策：HTTP status code 等已知語意數字用具名 pattern 優先保留（(\b[1-5]\d{2}\b) → 不替換），再跑通用數字替換。Normalizer 的規則順序決定優先級 — 具名 pattern 放在 \d{3,} 之前，匹配到的數字跳過後續替換。

不足 normalize：遺漏動態值導致同因 error 分裂。例如 message 中包含時間戳 "Error at 2026-06-24T14:30:00" 但 normalization 沒有覆蓋 ISO 8601 格式。對策：先用基礎規則上線，根據 error group 的分裂狀況逐步補規則 — 同一個 error 名稱下有大量 group 且 stack trace 相同，通常代表 normalization 不足。

Storage 設計

Fingerprint 的儲存分兩部分：events 表加 fingerprint 欄位、新建 error_groups 表追蹤每組的摘要。

Events 表擴充

在現有的 events 表加 fingerprint 欄位：

1ALTER TABLE events ADD COLUMN fingerprint TEXT;
2CREATE INDEX idx_fingerprint ON events(fingerprint);

fingerprint 存 hash 值（SHA256 hex 的前 16 字元足夠 — 自架場景的 error 種類不會多到 collision）。索引加速「查看某個 error group 的所有事件」查詢。

error_groups 表

 1CREATE TABLE error_groups (
 2    fingerprint TEXT PRIMARY KEY,
 3    name TEXT NOT NULL,
 4    error_type TEXT,
 5    normalized_message TEXT,
 6    count INTEGER NOT NULL DEFAULT 1,
 7    first_seen TEXT NOT NULL,
 8    last_seen TEXT NOT NULL,
 9    last_event_id INTEGER REFERENCES events(id),
10    session_count INTEGER NOT NULL DEFAULT 1,
11    status TEXT NOT NULL DEFAULT 'open'
12);
13
14CREATE INDEX idx_error_groups_last_seen ON error_groups(last_seen);
15CREATE INDEX idx_error_groups_count ON error_groups(count);