五段處理鏈路

第一段：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 與去重分群

核心欄位

type（必填）

事件類型。對應四類事件分類（模組一）：event、error、metric、lifecycle。

Collector 用 type 決定事件的處理路徑 — error 類型觸發告警規則，metric 類型進入數值聚合，event 類型進入行為分析。

name（必填）

事件名稱。使用 namespace.action 格式（事件命名規範）。例如 terminal.connect.done、auth.biometric.failed。

name 是查詢和統計的主要索引。grep "terminal.connect" 找到所有連線事件；按 name 分群計數得到功能使用頻率。

timestamp（必填）

事件發生的時間。ISO 8601 格式，包含時區偏移。2026-06-19T14:30:00.123+08:00。

Timestamp 由 SDK 在事件發生時記錄，不是 collector 收到時記錄。兩者可能有延遲（離線 buffer、網路延遲），以 SDK 端的時間為準。

source（必填）

事件來源的識別資訊。包含產生事件的 SDK、app 名稱、版本、平台、OS 版本。

1{
2  "source": {
3    "sdk": "flutter",
4    "app": "app_tunnel",
5    "version": "1.2.0",
6    "platform": "ios",
7    "os": "17.4"
8  }
9}

sdk 標明產生事件的 SDK 種類（js / flutter / python / go）。同一個平台可能有不同的 SDK——iOS 上可能是 Flutter SDK 或未來的 Swift 原生 SDK——sdk 欄位讓 collector 區分事件來自哪個 SDK 實作，platform 無法替代這個識別。sdk 和 platform 為必填，app、version、os 為選填。

Source 讓同一個 collector 接收多個 app 的事件時可以區分來源。也用於分析「哪個版本的 error 率最高」、「哪個 OS 版本有特定問題」。

platform 合法值與自動偵測

platform 由 SDK init 時自動偵測，開發者不需手動設定。各 SDK 的偵測來源和映射規則：

以上映射是 SDK init 時的預設自動偵測行為。Python 和 Go 的 runtime 回傳系統內部名稱（darwin、win32），SDK 負責映射到 schema 定義的標準名稱。Flutter 的 dart:io Platform.operatingSystem 恰好回傳合法值。JS SDK 在瀏覽器環境中無法可靠偵測 OS，platform 統一為 web。

自動偵測之外，SDK 也接受手動覆蓋 platform 值。短生命週期的命令列腳本（如 CI pipeline step、pre-commit hook）可手動將 platform 設為 script，表示非互動式 OS session——這類場景中 OS 名稱不是有意義的區分維度，script 讓查詢時能篩選出所有腳本來源的事件。

SDK 不做映射的話，collector 會收到不一致的 platform 值——同是 macOS 的事件有些標 darwin 有些標 macos，查詢篩選會漏事件。各平台 SDK 的執行環境適配細節見模組五：平台適配。

session（選填）

使用者 session 的識別資訊。Session ID（UUID）和 session 開始時間。

Session 用於關聯同一次使用中的多個事件。「使用者在這次 session 中做了什麼操作、遇到了什麼 error」的分析依賴 session ID。

去識別化要求：session ID 用 UUID 而非使用者帳號，不包含個人識別資訊（模組七）。

data（選填）

事件的附加資料。自由結構的 JSON object，內容依事件類型和名稱而定。

1{
2  "data": {
3    "url": "wss://192.168.1.100:7681/ws",
4    "duration_ms": 320,
5    "step": "3/5"
6  }
7}

Data 欄位是 schema 中唯一的自由結構區域。核心欄位（type、name、timestamp、source）有固定格式，data 的內容由事件定義者決定。

v（必填）

Schema 版本號。整數，從 1 開始遞增。

版本號讓 collector 知道用哪個版本的 schema 驗證這筆事件。Schema 演進時，舊版本的事件仍可被正確處理。

Collector 附加欄位（底線前綴）

Collector 在事件寫入 storage 時可以附加系統層的 metadata。這些欄位使用底線前綴（_flags、_fingerprint），和 SDK 端產生的業務欄位區隔。SDK 送出的事件中不包含這些欄位 — 它們由 collector pipeline 在處理過程中計算並附加。

_flags（選填，collector 附加）

Collector 端的行為分析或規則引擎偵測到異常時，在事件中附加標記。Dashboard 查詢可用 _flags 過濾可疑事件。

1{
2  "_flags": {
3    "suspicious": true,
4    "reason": "rate_anomaly"
5  }
6}

suspicious 標記的事件不被刪除 — 直接丟棄有誤殺正常流量的風險（行銷活動的真實流量暴增可能觸發異常偵測）。Dashboard 預設排除 _flags.suspicious = true 的事件，需要調查時可包含。

標記來源和 reason 值的定義見 Client-side SDK 認證 的事後標記策略段。

_fingerprint（選填，collector 附加）

Error 事件的去重識別碼。Collector 從 error 的 type、normalized message、stack trace 計算 hash，用於把相同根因的 error 歸組。

1{
2  "_fingerprint": "a3f8c2e1b7d94f06"
3}

Fingerprint 的計算邏輯和 error grouping 機制見 Error Fingerprint 與去重分群。

SDK 自監控指標

監控系統自身的資料完整性需要獨立的指標追蹤 — SDK 用 metric 類事件回報自己的送出量和丟棄量，collector 用 endpoint 暴露處理量和拒絕量。SDK 端的指標每次 flush 成功後作為標準 schema 事件一起送出，name 以 sdk. 前綴標識。

Collector 端對應暴露 collector.events.received、collector.events.rejected、collector.events.stored、collector.events.backpressure 等指標，透過 /metrics endpoint 或 health endpoint 的擴展欄位提供。

完整的指標定義、端到端比對方法和損失率閾值見 端到端資料完整性 的監控損失段。

完整 schema 範例

 1{
 2  "v": 1,
 3  "type": "error",
 4  "name": "terminal.connect.failed",
 5  "timestamp": "2026-06-19T14:30:00.123+08:00",
 6  "source": {
 7    "sdk": "flutter",
 8    "app": "app_tunnel",
 9    "version": "1.2.0",
10    "platform": "ios",
11    "os": "17.4"
12  },
13  "session": {
14    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
15    "started": "2026-06-19T14:25:00.000+08:00"
16  },
17  "data": {
18    "step": "ws_connect",
19    "error": "Connection refused",
20    "url": "wss://192.168.1.100:7681/ws"
21  }
22}

下一步路由

• 欄位設計的原則 → 欄位設計原則
• Schema 版本演進 → Schema 版本演進策略
• 和 OpenTelemetry 的差異 → 跟 OpenTelemetry 的 schema 差異對照
• Log 點的設計方法 → testing 模組二 客戶端可觀測性

概念位置

Funnel analysis 位在行為資料收集之後、產品決策之前。它的輸入是 event 類監控事件（使用者操作記錄），輸出是每步的轉換率。Funnel analysis 的前提是去識別化（redaction）已完成 — 分析行為資料前必須確保資料不含可識別個人的敏感欄位。

可觀察訊號與例子

產品需要 funnel analysis 的訊號是「使用者在某個流程中的完成率低於預期，但不知道卡在哪一步」。註冊流程的轉換率從填寫 email 到完成驗證只有 30%，funnel analysis 揭露 60% 的使用者在「等待驗證信」步驟流失。

設計責任

Funnel analysis 要定義步驟順序、步驟之間的時間窗口（使用者在多久內完成下一步才算轉換）、以及分群維度（按平台、來源、使用者類型拆分 funnel）。步驟定義需要和事件命名規範對齊 — funnel 的每一步對應一個具體的事件名稱。

CORS 限制

瀏覽器的同源政策限制網頁向不同 origin 發送請求。SDK 的 HTTP POST 送到 collector endpoint 時，如果 collector 和網頁不在同一個 origin（protocol + domain + port 都相同），瀏覽器會先發送 preflight OPTIONS 請求確認 server 允許跨域存取。

SDK 端的適配：

使用 navigator.sendBeacon(url, data) 代替 fetch / XMLHttpRequest。sendBeacon 不受 CORS 限制（瀏覽器對 beacon 請求不做 preflight），且在頁面 unload 時仍能可靠送出 — 適合 close flush 場景。

sendBeacon 的限制：payload 大小有上限（通常 64KB），不能自訂 Content-Type header（固定為 text/plain 或 application/x-www-form-urlencoded），沒有回應 — 送出後無法知道 server 是否收到。

如果需要 fetch（例如需要讀取回應或送出大 payload），collector 端需要設定 CORS header：Access-Control-Allow-Origin、Access-Control-Allow-Methods: POST、Access-Control-Allow-Headers: Content-Type。

Service Worker 攔截

Service Worker 可以攔截頁面發出的所有 HTTP 請求（包括 SDK 的 POST 請求到 collector）。如果應用程式的 Service Worker 有 cache 策略（cache-first、network-first），SDK 的監控請求可能被快取而非送到 collector。

SDK 端的適配：

在 fetch 請求中加 cache: 'no-store' 防止 Service Worker 快取監控請求。或在請求 URL 加唯一的 query parameter（?_t=timestamp）讓每次請求的 URL 都不同，繞過 cache 比對。

如果 SDK 本身提供 Service Worker 模組（在 Service Worker 內攔截 error），需要注意 Service Worker 的生命週期和頁面不同 — Service Worker 可能在頁面關閉後仍在執行，也可能在空閒時被瀏覽器終止。

SPA 路由變換偵測

Single Page Application 的路由變換（React Router、Vue Router、Angular Router）不觸發頁面重新載入。從監控角度看，使用者在不同「頁面」之間切換，但 window.onload 只在首次載入時觸發一次。

SDK 需要偵測 SPA 路由變換來記錄 lifecycle.view.change 事件。偵測方式：

History API 攔截：monkey-patch history.pushState 和 history.replaceState，在呼叫前後記錄路由變換。同時監聽 popstate 事件處理瀏覽器的上一頁/下一頁。

MutationObserver：監聽 DOM 變化偵測頁面內容更新。但 MutationObserver 觸發頻率高，需要 debounce 並搭配 URL 變化檢查，避免把 DOM 微調誤判為路由變換。

框架特定的 hook：如果 SDK 提供框架整合套件（React / Vue / Angular plugin），可以用框架的 router 事件（useNavigate hook、router.afterEach guard）直接取得路由變換資訊，比 monkey-patch History API 更可靠。

JS/TS 的平台限制理解後，其他平台各有各的挑戰 — Flutter 平台適配處理 isolate 和 platform channel 的問題。所有平台共同面對的 timestamp 一致性問題（時區、精度、clock drift）在獨立章節中展開。SDK 的跨平台公開 API 設計見模組三 SDK 公開 API。

預設 Redaction Rule

SDK 內建的 redaction rule 覆蓋最常見的敏感欄位模式。開發者不需要設定就能獲得基本保護。

欄位名稱比對

以下欄位名稱（不分大小寫）的值自動替換為 [REDACTED]：

• password、passwd、secret、token、api_key、apiKey
• authorization、auth、credential
• ssn、social_security
• credit_card、card_number、cvv、cvc

欄位名稱比對用 substring match — user_password 包含 password 會被 redact，password_reset_token 包含 password 和 token 也會。

值格式比對

以下格式的值無論欄位名稱為何都自動替換：

• Email 地址格式（user@domain.com → u***@domain.com）
• 信用卡號碼格式（連續 13-19 位數字 → 保留末四碼）
• Bearer token 格式（Bearer xxx → Bearer [REDACTED]）

值格式比對用正則表達式。正則的效能影響在大量事件時需要注意 — 預設 rule 的正則保持簡單，避免 catastrophic backtracking。

自訂 Pattern

應用可能有自己的 secret 格式，預設 rule 覆蓋不到。SDK 提供 API 讓開發者註冊自訂 redaction pattern。

 1monitor.addRedactionRule(
 2  name: 'internal-api-key',
 3  pattern: RegExp(r'sk_live_[a-zA-Z0-9]{24}'),
 4  replacement: '[REDACTED:api-key]',
 5)
 6
 7monitor.addRedactionRule(
 8  name: 'database-url',
 9  fieldNames: ['database_url', 'db_url', 'connection_string'],
10  replacement: '[REDACTED:db-url]',
11)

自訂 pattern 的設計考量：

Pattern 在 init 時註冊。Redaction rule 在 SDK 初始化時設定，之後所有事件都通過這些 rule。不支援動態修改 — 避免「中途加 rule 導致之前的事件沒被 redact」的困惑。

Pattern 順序無關。所有 rule 獨立執行，不依賴順序。一個欄位可以匹配多個 rule，以第一個匹配的 replacement 為準。

Replacement 可以保留部分資訊。[REDACTED] 完全遮蔽，[REDACTED:api-key] 保留類型資訊，u***@domain.com 保留結構。保留類型資訊對 debug 有幫助 — 看到 [REDACTED:api-key] 至少知道這裡原本有一個 API key。

Redaction 的適用範圍

Redaction 應用在 SDK 送出事件前的最後一步 — 在序列化（JSON encode）之前。適用範圍包括：

• Event 的 data 欄位（自由欄位，開發者可能放入任何內容）
• Error 的 stack trace（檔案路徑可能包含使用者名稱或部署路徑）
• Error 的 message（例外訊息可能包含 query string 或參數值）
• Lifecycle 的 metadata（連線 URL 可能包含認證資訊）

Redaction 不應用在 SDK 的內部欄位（timestamp、event type、session ID）— 這些是 SDK 自己產生的，不包含使用者資料。

下一步路由

• 資料離開 client 後的保護 → Transport 安全
• 去識別化策略 → 去識別化策略
• IME 個人化學習的 secret 洩漏風險 → ux-design 模組三 IME 安全 checklist

六個方法

init

SDK 初始化。設定 collector endpoint、app 識別資訊、flush 間隔、buffer 大小。在 app 啟動時呼叫一次。

1Monitor.init({
2  endpoint: 'https://collector.example.com/v1/events',
3  app: 'my_app',
4  version: '1.2.0',
5  flushInterval: 30000,   // 毫秒
6  bufferSize: 100,
7})

init 負責建立 session、記錄 lifecycle.session.start 事件、啟動 flush 計時器。init 之前呼叫其他方法應該拋出明確錯誤（SDK 未初始化），而非靜默忽略。

連線驗證策略：lazy。init 不驗證 collector 是否可達 — 不發 HTTP 請求、不 ping endpoint。init 的失敗只代表配置錯誤（缺少 endpoint 參數），不代表網路問題。網路問題在第一次 flush 時才浮現，flush 失敗時事件保留在 buffer 等待重試。

Lazy 策略的理由：SDK 不應阻塞主程式的啟動流程。如果 init 驗證連線，collector 暫時不可用時 app 會啟動失敗 — 監控工具反而變成可用性的瓶頸。短生命週期腳本（Python 平台適配：短生命週期腳本）對這一點更敏感 — hook 腳本不能因為 collector 沒啟動就拒絕執行。

event

記錄使用者操作事件（四類事件中的 Event 類）。接受事件名稱和可選的 data 物件。

1Monitor.event('terminal.connect.start', { url: 'wss://...' })
2Monitor.event('enrollment.qr.scan')

event 方法是非阻塞的 — 事件進入內部 buffer 立即返回，不等待網路送出。應用程式的操作流程不應該被監控 SDK 的網路延遲阻塞。

error

記錄錯誤事件。接受 Error/Exception 物件或自訂的錯誤描述。自動附加 stack trace、錯誤類型、觸發位置。

1Monitor.error(exception, { step: 'ws_connect' })
2Monitor.error('Auth token missing', { context: 'handshake' })

error 方法和自動攔截機制（自動攔截）互補 — 自動攔截處理未捕獲的例外，error 方法處理開發者主動上報的已知錯誤。

metric

記錄數值指標。接受指標名稱和數值。

1Monitor.metric('connect.duration_ms', 320)
2Monitor.metric('terminal.fps', 58.5)

metric 方法記錄的是離散的數值快照。聚合計算（平均、百分位、趨勢）在 collector 端完成，SDK 端只負責記錄原始值。

flush

強制送出 buffer 中所有待發事件。正常情況下 SDK 按 flushInterval 定期自動 flush（攢批送出）。flush 方法用於需要確保事件已送出的場景 — 例如 app 即將進入背景或使用者手動觸發 log 上傳。

1await Monitor.flush()

flush 是非同步方法 — 需要等待網路請求完成。呼叫端可以 await 確認送出成功，也可以 fire-and-forget。

close

SDK 資源釋放。停止 flush 計時器、送出 buffer 中剩餘事件、關閉網路連線、記錄 lifecycle.session.end 事件。

1await Monitor.close()

close 在 app 關閉時呼叫。呼叫後 SDK 進入已關閉狀態，後續的 event/error/metric 呼叫應該被靜默忽略（不拋錯，因為 app 正在關閉）。

API 設計原則

方法名稱和四類事件對齊。event / error / metric 三個方法直接對應三類事件，lifecycle 事件由 init 和 close 自動產生。開發者看到方法名稱就知道對應哪類事件。

所有上報方法非阻塞。event、error、metric 進 buffer 立即返回。監控 SDK 阻塞應用程式的操作流程是反模式。

init 和 close 成對出現。init 開始 session，close 結束 session。兩者界定 SDK 的活躍期間。

各平台的 SDK 整合範例（Flutter 的 pubspec.yaml + main.dart init、Python 的 pip install + init code、JS 的 script tag + init）見 monitor repo 各 SDK 的 README。

下一步路由

• 自動攔截未捕獲的錯誤 → 自動攔截機制
• Buffer 和 flush 的策略 → 攢批送出策略
• SDK 端的資料脫敏 → SDK redaction helper
• SDK 的 HTTP POST 行為需要 protocol test → testing 模組三 協議整合測試

Event：使用者做了什麼

Event 記錄使用者主動發起的操作。按鈕點擊、頁面瀏覽、表單提交、搜尋查詢 — 每個 event 代表使用者的一個意圖表達。

Event 的觸發時機是使用者操作發生時。程式碼中的位置通常是 UI 事件處理器（onClick、onSubmit、onNavigate）。

Event 的消費方式：

• Debug context：問題發生前使用者做了哪些操作。和 error 事件搭配使用，還原問題的操作路徑。
• 行為分析：使用者做了哪些操作、操作順序是什麼、在哪一步停止。Funnel analysis 的原料（模組八）。
• 功能使用率：哪些功能被頻繁使用、哪些很少被觸發。功能優先順序的決策依據。

Error：什麼出了問題

Error 記錄程式碼執行中的非預期狀態。例外拋出、assertion 失敗、非預期的 API 回應、資源存取失敗。

Error 的觸發時機是非預期狀態被偵測到時。來源包括：語言層級的 try/catch 捕獲、框架的全域錯誤處理器（Flutter 的 FlutterError.onError、JavaScript 的 window.onerror）、自訂的錯誤檢查邏輯。

Error 的消費方式：

• 即時告警：特定類型的 error 或 error 數量超過閾值時通知開發者。
• 趨勢分析：error 數量隨時間的變化。新版本部署後 error 是否增加。
• 根因分析：error 的 stack trace、觸發條件、影響範圍。和 event 搭配還原「使用者做了什麼導致 error」。

Metric：系統狀態的數值快照

Metric 記錄系統狀態的可量化指標。回應時間、記憶體使用量、佇列長度、連線數、frame rate。

Metric 的觸發時機是定期取樣或特定事件發生時。定期取樣適合持續變化的指標（記憶體使用量每 30 秒取一次），事件觸發適合離散的測量（每次 API 回應記錄回應時間）。

Metric 的消費方式：

• 效能監控：回應時間的 P50 / P95 / P99 分佈。記憶體使用量的趨勢。
• 容量規劃：佇列長度接近上限、連線數接近 pool 上限 — 需要擴容的訊號。
• SLA 追蹤：服務可用性、回應時間是否在承諾範圍內。

Lifecycle：系統經歷了什麼階段

Lifecycle 記錄系統本身的狀態轉換。App 啟動、前景/背景切換、連線建立/斷開、版本更新、設定變更。

Lifecycle 的觸發時機是系統狀態轉換發生時。來源包括：app 生命週期回呼（onCreate、onResume、onPause）、連線狀態變化事件、部署和設定變更鉤子。

Lifecycle 的消費方式：

• Session 分析：使用者一次使用多久、啟動頻率、前後景切換頻率。
• 環境資訊：Error 發生時的系統狀態（app 版本、OS 版本、網路狀態）。
• 連線品質：連線建立成功率、斷線頻率、重連次數（testing 模組二 三層 log）。

四類事件的區別

下一步路由

• 事件命名規範 → 事件命名規範
• 從需求推導收集策略 → 從需求推導「該收集哪些事件」
• Event 類事件在商業分析中的用途 → 模組八 行為資料的商業利用
• Log 點的設計方法 → testing 模組二 客戶端可觀測性

四個判斷維度

使用者數

自架方案的成本和使用者數幾乎無關（JSONL + grep 處理 1 個和 100 個使用者的成本差異很小）。商業方案按事件量或使用者數計費，使用者數增長直接推高費用。

經驗估算：使用者數在百人以下時，自架的總成本（開發 + 維護 + 硬體）通常低於商業方案的年費（以典型商業方案年費 $300-$600 和自架的開發維護時間估算）。使用者數在千人以上時，自架需要投入的基礎設施維護（高可用、擴容、備份）成本上升，商業方案的規模經濟開始有優勢。具體的交叉點取決於選用的 vendor 定價（Sentry Developer plan 免費額度 5000 events/月、PostHog 免費到 1M events/月）和自架的維護時間成本。

兩者之間是灰色地帶 — 取決於功能需求和團隊能力。

網路範圍

使用者和 collector 是否在同一個網路內。

同一網路（自用工具、內部工具）：自架方案直接 HTTP POST 到本機或內網 endpoint，不需要 DNS、TLS 憑證、CDN。成本極低。

外部網路（公開 app、SaaS）：自架方案需要處理公網暴露、DDoS 防護、TLS 憑證管理、高可用（多區域部署）。商業方案把這些基礎設施問題內化了。

功能需求

自架方案的功能上限是開發者願意投入的工程量。grep + jq 能做基礎查詢和 funnel 分析（模組八 自架 funnel）。Dashboard、告警、session replay、A/B test 分群每個功能都是數週到數月的開發量。

商業方案的功能開箱即用。如果需求包含 session replay、A/B test dashboard、自動 issue 分群，商業方案的功能完成度遠高於自架。

合規要求

資料必須存放在特定地區（GDPR data residency）或不能離開公司網路（金融、醫療）。

自架：資料完全在自己的基礎設施上，資料位置由自己控制。適合最嚴格的合規要求。

商業方案：資料存放在 vendor 的基礎設施上。部分 vendor 提供 data residency 選項（Sentry 的 EU hosting、Datadog 的 EU region），但仍然是第三方持有資料。

決策表

四個維度中三個以上指向同一方向 → 選那個方向。兩兩對半 → 從自架開始（成本低、可逆），需求增長後再評估切換。

決策表指向商業方案後，Sentry 深入和 Firebase 套件分別展開兩個主流方案的架構和能力邊界。決策表指向自架時，模組四 Collector 設計提供從 HTTP endpoint 到 rule engine 的完整實作藍圖。Server-side 的可觀測性（OTLP、Prometheus、Grafana）見 Backend 模組四 可觀測性。

中間路線

上表是「完全自架 vs 專業監控 SaaS」的兩端。中間還有兩條路徑 — 用 BaaS（Supabase + Vercel）搭出託管版 collector，或用 PaaS（Railway / Fly.io）跑自架 collector 原始碼但不管 server。APP 上線初期用免費方案零成本起步、保留自訂 schema 彈性是常見的起步策略。完整的四條路徑比較、架構差異、免費方案限額和遷移路線見部署光譜。

事件命名

行為事件的命名遵循 namespace.action 格式（模組一 事件命名規範）。行為分析場景對命名的額外要求是：同一個 funnel 內的事件要能用 namespace 前綴篩選。

例：註冊流程的事件用共同前綴 signup：

1signup.page.view          使用者看到註冊頁
2signup.form.submit        使用者送出表單
3signup.email.verify       使用者點擊驗證信連結
4signup.complete           註冊完成

用 signup.* 就能篩選出整個註冊流程的事件，不需要事先知道每一步的完整名稱。

屬性設計

每個事件除了名稱，還帶有屬性（properties / parameters）描述事件的 context。屬性分成三層：

通用屬性（每個事件都有）

• timestamp：事件發生的時間（UTC，毫秒精度）
• session_id：當次使用的 session 識別碼
• user_id：使用者識別碼（去識別化後，見 模組七）
• platform：iOS / Android / Web
• app_version：app 版本號

事件類型屬性（同類事件共有）

• 頁面瀏覽事件：page_name、referrer
• 按鈕點擊事件：button_id、button_text
• 搜尋事件：query、result_count

事件專屬屬性（特定事件才有）

• signup.form.submit：form_method（email / Google / Apple）
• purchase.complete：amount、currency、product_id

屬性設計的判斷標準是：這個屬性是否用於回答一個分析問題。「註冊方式的轉換率差異」需要 form_method 屬性；如果沒有這個分析問題，就不需要這個屬性。

Funnel 定義

Funnel 是一連串有順序的事件，代表使用者完成一個目標的步驟。Funnel 定義在事件設計階段完成 — 決定哪些事件構成一個 funnel、順序是什麼、每步之間的最大時間間隔。

定義一個 funnel 需要：

步驟清單：funnel 包含哪些事件，順序是什麼。

時間窗口：步驟之間的最大間隔。使用者在步驟 A 之後 30 天才做步驟 B，是否算在同一個 funnel 內？時間窗口的設定取決於業務場景 — 電商結帳 funnel 通常是 30 分鐘，SaaS onboarding funnel 可能是 7 天。

完成條件：什麼算「完成」funnel。到達最後一步即完成，還是需要特定屬性值（purchase.complete 且 status = success）。

過度收集的成本

行為事件收集的邊界是「能回答已知的分析問題」。收集超出分析需求的事件有三個成本：

儲存成本：每個事件佔一行 JSONL。高頻事件（每次滾動、每次 hover）的資料量遠大於低頻事件（按鈕點擊、頁面瀏覽）。

隱私風險：收集的事件越多，包含可識別個人行為模式的風險越高（模組七 資安與隱私）。

噪音：分析時需要從大量事件中篩選出有意義的模式。事件越多，訊噪比越低。

設計好的行為事件直接成為 Funnel analysis 的輸入 — funnel 的每一步對應一個行為事件。行為事件在四類事件分類中屬於 Event 類，完整的分類定義見模組一 四類事件定義。收集行為事件前必須完成去識別化 — 使用者行為模式本身就是可識別資訊。

待寫章節

• 四類事件的完整定義（event / error / metric / lifecycle）
• 事件命名規範（namespace.action 格式）
• 商業方案的事件類型對應（Sentry / Crashlytics / GA4 / Datadog RUM）
• 從需求推導「該收集哪些事件」的方法

跨分類引用

• → testing 模組二 客戶端可觀測性：本模組教分類，testing 教設計 log 點
• → monitoring 模組八 商業利用：event 類是行為分析的原料
• → backend 04 可觀測性：server-side 用 OTLP，本系列用 HTTP POST JSON

概念位置

Refusal 行為的典型形態：

Refusal rate 作為偵測訊號的兩個方向：

1. 率突然下降：可能是對齊被繞過、prompt injection 攻擊在進行、或新版本模型對齊變弱。
2. 率突然上升：可能是訓練資料或對齊政策變嚴、影響使用者體驗、或 vendor 端政策調整。

實作上、偵測 refusal 通常用簡單 pattern matching（看是否含 “I can’t” / “I’m not able” / “Sorry” 等）或更精確的 classifier；具體實作依 偵測平台 設計。

事實查核註：refusal rate 的標準化測量方式、跟「對齊強度」的對應關係仍在研究演進、不同 vendor 跟 model 的 baseline 差異大、引用前以對應模型的 model card 跟最新研究為準。

設計責任

理解 refusal rate 後可以解釋兩個現象：為什麼 production LLM 服務監控 refusal rate（變化是異常訊號）、為什麼開源模型的 refusal rate 通常低於商業旗艦（前者 safety RLHF 投入較少）。

production 設計時、refusal rate 是 content 層偵測訊號之一、需配合 tool call 序列、token usage、prompt pattern 等其他訊號才能形成完整偵測覆蓋。詳見 LLM Service 偵測訊號覆蓋。

自架 vs 商業的判斷決策表用四個維度（使用者數 / 網路範圍 / 功能需求 / 合規）做二元分流。本章把光譜展開成四條路徑，讓中間的 BaaS 和 PaaS 選項浮現。Backend 選型模組已建立了完整的交付形態光譜（交付形態選型）和逐能力判斷外包深度的框架（能力級買 vs 建）。本章把那個框架特化到監控場景。

四條路徑

路徑 A 和 D 分別是光譜的兩端 — Sentry 深入、Firebase 套件和模組四 Collector 設計已完整討論。以下展開路徑 B 和 C。

路徑 B：BaaS + Serverless

APP 上線初期用 Supabase + Vercel（或 Cloudflare Workers）搭監控後端：serverless function 接收 SDK 送來的事件、驗證 schema 後寫入 Supabase 的 PostgreSQL。整條鏈路在免費方案額度內可以零成本運作。

架構差異

Serverless function 沒有常駐 process。模組四假設的 Go single binary 架構 — channel 背壓、single-writer goroutine pattern、in-memory buffer — 在 serverless 環境都不適用。每個 HTTP request 是獨立的 function invocation，沒有跨 request 的記憶體狀態。

背壓機制需要重新設計：Go collector 用 channel 容量做背壓（channel 滿回 429），serverless 版改用 DB-level 的 rate limit（PostgreSQL 的 advisory lock 或外部 rate limiter 如 Upstash Redis）或 platform-level 的 quota（Vercel 的 concurrency limit）。SDK 端的 429 處理邏輯不需要改 — 不管背壓訊號來自 channel 還是 DB quota，SDK 都是收到 429 後降採樣。

Downsample 和 purge 在 Go collector 是 background goroutine 定期執行。Serverless 沒有 background job — 需要外部 cron trigger（Vercel Cron / Supabase pg_cron / GitHub Actions scheduled workflow）。

免費方案限額

以下為 2026-06 查詢的各平台免費方案限額。平台定價會變動，決策前以官方定價頁為準。

Audit date: 2026-06。平台免費方案限額可能調整，決策前以官方定價頁為準。

適合情境

路徑 B 適合以下組合：APP 上線初期（使用者數 < 100）、團隊熟悉前端和 SQL 但不想管 server、想保留自訂 schema 和查詢彈性（商業 SaaS 的 schema 是 vendor 定義的）、零成本起步但未來可能遷到自架。

撞牆訊號

以下訊號出現時，代表路徑 B 的天花板已到、該評估遷到路徑 C 或 D：

連線數瓶頸：Supabase Free 的 PostgreSQL 約 20 個 concurrent connection。Serverless function 每次 invocation 開新連線，高併發時可能耗盡連線池。Supabase 內建 PgBouncer 做 connection pooling 可緩解，但免費方案的 pooler 有自己的連線上限。

Cold start 延遲：Vercel serverless function 的 cold start 約 200ms、Supabase Edge Function 約 100ms。對監控 ingestion（不是使用者面向 API）通常可接受，但如果 SDK 的 flush timeout 設得很短（< 1s），cold start 可能造成偶發超時。

Background job 限制：Downsample 和 purge 需要外部 cron。Vercel Hobby 支援最多 2 個 cron job、每個最頻繁每天觸發 1 次 — 如果需要每小時 downsample，要用 Supabase pg_cron（Free 方案支援）或外部 scheduler。

免費額度耗盡：Supabase 的 500K Edge Function invocations/月 ≈ 每天 16K requests。如果每個 request 攢批 100 筆事件，可處理每天 160 萬筆事件。超過後進入按量付費。Vercel Hobby 無明確 invocation 上限、瓶頸在 bandwidth（100GB/月）和 execution duration。

合規限制：Supabase Free 的 PostgreSQL 部署在特定 region。有 GDPR data residency 需求的 app（歐盟使用者的資料必須留在 EU）需確認 vendor 的 region 支援 — 免費方案的 region 選擇可能有限。

路徑 C：PaaS

PaaS 跑的是和完全自架相同的 Go collector 原始碼，差異只在部署方式。git push 觸發自動 build 和 deploy，平台管 server provisioning、TLS 憑證、process supervision。Collector 的 channel 背壓、single-writer pattern、SQLite storage 全部適用 — 和本機開發環境的行為一致。

Railway 和 Fly.io 都支援 persistent volume — Railway Hobby 含 1GB、Fly.io Free 含 1GB（限單 region）。SQLite 的 WAL 檔案需要持久化，persistent volume 是必要條件。Render 的免費方案沒有 persistent disk — SQLite 在每次 deploy 後重置，不適合需要保留歷史事件的場景。PaaS 平台以 container 形式運行 collector，SQLite 在 container 中的 I/O 和持久化考量見 Container 部署設計。

路徑 C 適合：想用自架 collector 但不想管 server / TLS / systemd 的團隊。程式碼完全相同，遷到自架（路徑 D）的成本接近零 — 把 binary 複製到 VPS、設定 systemd service 就完成。

路徑 C 的天花板在平台定價 — Railway Hobby 有 $5/月的資源上限、Fly.io Free 有 3 個 shared VM。流量成長到免費額度不夠時，PaaS 的按量付費和 VPS 月租費的交叉點是遷到自架的判讀訊號。

路徑間的遷移

遷移成本取決於起點和終點之間有多少層需要重寫。

路徑 B → C 或 B → D 的遷移代價主要在 collector 邏輯的重寫 — serverless function 的 request-level 處理和 Go binary 的 channel-based pipeline 是不同的架構，不能直接搬。資料層的遷移代價較低 — Supabase 的 PostgreSQL 資料可以用 pg_dump 匯出、匯入自管 PostgreSQL。

交付形態遷出的通用框架（資產線盤點、並行期設計、回切窗口）見 託管形態遷出。

外包深度對照

用 外包深度 的三層框架（managed 基礎設施 / feature SaaS / BaaS bundle）看四條路徑：

路徑 B 在外包深度上介於 managed 基礎設施和 BaaS bundle 之間 — DB 和 runtime 交給平台，但 collector 邏輯和 schema 仍由開發者控制。這和 BaaS 的「前端 SDK 直連平台資料庫」模式不同 — 監控場景的路徑 B 仍然有一個自己寫的中間層（serverless function），只是這個中間層跑在平台上而非自己的 server。

選擇建議

APP 上線初期選 B 或 A 取決於自訂需求 — 需要自訂 schema 和查詢邏輯（例如自定義 error fingerprint、行為事件命名規範）選 B，只需要開箱即用的 error tracking 或行為分析選 A。B 保留遷到自架的彈性（資料在自己的 PostgreSQL），A 的功能完成度更高（dashboard、告警、session replay 開箱即用）。

下一步路由

• 自架 vs 商業的詳細決策 → 自架 vs 商業的判斷決策表
• 自架 collector 的完整設計 → 模組四 Collector 設計
• Backend 交付形態光譜 → 交付形態選型
• 能力級買 vs 建判斷 → 能力級買 vs 建
• 外包深度概念 → 外包深度
• BaaS 概念 → BaaS
• 遷出劇本 → 託管形態遷出
• Vendor lock-in 概念 → Vendor Lock-In

Isolate 安全

Dart 的 Isolate 是獨立的記憶體空間，Isolate 之間不共享記憶體，只能透過 message passing 溝通。SDK 的記憶體 buffer 存在於 main isolate 中，其他 isolate 產生的事件需要透過 port 傳送到 main isolate 才能進入 buffer。

SDK 端的適配：

提供 Monitor.eventFromIsolate(SendPort port) 方法，在子 isolate 中透過 port 把事件送回 main isolate。或者提供 isolate-aware 的 Monitor.init() 變體，在子 isolate 中初始化一個輕量的 event forwarder。

如果 SDK 使用 compute 或 Isolate.spawn 做背景任務（例如壓縮 buffer），需要透過 port 把結果送回 main isolate — 背景 isolate 無法直接存取 main isolate 的 HTTP client 或 buffer。

Platform channel 攔截

Flutter 透過 Platform channel 呼叫原生平台功能（iOS 的 Swift/ObjC、Android 的 Kotlin/Java）。Platform channel 的呼叫可能失敗（原生端未實作、參數格式錯誤、原生端拋出例外），這些錯誤在 Dart 端表現為 PlatformException。

SDK 可以攔截 Platform channel 的呼叫記錄每次呼叫的方法名稱、參數、結果和耗時。攔截方式是替換 ServicesBinding.defaultBinaryMessenger 的處理器，在轉發前後記錄事件。

攔截的價值是：Platform channel 的錯誤通常難以 debug（stack trace 跨越 Dart 和原生兩層），監控記錄提供「呼叫了哪個 channel method、傳了什麼參數、在哪一層失敗」的完整 context。

注意：攔截 Platform channel 會增加每次呼叫的延遲（記錄事件的開銷）。對高頻的 Platform channel 呼叫（例如每幀都呼叫的渲染相關 channel），攔截可能影響效能。SDK 應該提供 channel 過濾機制 — 只攔截特定 channel 或只在 debug mode 攔截。

App lifecycle 事件

Flutter 的 WidgetsBindingObserver 提供 app 生命週期回呼：

• didChangeAppLifecycleState(AppLifecycleState state) — app 在 resumed（前景）、inactive（部分可見）、paused（背景）、detached（即將關閉）之間切換。

SDK 在 init 時註冊 observer，記錄每次狀態轉換為 lifecycle 事件。

lifecycle 事件在 flush 策略中有特殊意義：

paused（進入背景）：觸發 flush — 把 buffer 中的事件送出，因為 app 在背景可能被系統殺掉，buffer 中的事件會遺失。iOS 在 app 進入背景後約 5 秒 suspend，flush 必須在這個時間窗口內完成。

resumed（回到前景）：檢查上次 flush 是否成功。如果 paused 時的 flush 失敗（網路超時），在 resumed 時重試。

detached（即將關閉）：呼叫 Monitor.close() 做最後一次 flush 和資源釋放。detached 的時間窗口更短，close flush 可能被截斷。

下一步路由

• Python 平台的適配 → Python 平台適配
• 跨平台 timestamp 一致性 → 跨平台 timestamp 一致性
• 自動攔截機制 → 模組三 自動攔截

基本計算

Funnel 的每一步有兩個數字：進入人數和完成人數。轉換率 = 完成人數 / 進入人數。

以四步註冊 funnel 為例：

整體轉換率 = 310 / 1000 = 31%。但更有價值的資訊在每步的轉換率：步驟 2（填寫表單）流失 38%，步驟 4（email 驗證）流失 46.6%。這兩步是優化的優先目標。

流失原因的區分

Funnel analysis 指出「哪一步流失」，但不直接回答「為什麼流失」。流失原因需要結合其他資料推斷。

設計問題導致的流失

使用者看到表單但沒填寫（步驟 2 流失 38%）。可能原因：表單欄位太多、要求的資訊太敏感（信用卡號在註冊階段）、表單 UI 在特定裝置上有問題。

判斷方式：按平台、裝置、螢幕尺寸細分轉換率。如果 iOS 轉換率 70% 但 Android 只有 45%，可能是 Android 的表單 UI 有問題。

技術問題導致的流失

使用者送出表單但 email 驗證沒完成（步驟 4 流失 46.6%）。可能原因：驗證信被歸到垃圾郵件、驗證連結過期太快、驗證頁面載入失敗。

判斷方式：結合 error 事件。如果步驟 4 有大量 signup.email.verify.failed error，是技術問題；如果沒有 error 但流失高，使用者可能沒收到信或沒看到信。

意圖問題導致的流失

使用者到了註冊頁但根本沒打算註冊 — 只是瀏覽。這類流失不是問題，是正常的使用者行為。

判斷方式：看使用者在流失步驟停留的時間。停留 < 3 秒就離開，可能是誤點或沒有註冊意圖；停留 > 30 秒但沒完成，可能是遇到障礙。

Funnel 的時間窗口

同一個使用者在步驟 A 和步驟 B 之間隔了多久，仍算在同一個 funnel 內？時間窗口的設定影響 funnel 的計算結果。

窗口太短：使用者中途離開稍後回來完成，被計為流失。Funnel 的流失率被高估。

窗口太長：使用者今天瀏覽、一個月後被廣告重新帶回來完成，兩次獨立的意圖被合併成一個 funnel。轉換率被高估。

合理的窗口依業務場景而定：電商結帳 funnel 用 30 分鐘到 1 小時，SaaS onboarding 用 7 天，B2B 銷售漏斗用 30-90 天。

畫面狀態矩陣和 funnel 的關係

畫面狀態矩陣（ux-design 模組一）描述每個畫面的狀態和轉換。Funnel 描述使用者跨畫面的操作路徑。兩者的對應是：funnel 的每一步通常對應一個畫面狀態的進入事件。

狀態矩陣中的退出路徑（back 按鈕、取消操作）就是 funnel 的流失點。狀態矩陣的退出路徑為空 = UX 死胡同，funnel 分析中表現為「使用者進入後既沒完成也沒退出 — session 中斷」。

下一步路由

• 不同使用者群體的行為差異 → Cohort analysis
• 行為事件的設計 → 行為事件設計
• 自架方案做 funnel → 從 collector 資料做基礎 funnel 分析

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 設計
• 儲存撐不住時的演進 → 規模演進

概念位置

Redaction 位在 SDK 端的事件產生和 collector 端的事件接收之間。它是監控資料安全的第一道防線 — 在資料離開使用者裝置之前處理，比 collector 端的 access control 更早介入。Redaction 和 transport 加密（HTTPS）互補：redaction 保護欄位內容，transport 加密保護傳輸過程。

可觀察訊號與例子

系統需要 redaction 的訊號是監控事件的 data 欄位可能包含使用者輸入。CLI 輸入可能含密碼（mysql -p'secret'）、API key（Authorization: Bearer sk-...）、連線字串（含帳密的 URL）。IME 個人化學習也是洩漏面 — 輸入框的內容被 IME 學習後跨 app 可見。

設計責任

Redaction 要定義預設規則（哪些欄位名稱自動 redact）、自訂 pattern（正則表達式比對敏感值）、執行時機（event 進入 buffer 前還是 flush 時）、以及 redaction 失敗的處理（丟棄整筆事件 vs 只移除敏感欄位）。

跟 Backend 04 的分工：本文從 client-side 使用角度說明 Sentry 的 error tracking、performance monitoring 與 session replay — SDK 怎麼埋、error 怎麼分群、release 怎麼追蹤。Server-side 平台治理（告警路由整合、SLI 指標設計、self-hosted vs SaaS 成本治理、跟 OTel 的整合）見 Backend 04 Sentry vendor page。

Sentry 的核心是 error tracking — 自動捕獲未處理的例外、提供 stack trace、自動分群（grouping）相同 root cause 的 error。在 error tracking 的基礎上，Sentry 擴展了 performance monitoring（transaction / span）和 session replay（重播使用者操作）。

Error tracking

Sentry 的 error tracking 架構有三個層次：SDK 端的自動捕獲、server 端的 issue grouping 和 UI 端的 issue management。

自動捕獲

Sentry SDK 在各平台註冊全域錯誤處理器（和模組三 自動攔截的機制相同）。捕獲到例外後，SDK 收集 stack trace、breadcrumbs（最近的使用者操作）、device context（OS / browser / device model）和自訂 tags，打包成 event 送到 Sentry server。

Issue grouping

Sentry server 收到 error event 後，用 fingerprinting 演算法判斷這個 error 是否和已有的 issue 相同。預設的 fingerprinting 基於 stack trace 的 frame — 如果兩個 error 的 stack trace 指向同一個位置，歸入同一個 issue。

自訂 fingerprint 讓開發者控制 grouping 邏輯。例如：不同使用者觸發的同一個 API error 可能有不同的 stack trace（因為 call site 不同），但 root cause 相同 — 自訂 fingerprint 把它們歸入同一個 issue。

Issue management

每個 issue 有狀態（unresolved / resolved / ignored）、指派（誰負責修復）、趨勢（這個 issue 的發生頻率是上升還是下降）。Sentry 的 UI 提供 issue 列表、趨勢圖、影響範圍（影響多少使用者）。

Performance monitoring

Sentry 的 performance monitoring 用 transaction 和 span 模型（和 OpenTelemetry 的 trace / span 概念相同）。

Transaction 代表一個完整的操作（頁面載入、API 請求處理）。Span 是 transaction 內的子操作（database query、外部 API 呼叫）。Transaction 和 span 的 duration 構成操作的時間分佈。

Performance monitoring 的價值是發現「慢」的問題 — P95 回應時間超過閾值、特定 span 佔了 transaction 80% 的時間。和 error tracking 互補：error 告訴你「什麼壞了」，performance 告訴你「什麼慢了」。

Session replay

Session replay 錄製使用者的操作過程 — DOM 變化、滑鼠移動、點擊事件 — 在 Sentry UI 中重播。開發者可以看到「使用者在觸發 error 之前做了什麼操作」。

Session replay 的實作是 DOM snapshot + mutation recording。記錄的是 DOM 結構的變化（非螢幕錄影），在重播時重建 DOM。資料量比錄影小很多，但仍然是所有 Sentry 功能中資料量最大的。

隱私考量：session replay 會看到使用者輸入的內容（除非做 masking）。Sentry 提供 privacy configuration 控制哪些元素被 mask（輸入框、敏感資料區域）。

自架方案和 Sentry 的差距

Sentry 的核心價值在 issue grouping 和趨勢分析 — 把大量 error event 歸類成可管理的 issue 列表，自動追蹤每個 issue 的趨勢。自架方案用 grep 做不到自動 grouping。

下一步路由

• Firebase 的整合方案 → Firebase 套件
• Datadog 的全棧 APM → Datadog RUM
• 自架 vs 商業的判斷 → 自架 vs 商業的判斷決策表
• 自架方案的 error fingerprint 實作 → Error Fingerprint 與去重分群

同區網也要加密的理由

自用工具的 SDK 和 collector 通常在同一台機器或同一個區域網路（LAN / Tailscale tailnet）。常見的假設是「同區網不需要加密，因為只有我自己在用」。

這個假設在以下情境不成立：

共用網路：咖啡廳、共享辦公室、飯店 WiFi — 同一個 AP 下的其他裝置可以用 ARP spoofing 或 WiFi sniffing 攔截未加密的 HTTP 流量。

未來的網路拓撲變更：目前在同一台機器上的 SDK 和 collector，可能之後拆到不同的機器或不同的網路段。如果一開始就用 HTTPS，拓撲變更不需要額外的安全調整。

養成正確習慣：在自用工具上用 HTTP 是因為「反正只有我」，但相同的開發者在商業專案中可能延續這個習慣。從自用工具開始就用 HTTPS，讓加密傳輸成為預設行為。

HTTPS 設定

自簽憑證

自用工具和內部服務用自簽憑證（self-signed certificate）就足夠。不需要購買 CA 憑證 — 自簽憑證提供加密（防竊聽）和完整性（防篡改），只是不提供身份驗證（client 無法確認 server 是不是「官方的」）。在自用場景中 server 就是自己架的，身份驗證不是問題。

1openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes

Go collector 使用自簽憑證：

1http.ListenAndServeTLS(":8443", "cert.pem", "key.pem", handler)

SDK 端需要信任自簽憑證。開發期可以在 HTTP client 設定 badCertificateCallback 接受自簽憑證；production 應該把自簽憑證加入系統的信任清單。

Let’s Encrypt

如果 collector 有公開的 domain name，用 Let’s Encrypt 取得免費的 CA 憑證。自動續期、不需要手動管理。適合部署在 VPS 或雲端的 collector。

Basic Auth

HTTPS 保護傳輸層（防竊聽），basic auth 保護 endpoint 層（防未授權存取）。兩者互補，缺一不可 — basic auth 在 HTTP 上傳送的是 base64 編碼的帳密，沒有 HTTPS 的加密保護等於明文傳送。

1Authorization: Basic base64(username:password)

SDK 在每個 HTTP POST request 的 header 中帶上 basic auth。Collector 端驗證帳密，不匹配則回傳 401。

Basic auth 的帳密管理：

• 帳密存在 SDK 的設定檔或環境變數中，不硬編碼在程式碼裡
• Collector 端的帳密用 bcrypt hash 儲存，不存明文
• 定期輪替帳密（自用工具半年到一年一次即可）

API Key 替代方案

如果不需要 username/password 的雙因素，單一 API key 更簡單。

1X-API-Key: sk_monitor_abc123...

API key 的管理比 basic auth 簡單（一個字串而非帳密對），但安全性略低（只有一個 factor）。自用工具場景下 API key 通常足夠。

下一步路由

• SDK 端的 redaction → SDK Redaction API 設計
• Collector 端的 access control → Collector Access Control 實作
• Server-side 的 secret management → backend 07 資安

各平台的攔截點

JavaScript / TypeScript

JS 環境有兩個全域錯誤攔截點：

window.onerror 捕獲同步程式碼中未處理的例外。回呼函式收到 error message、來源 URL、行號、列號和 Error 物件。

window.onunhandledrejection 捕獲未處理的 Promise rejection。回呼函式收到 PromiseRejectionEvent，包含 rejection reason。

SDK 在 init 時註冊這兩個處理器。註冊前先保存原有的處理器（如果有），攔截後先呼叫原有處理器再執行 SDK 的記錄邏輯 — 避免覆蓋應用程式已有的錯誤處理。

限制：onerror 對跨域腳本的錯誤只收到 Script error. 訊息，沒有 stack trace。需要在 <script> 標籤加 crossorigin 屬性，server 端的 CORS header 加 Access-Control-Allow-Origin。

Flutter

Flutter 有兩個攔截層：

FlutterError.onError 捕獲 widget build / layout / paint 過程中的例外。預設行為是在 console 印出錯誤，SDK 替換為記錄 error 事件後再呼叫預設處理器。

PlatformDispatcher.instance.onError 捕獲其他非同步區域的未處理例外（Dart 2.15+）。包含 Isolate 內的未捕獲例外。

runZonedGuarded 是另一個選項 — 在指定的 Zone 內捕獲所有未處理例外。SDK 可以用 runZonedGuarded 包住整個 runApp()，但這和 PlatformDispatcher.onError 有重疊，需要避免同一個例外被記錄兩次。

限制：Flutter 的 release mode 會移除 stack trace 的符號資訊（obfuscation）。需要保留 debug symbols 檔案（.dSYM / mapping.txt），在 collector 端做 symbolication。

Python

sys.excepthook 處理主執行緒的未捕獲例外。回呼函式收到 exception type、value 和 traceback。

threading.excepthook（Python 3.8+）處理子執行緒的未捕獲例外。

atexit.register 用於在 Python 程序退出時 flush 剩餘的 buffer。但 atexit 在 os._exit() 或 SIGKILL 時不會執行。

限制：Python 的 GIL 讓 SDK 的網路操作可能阻塞主執行緒。SDK 的 flush 應該在獨立的 daemon thread 中執行，主執行緒只負責把事件放入 buffer。

攔截後的統一處理

不同平台的錯誤物件格式不同（JS 的 Error、Flutter 的 FlutterErrorDetails、Python 的 sys.exc_info tuple）。SDK 在攔截後把平台特定的錯誤物件轉換為統一的 error 事件格式：

• type: "error"
• name: 從 error class name 推導（TypeError → error.TypeError）
• data: 包含 message、stack trace（字串化）、觸發位置

轉換層是每個平台 SDK 唯一的平台特定程式碼。轉換完成後，事件進入和手動上報相同的 buffer → flush 管線。

和手動上報的分工

自動攔截處理「開發者沒有預期到的錯誤」— 未捕獲的例外、未處理的 rejection。手動上報（Monitor.error()）處理「開發者知道可能發生但想記錄的錯誤」— 已捕獲的例外、業務邏輯的異常狀態。

兩者進入同一個 buffer 和 flush 管線，在 collector 端可以用 data 中的 source: "auto" / source: "manual" 欄位區分。

下一步路由

• SDK 公開 API → SDK 公開 API 設計
• 各平台的深入適配問題 → 模組五 平台適配
• Buffer 和 flush → 攢批送出策略
• 主動感測器設計（和被動攔截互補）→ 前端感測器設計

namespace.action 格式

每個事件名稱由兩部分組成：namespace（事件發生的模組或功能區域）和 action（發生了什麼）。用 . 分隔。

1terminal.connect.start      ← namespace: terminal.connect, action: start
2terminal.connect.done       ← namespace: terminal.connect, action: done
3terminal.input.submit       ← namespace: terminal.input, action: submit
4auth.biometric.success      ← namespace: auth.biometric, action: success
5auth.biometric.fallback     ← namespace: auth.biometric, action: fallback
6enrollment.qr.scan          ← namespace: enrollment.qr, action: scan

Namespace 層級

Namespace 的層級深度依功能結構而定。兩層通常足夠（terminal.connect），三層用於需要進一步區分的場景（terminal.connect.ws）。超過三層通常代表 namespace 設計過細，增加認知成本但不增加分析價值。

Action 命名

Action 使用動詞（start、submit、scan）或狀態（success、failed、timeout）。同一組動作用配對的 action 名稱：start / done（成對的生命週期）、success / failed（結果分支）。

避免在 action 中重複 namespace 的資訊。terminal.connect.terminal_connected 中 terminal 重複了；terminal.connect.done 更簡潔。

命名一致性的工程價值

Grep 友好

統一的 namespace 結構讓開發者用 grep "terminal.connect" 就能找到所有連線相關事件，不需要知道每個事件的完整名稱。

統計友好

按 namespace 前綴分群統計。terminal.* 的事件數量 = terminal 功能的使用頻率；auth.* 的事件數量 = 認證觸發頻率。層級結構讓統計的粒度可以調整。

文件友好

事件清單按 namespace 排列就是一份結構化的功能地圖。新加入的開發者讀事件清單就能理解系統有哪些功能模組。

和商業方案的命名對應

不同的商業監控方案有各自的命名慣例。自架方案用 namespace.action 格式，接入商業方案時需要做對應。

對應時保持一個原則：自架方案的事件名稱是 source of truth，商業方案的名稱是它的映射。在自架方案中改名後，映射層跟著改；不要讓商業方案的命名反過來影響自架的命名結構。

下一步路由

• 四類事件的定義 → 四類事件的完整定義
• 從需求推導收集策略 → 從需求推導「該收集哪些事件」
• 商業方案的完整比較 → 模組六 商業方案比較

待寫章節

• event.schema.json 完整欄位解說
• 欄位設計原則（source 標明來源 / data 自由欄位 / v 版本演進）
• Schema 版本演進策略（backward compatible 的增量變更）
• 跟 OpenTelemetry 的 schema 差異對照

跨分類引用

• SOT repo：tarrragon/monitor 的 schema/event.schema.json
• ← testing 模組二：log 點設計產出的事件需符合本 schema
• → monitoring 模組七 資安：schema 中哪些欄位需要 redaction

原則一：source 標明來源

每筆事件的 source 欄位記錄「這筆事件從哪裡來」。App 名稱、版本、平台、OS 版本 — 這些資訊在事件產生時由 SDK 自動填入，不依賴使用者或開發者手動標記。

source 的設計要點是「足夠區分但不過度」。sdk 和 platform 是必填——sdk 標明事件由哪個 SDK 實作產生（js / flutter / python / go），platform 標明運行平台（ios / android / web / macos）。兩者不能互相推導：同一個 platform（iOS）上可能有不同的 SDK（Flutter SDK 或 Swift 原生 SDK），同一個 SDK（Flutter）可能跑在不同 platform（iOS / Android / Web）。App 名稱和版本能區分「這是哪個 app 的哪個版本送來的事件」。OS 版本用於分析平台特定的問題（「這個 error 只出現在 iOS 17.4」）。

不需要在 source 放裝置 ID 或使用者 ID — 這些屬於個人識別資訊，放在 source 會讓每一筆事件都攜帶 PII，增加去識別化的複雜度。Session ID 用於關聯同次使用的事件，已足夠取代裝置/使用者級別的追蹤。

原則二：data 自由欄位

data 欄位是事件的附加資料區域，接受任意 JSON object。核心欄位（type、name、timestamp、source）有固定的 schema 驗證，data 的內容不做 schema 驗證（或做寬鬆驗證）。

自由欄位的設計理由是「不同事件需要不同的附加資料」。terminal.connect.done 需要 URL 和 duration；auth.biometric.failed 需要 error code 和 fallback 方式。為每種事件定義固定的 data schema 會讓 schema 膨脹且頻繁變動。

自由的代價是查詢時無法保證 data 內某個欄位一定存在。處理策略：查詢時用 optional access（data?.duration_ms），統計時跳過缺少目標欄位的事件。

原則三：v 版本演進

v 欄位是整數版本號，標明「這筆事件是用哪個版本的 schema 產生的」。

版本號解決的問題是 schema 變更時的向後相容。新版本的 SDK 產生 v=2 的事件，舊版本的 SDK 仍在產生 v=1 的事件。Collector 收到事件時根據 v 決定用哪個版本的驗證和處理邏輯。

版本號的遞增規則：

• 新增選填欄位：不需要遞增版本號。舊版事件缺少新欄位，collector 用預設值處理。
• 新增必填欄位：遞增版本號。舊版事件沒有這個欄位，collector 需要區分版本處理。
• 刪除或改名欄位：遞增版本號。collector 需要同時支援新舊版本的事件格式。
• 改變欄位型別：遞增版本號。string 改成 integer 等型別變更需要不同的解析邏輯。

欄位命名慣例

欄位名稱使用 snake_case（duration_ms、error_code），和 JSON 的慣例一致。避免在欄位名稱中編碼單位（duration 不夠明確 — 是秒還是毫秒？），在名稱中加上單位後綴（duration_ms、size_bytes）。

下一步路由

• 完整欄位定義 → event.schema.json 完整欄位解說
• Schema 版本演進的具體策略 → Schema 版本演進策略
• 和 OpenTelemetry 的比較 → 跟 OpenTelemetry 的 schema 差異對照

Cohort 的定義方式

時間 cohort（最常用）

按使用者完成某個動作的時間分群。「1 月份註冊的使用者」「第 12 週 onboarding 完成的使用者」。

時間 cohort 回答的問題：產品的留存率是否隨時間改善？新版本上線後註冊的使用者留存是否比舊版本高？

行為 cohort

按使用者的行為特徵分群。「首次使用就完成購買的使用者」「使用過搜尋功能的使用者」「連續 3 天登入的使用者」。

行為 cohort 回答的問題：哪些行為和留存相關？做了 X 的使用者留存率是否比沒做 X 的高？

屬性 cohort

按使用者的固有屬性分群。「iOS 使用者」「企業方案使用者」「來自特定廣告渠道的使用者」。

屬性 cohort 回答的問題：不同平台/方案/來源的使用者行為是否不同？

留存率矩陣

留存率矩陣是 cohort analysis 最常見的呈現方式。每行代表一個 cohort（例如某月註冊的使用者），每列代表註冊後的第 N 天/週/月，格中的值是該 cohort 在第 N 期仍活躍的比例。

從這張矩陣可以看到：留存率逐月改善（1 月 → 3 月的第 1 週留存從 45% 升到 52%）。如果 2 月有產品改版，這個改善可能和改版相關。

Cohort analysis 的判讀

自然衰減 vs 產品問題

所有產品都有自然衰減 — 使用者隨時間減少是正常的。Cohort analysis 的價值在於區分「正常衰減」和「異常衰減」。

如果所有 cohort 的衰減曲線形狀相似，衰減是產品層面的結構性問題（例如缺少持續使用的理由）。如果某個 cohort 的衰減明顯比其他 cohort 快，需要調查該 cohort 的特殊情況（當時的產品版本、市場環境、使用者來源）。

穩態留存

留存率通常在某個時間點後趨於穩定 — 留下來的使用者不再大量流失。穩態留存的百分比和到達穩態的時間是產品健康度的核心指標。

穩態留存高但到達時間長 = 產品有價值但 onboarding 需要改善。穩態留存低 = 產品的持續使用價值不足。

和 funnel 的關係

Funnel analysis 回答「使用者在哪一步流失」（單次流程），cohort analysis 回答「使用者是否持續回來」（長期行為）。兩者互補：funnel 改善單次流程的轉換率，cohort 追蹤改善是否帶來長期留存的變化。

下一步路由

• 使用者從哪來 → Attribution
• 單次流程的流失分析 → Funnel analysis
• 使用者分群的工程實作 → RFM 分群
• 客戶終身價值 → LTV
• 留存率 → Retention

概念位置

Cohort analysis 位在 funnel analysis 之後、策略制定之前。Funnel analysis 回答「使用者在哪一步流失」，cohort analysis 回答「哪種使用者流失率高」。兩者搭配使用：funnel 找到流失步驟，cohort 找到流失群組，策略針對特定群組的流失步驟設計。

可觀察訊號與例子

產品需要 cohort analysis 的訊號是「整體留存率或轉換率的平均值遮蔽了群組差異」。整體 30 天留存率 40%，但按註冊來源拆分後發現自然搜尋來的使用者留存 60%、廣告來的使用者留存 20% — 平均值沒有揭露這個差異。

設計責任

Cohort analysis 要定義分群維度（按什麼特徵分）、觀察指標（留存率、活躍度、付費率）、觀察時間窗口（7 天、30 天、90 天）、以及最小群組大小（群組太小時統計不顯著）。分群維度的選擇決定了分析能揭露什麼 — 按「註冊來源」分群能看到獲客通路的品質差異，按「使用的功能」分群能看到功能黏著度差異。

認證：來源是誰

認證驗證送出資料的 client 是否合法。未認證的 request 應該被拒絕，避免任意來源向 collector 寫入資料。

API Key 認證

每個合法的 SDK client 有一個 API key。Collector 檢查 request header 中的 API key 是否在合法清單中。

 1func authMiddleware(next http.Handler) http.Handler {
 2    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 3        key := r.Header.Get("X-API-Key")
 4        if !isValidKey(key) {
 5            http.Error(w, "unauthorized", http.StatusUnauthorized)
 6            return
 7        }
 8        next.ServeHTTP(w, r)
 9    })
10}

自用工具場景下，一個 API key 對應一個 client 通常就足夠。多個 client（例如同一個 app 的 iOS 和 Android 版本）可以用同一個 key，或每個平台一個 key 以便在 access log 中區分來源。

mTLS（Mutual TLS）

Client 和 server 互相驗證對方的憑證。安全性比 API key 高 — 攻擊者即使取得 API key，沒有 client 憑證也無法連線。

mTLS 的設定成本較高（每個 client 需要產生和管理憑證），適合對安全性要求較高的環境。自用工具通常不需要 mTLS。

授權：允許做什麼

授權控制已認證的 client 可以執行哪些操作。Collector 的操作通常分為兩類：寫入事件和查詢事件。

角色分離

最簡單的授權模型是兩個角色：

• Writer：只能寫入事件（POST /events）。SDK client 使用這個角色。
• Reader：只能查詢事件（GET /events、GET /query）。開發者的 CLI 工具使用這個角色。

角色分離的價值在於限制洩漏的影響範圍。如果 SDK 的 API key 被洩漏，攻擊者只能寫入（產生垃圾事件），不能讀取（看到歷史事件中的敏感資訊）。

寫入限制

即使認證通過、角色正確，collector 也可以對寫入加上限制：

• Rate limit：每個 API key 每分鐘最多 N 個 request。防止 client 端 bug 導致事件風暴。
• Payload size limit：每個事件最大 M KB。防止異常大的 event data 消耗儲存。
• Schema validation：事件必須符合定義的 JSON schema。格式不正確的事件拒絕存入。

Access Log：誰做了什麼

Access log 記錄每個到達 collector 的 request — 來源 IP、API key（或 key 的 hash）、操作類型、時間戳、response status。

Access log 的用途：

安全審計：發現異常行為 — 未知 IP 的大量寫入、非工作時間的讀取、連續的認證失敗。

問題排查：SDK 說事件送出成功但 collector 沒有收到 — access log 可以確認 request 是否到達、response 是什麼。

用量統計：每個 client 送了多少事件、佔多少儲存。

Access log 本身也是監控資料，但和業務事件分開儲存。Access log 存在 collector 本機的 log 檔中，用系統的 logrotate 管理輪替。

12026-06-19T10:30:00Z POST /events key=sk_mon_ab...cd ip=192.168.1.50 status=200 size=1234
22026-06-19T10:30:01Z POST /events key=INVALID ip=10.0.0.99 status=401 size=0
32026-06-19T10:31:00Z GET /query key=sk_read_ef...gh ip=192.168.1.1 status=200 size=8901

下一步路由

• SDK 端的 redaction → SDK Redaction API 設計
• Transport 層的加密 → Transport 安全
• 資料儲存後的去識別化 → 去識別化策略
• Client-side credential 暴露的根本限制 → Client-side SDK 認證

Crashlytics

Firebase Crashlytics 專注在 crash 報告 — fatal crash（app 當機）和 non-fatal exception（被捕獲但值得記錄的錯誤）。

自動 crash 報告

Crashlytics SDK 在 app crash 時自動收集 crash 資訊（stack trace、device info、OS version），在下次 app 啟動時上傳。不需要開發者寫程式碼 — SDK 初始化後自動運作。

Issue 分群

和 Sentry 類似，Crashlytics 用 stack trace 自動把 crash 分群成 issue。每個 issue 有影響的使用者數、趨勢、crash-free session 比率。

和 Analytics 的關聯

Crashlytics 可以在 crash 報告中附加 Analytics 的使用者屬性和自訂 key。但兩者的 dashboard 獨立 — crash 資料在 Crashlytics console，行為資料在 Analytics console。要從「crash」追蹤到「crash 前使用者做了什麼」需要在兩個 console 之間切換。

Analytics（GA4）

Firebase Analytics 是 Google Analytics 4（GA4）的 mobile SDK 版本。記錄使用者操作事件（screen view、button click、purchase）和使用者屬性。

自動收集事件

GA4 SDK 自動收集一組預定義事件：first_open、session_start、screen_view、user_engagement。開發者不需要手動埋點就能得到基礎的使用統計。

自訂事件

開發者用 logEvent(name, parameters) 記錄自訂事件。事件名稱和參數的命名有限制（名稱 40 字元、參數 25 個、參數值 100 字元）。

和四類事件的對應

GA4 主要處理 Event 類和 Lifecycle 類事件（模組一）。Error 類由 Crashlytics 處理。Metric 類沒有原生支援 — 需要把 metric 包裝成 event 的 parameter。

Remote Config

Firebase Remote Config 讓開發者在不更新 app 的情況下修改 app 的行為 — 功能旗標（feature flag）、UI 文案、數值參數。

和 A/B test 的整合

Remote Config 和 Firebase A/B Testing 整合：定義實驗（variant A: 舊 UI / variant B: 新 UI），Remote Config 自動分配使用者到 variant，Analytics 收集兩組使用者的行為數據，A/B Testing console 顯示統計結果。

這個整合是 Firebase 生態的獨特優勢 — config 分發、使用者分群、行為收集、統計分析在同一個平台完成，不需要整合多個工具。

Firebase 的取捨

Firebase 的設計取捨是「拆分但整合」— 每個產品獨立運作（可以只用 Crashlytics 不用 Analytics），但組合使用時有整合優勢（Crashlytics + Analytics 的 user ID 共享）。

下一步路由

• Datadog 的全棧 APM → Datadog RUM
• 行為分析專用方案 → Mixpanel / Amplitude
• 自架 vs 商業的判斷 → 自架 vs 商業的判斷決策表

GIL 與 threading

Python 的 Global Interpreter Lock（GIL）讓同一時間只有一個 thread 執行 Python bytecode。SDK 的 flush 操作（HTTP POST 到 collector）如果在主 thread 執行，會阻塞主程式的其他工作。

SDK 端的適配：

在 daemon thread 中執行 flush。Daemon thread 在主 thread 結束時自動終止，不需要手動 join。SDK 的 flush 計時器在 daemon thread 中運行，buffer 的存取用 threading.Lock 保護。

GIL 對 SDK 的影響比想像的小：HTTP 請求是 I/O bound 操作，CPython 在等待 I/O 時釋放 GIL。所以 flush 的 HTTP POST 在 daemon thread 中執行時，主 thread 可以繼續工作。GIL 只在 CPU-bound 的操作上造成瓶頸 — SDK 的 buffer 操作和事件序列化是 CPU-bound 但耗時極短（微秒級），影響可忽略。

asyncio 環境

Python 的 asyncio 程式（FastAPI、aiohttp）使用事件迴圈而非 threading。SDK 在 asyncio 環境中應該用 asyncio.create_task 而非 threading 執行 flush，避免在事件迴圈中阻塞。

SDK 可以在 init 時自動偵測是否在 asyncio 環境中（檢查 asyncio.get_running_loop() 是否存在），自動切換 flush 的執行方式。

atexit 可靠性

atexit.register 在 Python 程序正常退出時執行註冊的清理函式。SDK 在 init 時註冊 atexit handler 做最後一次 flush。

atexit 不執行的場景：

• os._exit() 直接終止 process，跳過所有清理
• SIGKILL（kill -9）強制終止，作業系統直接回收 process
• 未處理的 fatal signal（SIGSEGV、SIGABRT）導致 crash

對於 SIGTERM 和 SIGINT，Python 預設會執行 atexit handler（前提是 signal handler 沒有被覆蓋）。SDK 可以額外註冊 signal.signal(signal.SIGTERM, handler) 確保在收到 SIGTERM 時觸發 flush。

實務影響：os._exit() 和 SIGKILL 導致的事件遺失無法避免。使用本地 persistence（離線 buffer）可以降低影響 — 事件在寫入本地檔案後，即使 process 被強制終止，下次啟動時仍可補發。

短生命週期腳本

SDK 的預設設計假設長期運行的 app — flush interval 定期觸發、daemon thread 持續運行、atexit 是最後防線。但 Python SDK 的一個重要場景是短命腳本（CI/CD hook、pre-commit hook、CLI 工具的子命令），生命週期可能 < 1 秒。這個場景下 SDK 的行為和長期 app 完全不同。

什麼會壞

flush interval 來不及觸發。預設 30 秒的 flush interval，但腳本在 200ms 內結束。計時器還沒觸發，buffer 中的事件從未送出。

daemon thread 隨主 thread 結束。SDK 用 daemon thread 執行 flush 計時器。Python 的 daemon thread 在最後一個非 daemon thread 結束時被殺 — 不會等待 daemon thread 完成當前工作。如果 flush 正在進行中（HTTP POST 送到一半），daemon thread 被殺，HTTP 請求中斷，事件丟失。

atexit 的執行順序不確定。atexit handler 在 daemon thread 被殺之後執行。如果 SDK 的 atexit handler 嘗試在 daemon thread 中 flush，會失敗（thread 已死）。atexit handler 必須在主 thread 中同步 flush。

正確的短命腳本模式

1from monitor import Monitor
2
3Monitor.init(endpoint="http://localhost:9090/v1/events", app="my-hook")
4
5# 做事...
6Monitor.event("hook.run", {"hook": "branch-check"})
7
8# 結束前必須呼叫 close
9Monitor.close()  # close 內同步 flush，不依賴 daemon thread

close() 是唯一可靠的 flush 時機。close() 的實作在短命腳本場景下必須：

1. 同步執行 HTTP POST，不委託給 daemon thread — 主 thread 呼叫 close() 時直接在當前 thread 送出
2. 設 HTTP timeout — 短命腳本不能等太久，3 秒的 timeout 是合理的
3. flush 失敗時靜默放棄 — 短命腳本的主要職責不是監控，SDK 失敗不應影響腳本的 exit code

atexit 仍然註冊，作為開發者忘記呼叫 close() 的備份。但 atexit 是 best-effort — 在 os._exit() 和 SIGKILL 下不執行。

flush interval 在短命腳本中的角色

flush interval 對短命腳本無意義 — 腳本在第一次 interval 觸發前就結束了。SDK 可以偵測「init 到 close 的間隔 < flush interval」的模式，在 debug log 中提示開發者考慮降低 interval 或直接依賴 close() flush。

但不建議把 flush interval 設為 0（停用）— 同一個 SDK 設定可能同時用於長期 app 和短命腳本，interval 對長期 app 仍然有用。

Subprocess 監控

Python 程式中的 subprocess.Popen 啟動的子程序是獨立的 process，不共享 SDK 的 buffer 和網路連線。子程序的錯誤和事件需要獨立的監控機制。

兩種方式：

子程序獨立初始化 SDK：子程序的 Python 腳本自己呼叫 Monitor.init()，獨立送事件到 collector。適合子程序是長時間運行的 Python 程式。

父程序代理：父程序讀取子程序的 stdout/stderr，從輸出中解析事件（子程序用約定格式印出事件），父程序的 SDK 代理送出。適合子程序是短命的腳本或非 Python 程式。

下一步路由

• Go 平台的適配 → Go 平台適配
• 跨平台 timestamp 一致性 → 跨平台 timestamp 一致性
• 離線 buffer 策略 → 模組三 離線 buffer 與重試

不需要改版的變更

新增選填欄位

在 data 區域新增欄位。舊版 SDK 送來的事件不包含這個欄位，collector 和查詢工具用「欄位不存在則忽略」的邏輯處理。

例：v=1 的事件沒有 data.duration_ms，v=1 的 SDK 升級後開始送 data.duration_ms。Collector 不需要改 — 新欄位出現在 data 自由區域，不影響 schema 驗證。查詢時用 optional access。

新增事件名稱

新功能加入新的事件名稱（enrollment.qr.scan）。事件名稱不受 schema 版本控制 — schema 定義的是事件的結構，不是事件名稱的清單。

需要改版的變更

新增核心必填欄位

在核心區域（type、name、timestamp、source 同層）新增必填欄位。舊版 SDK 不會送這個欄位，collector 需要根據版本號決定是否要求這個欄位。

例：v=2 新增必填的 environment 欄位（production / staging / development）。v=1 的事件沒有這個欄位，collector 對 v=1 不要求 environment，對 v=2 要求 environment。

改變欄位型別

把 duration 從 string（"320ms"）改成 integer（320）。同一個欄位的兩種型別需要不同的解析邏輯，collector 用版本號區分。

刪除或重新命名欄位

刪除欄位或改名（error_msg → error_message）需要改版。Collector 對舊版本讀舊欄位名，對新版本讀新欄位名。

Collector 的多版本支援

Collector 同時接收不同版本的事件。處理策略：

版本分派

收到事件後先讀 v 欄位，分派到對應版本的處理器。每個版本的處理器知道該版本的欄位結構和驗證規則。

正規化

不同版本的事件正規化成統一的內部格式後儲存。正規化層處理欄位名稱對應（error_msg → error_message）和型別轉換（string → integer）。查詢時只面對正規化後的格式。

版本淘汰

當所有 SDK 都升級到 v=2 後（從事件記錄中確認不再收到 v=1），可以移除 v=1 的處理器。淘汰前確認沒有離線 buffer 中的 v=1 事件尚未送達。

實務建議

遲改版優於早改版。每次改版增加 collector 的複雜度（多一個版本的處理器）。如果變更可以用「新增選填欄位」解決，優先選擇不改版。

一次改版包含多個變更。如果確定要改版，把多個計畫中的 breaking change 合併到同一次版本升級。v=1 → v=2 包含三個 breaking change，比 v=1 → v=2 → v=3 → v=4 各包含一個 breaking change 的維護成本低。

Schema 文件和版本號同步。每個版本的 schema 有對應的文件，記錄該版本和前一版本的差異。

下一步路由

• 完整欄位定義 → event.schema.json 完整欄位解說
• 欄位設計原則 → 欄位設計原則
• 和 OpenTelemetry 的比較 → 跟 OpenTelemetry 的 schema 差異對照

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 架構

Sentry

Sentry 的核心概念是 error tracking，但已擴展到 performance monitoring 和 session replay。

Sentry 的設計假設是「error 是主角，其他事件是 error 的 context」。Event 和 lifecycle 都以 breadcrumb 形式附加在 error 報告上，獨立查看的能力有限。Breadcrumb 預設保留最近 100 條且不可獨立查詢 — 它是 error 報告的附件，不是獨立的事件資料庫。Metric 對應的 Transaction + Span 則有獨立的 Performance 頁面可以查看，和 error 是不同的 UI 入口。如果主要需求是行為分析而非 error tracking，Sentry 的 breadcrumb 模型可能不夠用。

Firebase Crashlytics + Analytics

Firebase 把 error tracking 和行為分析拆成兩個獨立產品。

Firebase 的特點是 Crashlytics 和 Analytics 各自獨立運作 — error 資料在 Crashlytics console，行為資料在 Analytics console。Metric 沒有原生支援，只能用 Analytics event 的 parameters 欄位記錄數值（例如 event: 'page_load', parameters: {duration_ms: 320}），查詢時需要在 BigQuery export 中自行聚合。兩個 console 之間的關聯需要手動（在 Crashlytics 的 custom key 中設定 user ID，再到 Analytics 用同一個 ID 查行為）。

Datadog RUM

Datadog Real User Monitoring 從全棧 APM 的角度設計 client-side 監控。

Datadog RUM 的特點是和 backend APM 的深度整合。Client-side 的 action 可以關聯到 server-side 的 trace，形成從按鈕點擊到 database query 的完整鏈路。自架方案通常做不到這個深度的跨層關聯。

接入策略

接入商業方案時的映射原則：

自架事件名稱是 source of truth。商業方案的事件名稱是自架名稱的映射，不是取代。映射邏輯集中在一個 adapter 層，商業方案更換時只改 adapter。

不要為了配合商業方案改變自架的分類。Sentry 把 event 記錄為 breadcrumb 不代表自架方案也要把 event 降級成 error 的附屬品。自架的四類分類是語意正確的，商業方案的分類是它自己的產品設計。

同時接入多個方案時做去重。Error 同時發到 Sentry 和 Crashlytics 會產生重複。在 adapter 層控制「哪類事件發到哪個方案」，避免同一個事件在多個 dashboard 出現。

下一步路由

• 四類事件的定義 → 四類事件的完整定義
• 商業方案的深入比較 → 模組六 商業方案比較
• 事件命名規範 → 事件命名規範

待寫章節

• SDK 公開 API 設計（init / event / error / metric / flush / close）
• 自動攔截機制（JS window.onerror / Flutter FlutterError / Python sys.excepthook）
• 攢批送出策略（flush interval / buffer size / flush on close）
• 離線 buffer 與重試（FIFO 丟棄 / 本地 persistence / 恢復後補發的取捨）
• SDK redaction helper（模組七的實作層）

跨分類引用

• → testing 模組三 協議整合測試：SDK 的 HTTP POST 行為需要 protocol test
• → monitoring 模組七 資安：redaction 在 SDK 端做
• ← testing 模組一 測試策略：mock 遮蔽機制影響 SDK 的 auto-intercept 行為驗證
• 實作 repo：tarrragon/monitor 的 sdk-js / sdk-flutter / sdk-python

三個觸發條件

時間觸發（flush interval）

固定間隔自動 flush。SDK 在 init 時啟動計時器，每隔 N 毫秒檢查 buffer 是否有待發事件，有則送出。

合理的間隔範圍：10-60 秒。間隔太短（1 秒）接近逐筆送出，失去攢批的效益；間隔太長（5 分鐘）可能讓事件延遲到達 collector，影響即時監控和告警的反應速度。

自用工具場景下 30 秒是合理的預設 — 事件量低，30 秒的延遲對 debug 分析沒有實質影響。商業產品可以降到 10 秒以獲得更接近即時的 error 告警。

數量觸發（buffer size）

Buffer 內的事件數量達到上限時立即 flush。Buffer size 設定為一次 HTTP POST 的合理 payload 大小對應的事件數量。

合理的數量範圍：50-200 筆。數量太少（10 筆）頻繁觸發 flush；數量太多（1000 筆）單次 HTTP POST 的 payload 過大，增加傳輸失敗的風險（超時、記憶體）。

數量觸發和時間觸發互為備援。高頻事件場景（使用者快速操作）靠數量觸發避免 buffer 溢出；低頻事件場景（使用者長時間閒置）靠時間觸發確保事件在合理時間內送出。

關閉觸發（flush on close）

SDK close 時強制 flush buffer 中所有剩餘事件。這是最後一道保障 — app 關閉後 buffer 中未送出的事件就永久遺失了。

close flush 的挑戰是時間限制。iOS app 進入背景後約 5 秒會被系統 suspend，Android 的限制更嚴格。Close flush 必須在這個時間窗口內完成網路請求。如果 buffer 中事件太多導致 flush 超時，需要截斷 — 送出最近的 N 筆，放棄較舊的。

Buffer 管理

記憶體 buffer

Buffer 在記憶體中維護一個事件陣列。新事件 append 到尾端，flush 時取出整個陣列送出並清空。

記憶體 buffer 的上限應該設定為 buffer size 的 2-3 倍（允許 1-2 次 flush 失敗後累積的事件）。超過上限時丟棄最舊的事件（FIFO），保留最新的 — 最新的事件對 debug 和即時分析的價值更高。

離線 buffer

網路不可用時，事件累積在記憶體 buffer 中。如果離線時間超過記憶體 buffer 容量，需要離線 persistence — 見 離線 buffer 與重試。

Flush 失敗處理

HTTP POST 失敗時（網路中斷、server 回 5xx、超時），事件保留在 buffer 中等待下一次 flush 重試。不立即重試 — 連續失敗通常代表網路問題或 server 問題，立即重試只會增加負載。

重試次數有上限（3 次）。超過重試上限的事件被丟棄，記錄一筆 sdk.flush.dropped metric 事件（這筆 metric 本身也進 buffer，在下次成功 flush 時送出）。

SDK 對 collector 回應的處理

SDK 只需要判斷 HTTP status code 就知道怎麼處理 buffer，不需要解析 response body 的細節。

207 和 400 都清 buffer 的關鍵判斷：Schema 驗證失敗是 SDK 端產出了不合規的事件，問題在 SDK 的事件建構邏輯（程式碼 bug），不在 collector 或網路 — 重試相同事件永遠不會過。SDK 把失敗事件的 error 訊息記到 warning/error log 供開發者排查，然後放行後續事件。

503 保留 buffer 的關鍵判斷：collector 暫時不可用是基礎設施問題（SQLite busy timeout、背壓），事件本身合法，等 collector 恢復後重試會成功。retry_after 由 collector 在回應中指定，SDK 用這個值設定下次 flush 的最小等待時間。

Batch 格式

SDK 在 flush 時把 buffer 中所有事件包裝成一個 batch，帶上 batch_id 送出。

1{
2  "batch_id": "019537a0-7b2c-7def-8a2b-3c4d5e6f7890",
3  "events": [ ... ]
4}

batch_id 由 SDK 在 flush 時產生。使用 UUID v7（uuid.uuid7()，Python 3.14+ 標準庫）——時間戳前綴保證有序（debug 時按 batch_id 排序即時間順序），隨機後綴保證唯一（高負載下多個 SDK 同時 flush 不碰撞）。用途是追蹤和 debug（collector log 中標記同一批事件的來源）。Collector 不依賴 batch_id 做去重 — 同一批事件被 SDK 重試時會帶不同的 batch_id（每次 flush 重新產生），collector 按事件內容（timestamp + source + name）判斷是否重複。

UUID v7 而非時間戳格式的選型理由：時間戳格式（b-{YYYYMMDD}-{HHMMSSfff}）在同毫秒多次 flush 時會碰撞，雖然 MVP 的 debug 用途碰撞無害，但 batch_id 碰撞在後續版本的離線補發去重場景（見 離線 buffer 與重試）會造成歧義。UUID v7 兼顧有序和唯一，一次到位。

Heartbeat 和 flush 的整合

DevOps dashboard 需要 sdk.heartbeat 事件判斷 SDK 是否存活。Heartbeat 不需要獨立的 timer — 整合在 flush timer 中：

flush timer 觸發時，如果 buffer 為空且距上次 heartbeat 超過設定間隔（預設 5 分鐘），自動注入一筆 sdk.heartbeat lifecycle 事件後送出。App idle 時仍有心跳但不多一個 timer；app 活躍時 heartbeat 被正常事件的 flush 取代（buffer 不會為空）。

Heartbeat 間隔由 SDK init config 的 heartbeatInterval 設定。設為 0 停用 heartbeat。

下一步路由

• 離線場景的處理 → 離線 buffer 與重試
• SDK 公開 API → SDK 公開 API 設計
• Collector 端如何接收批次事件 → 模組四 Collector 架構

Metric 收集：Prometheus + Grafana

Prometheus 是 pull-based 的 metric 收集系統——它主動去 scrape 各服務的 metric endpoint，不需要服務往外推資料。這個架構天然適合斷網：所有流量都在內網、不需要出站連線。

離線安裝

Prometheus 和 Grafana 都是單一二進位或容器映像，離線安裝跟映像搬運相同的流程：

1# 外部：下載 release binary
2wget https://github.com/prometheus/prometheus/releases/download/v2.53.0/prometheus-2.53.0.linux-amd64.tar.gz
3wget https://dl.grafana.com/oss/release/grafana-11.1.0.linux-amd64.tar.gz
4
5# 搬運後解壓、設定 systemd service
6tar xzf prometheus-2.53.0.linux-amd64.tar.gz
7sudo mv prometheus-2.53.0.linux-amd64 /opt/prometheus

如果用容器部署，先把映像搬進內部 registry 再 pull：

1# 內部：從內部 registry 啟動
2docker run -d -p 9090:9090 \
3  -v /etc/prometheus:/etc/prometheus \
4  -v /data/prometheus:/prometheus \
5  registry.internal:5000/prometheus:v2.53.0

Scrape 設定

Prometheus 的 prometheus.yml 定義要 scrape 的目標。斷網環境通常用 static config（手動列出目標）而非 service discovery（需要雲端 API）：

 1scrape_configs:
 2  - job_name: 'node-exporter'
 3    static_configs:
 4      - targets:
 5          - 'server-01:9100'
 6          - 'server-02:9100'
 7          - 'db-01:9100'
 8
 9  - job_name: 'app'
10    static_configs:
11      - targets:
12          - 'app-01:8080'
13          - 'app-02:8080'
14    metrics_path: '/metrics'

新增機器時手動把它加進 targets 清單。如果用 Consul（內網 service discovery），Prometheus 支援 Consul SD、可以自動發現新服務。

Node Exporter

每台需要監控的 Linux 機器裝一個 node_exporter（單一二進位、無依賴），暴露 CPU、記憶體、磁碟、網路等系統 metric。離線安裝同理——下載 binary、搬運、解壓、設成 service。

1# 搬運後安裝
2tar xzf node_exporter-1.8.1.linux-amd64.tar.gz
3sudo cp node_exporter-1.8.1.linux-amd64/node_exporter /usr/local/bin/
4sudo useradd --no-create-home --shell /bin/false node_exporter
5# 建立 systemd service（略）

Log 收集：Loki 或 ELK

Grafana Loki（輕量）

Loki 是 Grafana 生態的 log 彙整系統，架構類似 Prometheus（pull/push 都支援），但儲存的是 log stream 而非 metric。它不索引 log 內容（只索引 label），所以儲存成本遠低於 Elasticsearch。

 1# loki-config.yaml 基本設定
 2auth_enabled: false
 3server:
 4  http_listen_port: 3100
 5storage_config:
 6  filesystem:
 7    directory: /data/loki/chunks
 8schema_config:
 9  configs:
10    - from: 2024-01-01
11      store: tsdb
12      object_store: filesystem
13      schema: v13
14      index:
15        prefix: index_
16        period: 24h

搭配 Promtail（log 收集 agent）在每台機器上收集 log 並推送到 Loki：

 1# promtail-config.yaml
 2clients:
 3  - url: http://loki.internal:3100/loki/api/v1/push
 4scrape_configs:
 5  - job_name: system
 6    static_configs:
 7      - targets: [localhost]
 8        labels:
 9          job: syslog
10          __path__: /var/log/*.log

ELK Stack（功能豐富）

Elasticsearch + Logstash + Kibana 是功能最完整的 log 平台，但資源消耗大（Elasticsearch 建議至少 4GB RAM 起跳）。適合需要全文搜索 log 內容的場景。

離線安裝：Elastic 提供離線安裝包（.deb / .rpm），或用 Docker 映像。三個組件都要搬運。

選型判準：5 台以下的小環境用 Loki（輕量、跟 Prometheus + Grafana 同一套 dashboard）。需要全文搜索、已有 ELK 經驗的團隊用 ELK。

告警：沒有外部 webhook 怎麼通知

連網環境的告警通常發到 Slack webhook、PagerDuty API、或 email relay service。斷網環境這些路徑都不通。

內部 SMTP

如果隔離網路內有 email server（很多企業內網有 Exchange 或 Postfix），Prometheus Alertmanager 可以發 email 告警：

 1# alertmanager.yml
 2route:
 3  receiver: 'email-team'
 4receivers:
 5  - name: 'email-team'
 6    email_configs:
 7      - to: 'oncall@internal.corp'
 8        from: 'alertmanager@internal.corp'
 9        smarthost: 'smtp.internal.corp:25'
10        require_tls: false

內部即時通訊

如果內網有 Mattermost（Slack 的 self-hosted 替代）或 Rocket.Chat，Alertmanager 可以用 webhook 發送到這些工具的 incoming webhook endpoint。

實體告警

極端情境（沒有 email、沒有 chat）：Alertmanager 把告警寫到檔案或資料庫、搭配值班制度定期查看。或用 Grafana 的 dashboard + 控制室大螢幕，值班人員直接看板。

告警的設計原則跟連網環境相同——symptom-based（錯誤率、延遲）優先於 cause-based（CPU、記憶體），閾值設計避免告警疲勞。差別在通知的到達速度可能慢一些（email 比 Slack push 慢），所以閾值要稍微保守（提早告警）。

Metric 與 Log 的儲存規劃

SaaS 監控的儲存是雲端自動擴展的。Self-hosted 的儲存要自己規劃——磁碟滿了 Prometheus 就停止收集、Loki 就停止寫入。

容量估算

Prometheus 的儲存量取決於 series 數量 × scrape 間隔 × 保留天數。粗估公式：

1每日儲存 ≈ active_series × sample_size(2B) × (86400 / scrape_interval) × compression_ratio(~0.1)

1 萬個 active series、15 秒 scrape interval、保留 30 天 ≈ 約 5GB。保留 90 天 ≈ 約 15GB。

Loki 的儲存量取決於 log 流量。粗估：每天 10GB 的 raw log 在 Loki 壓縮後約 1-2GB，保留 30 天 ≈ 30-60GB。

Retention 設定

1# prometheus.yml
2global:
3  scrape_interval: 15s
4storage:
5  tsdb:
6    retention.time: 30d
7    retention.size: 10GB  # 以先到的為準

超過容量時 Prometheus 自動刪除最舊的資料。設定 retention 前先確認磁碟空間足夠——斷網環境擴容磁碟的流程（採購 + 安裝）可能需要週到月級的時間。

NTP 時間同步

斷網環境容易被忽略的一個問題是時間同步。沒有 NTP server（pool.ntp.org）可連的機器，時鐘會漂移——幾天後各台機器的時間差可能達到秒級。當 Prometheus 收到的 metric timestamp 跟 Loki 收到的 log timestamp 有幾秒落差，事故排查時 metric 跟 log 對不上。

解法是在隔離網路內架一台 NTP server，所有機器從它同步：

1# 內部 NTP server（chrony）
2# /etc/chrony/chrony.conf
3local stratum 10         # 沒有外部來源時、自己當 stratum 10
4allow 10.0.0.0/16        # 允許內部網段同步
5
6# 其他機器指向內部 NTP
7server ntp.internal iburst

如果隔離網路的閘道可以開 NTP（UDP 123），讓閘道從外部 NTP 同步、內部機器從閘道同步，時間精度可以維持在毫秒級。

時程參考：Prometheus + Grafana + Alertmanager 的初次建置約需 1-2 天。Loki + Promtail 約需半天到一天。NTP server 約需 2 小時。後續維護主要是 Prometheus/Loki 版本更新的搬運（每次 1-2 小時）和儲存容量監控。

跨分類引用

• → 斷網環境的通用原則：監控工具的離線安裝走 content ferry 模式
• → 斷網環境的容器管理：Prometheus/Grafana/Loki 的容器映像搬運
• → 模組六：可觀測性與 log：連網環境的可觀測性 IaC
• → 無 SSH 環境的監控與告警：另一個極端——完全外部監控
• → Monitoring 04：Collector 架構與部署：SDK 和 Collector 的應用層監控，斷網環境需要把 Collector endpoint 指向 self-hosted backend
• → Monitoring 06：Self-hosted vs Commercial：斷網環境只能走 self-hosted 路線

歸因模型

Last-touch attribution

把轉換功勞全部歸給使用者轉換前最後接觸的渠道。上例中功勞歸「直接輸入網址」。

優點：實作最簡單 — 只需要記錄轉換事件的 referrer 或 UTM 參數。

缺點：忽略了前面渠道的貢獻。Facebook 廣告讓使用者第一次知道產品，但在 last-touch 模型中功勞為零。長期使用 last-touch 會導致行銷預算過度集中在「最後一步」渠道（品牌搜尋、直接訪問），低估「認知階段」渠道（展示廣告、社群媒體）。

First-touch attribution

把轉換功勞全部歸給使用者第一次接觸的渠道。上例中功勞歸 Facebook 廣告。

優點：強調「獲客」渠道的貢獻，適合評估品牌認知和獲客效率。

缺點：忽略了後續渠道的推進作用。使用者第一次看到廣告但沒行動，可能是後續的 Google 搜尋才促成轉換。

Multi-touch attribution

把轉換功勞分配給使用者轉換路徑上的所有渠道。分配方式有多種：

• 線性歸因：每個渠道平均分配。三個渠道各得 33.3%。
• 時間衰減：離轉換越近的渠道得到越多功勞。
• Position-based（U 型）：第一個和最後一個渠道各得 40%，中間渠道分 20%。
• 資料驅動（data-driven）：用機器學習模型從歷史資料學習每個渠道的貢獻。需要大量資料。

技術實作

Attribution 的技術實作需要解決兩個問題：跨 session 的使用者識別，和觸點的記錄。

跨 session 識別

同一個使用者在不同 session、不同裝置、不同瀏覽器上的行為需要關聯到同一個人。

Web 端用 cookie（first-party）或 login ID 關聯。Mobile 端用 device ID 或 login ID。跨裝置關聯需要使用者登入 — 未登入的使用者在不同裝置上是不同的匿名 ID。

觸點記錄

每次使用者接觸產品的渠道需要記錄。Web 端記錄 referrer、UTM 參數（utm_source、utm_medium、utm_campaign）。Mobile 端記錄 deep link 參數、app store 來源（需要 attribution SDK 如 AppsFlyer、Adjust）。

自架方案的歸因能力

自架 collector 能做基礎的 last-touch attribution — 在轉換事件的屬性中記錄 referrer 和 UTM 參數。

Multi-touch attribution 需要跨 session 的使用者行為歷史，實作複雜度顯著上升。如果 multi-touch 是核心需求，商業方案（GA4、Mixpanel、AppsFlyer）通常比自架更實用。

下一步路由

• A/B test 驗證渠道效果 → A/B test 的統計基礎
• 使用者分群 → Cohort analysis
• 行為事件設計 → 行為事件設計
• 客戶取得成本 → CAC

跟 Backend 04 的分工：本文從 client-side RUM 角度說明 Datadog 的全棧追蹤、四種 RUM 事件與 session replay。Server-side 的 APM 平台治理（agent 配置、成本治理、OTel 相容遷移、從 New Relic 或 Grafana Stack 遷移）見 Backend 04 Datadog vendor page。

Datadog Real User Monitoring（RUM）從全棧 APM 的角度設計 client-side 監控。核心特徵是 client 端的使用者操作可以關聯到 server 端的 trace，形成從按鈕點擊到 database query 的完整請求鏈路。

全棧追蹤

Datadog RUM 的 SDK 在 HTTP 請求中自動注入 trace context header。Server 端的 Datadog APM agent 讀取 header，把 server 端的 trace 和 client 端的 action 關聯。

這個能力在 debug「API 慢」的問題時特別有用 — 從 client 端看到「這個按鈕的回應時間 3 秒」，點進去看到 server 端的 trace 顯示「database query 佔了 2.8 秒」。自架方案和 Sentry 都做不到這個深度的跨層關聯。

前提是 server 端也使用 Datadog APM。如果 server 端用其他 APM（New Relic、Elastic APM），client-server 的關聯需要自行實作或用 OpenTelemetry 橋接。

四種 RUM 事件

Datadog RUM 收集四種事件，和自架方案的四類事件有對應關係（模組一 商業方案對應）：

View：頁面或畫面的載入和離開。自動偵測 SPA 的 route 變換，對應 lifecycle 事件。

Action：使用者操作。自動捕獲 click、tap、scroll，可手動記錄自訂 action，對應 event 事件。

Error：JS exception、network error、自訂 error，對應 error 事件。

Long Task：執行時間超過 50ms 的任務（阻塞主執行緒），對應 metric 事件。

定價

Datadog RUM 按 session 數計費（每個 session 是一次使用者訪問）。和 Sentry 按事件數計費不同 — session 計費讓成本更可預測（不會因為單次訪問觸發大量事件而費用暴增）。

Datadog 的完整方案（RUM + APM + Logs + Infrastructure）費用較高，適合已經用 Datadog 做 server-side 監控的團隊。單獨用 RUM 而 server 端用其他方案，失去全棧追蹤的優勢。

Datadog RUM 的全棧追蹤能力獨一無二，但如果只需要行為分析而非 APM，Mixpanel / Amplitude 是更輕量的選擇。和 Sentry 的定位差異在於 Sentry 聚焦 error tracking、Datadog 聚焦全棧關聯。自架 vs 商業的判斷決策表從使用者規模和功能需求維度做系統性比較。

Graceful shutdown

Go 程式收到 SIGTERM 或 SIGINT 時需要在退出前完成清理：flush 剩餘的 buffer、關閉網路連線、寫入最後的 lifecycle 事件。

1ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGTERM, syscall.SIGINT)
2defer stop()
3
4<-ctx.Done()
5// signal received, start graceful shutdown
6monitor.Close(context.WithTimeout(context.Background(), 5*time.Second))

graceful shutdown 的時間窗口由部署環境決定。Kubernetes 的預設 terminationGracePeriodSeconds 是 30 秒，Docker 的 stop timeout 是 10 秒。SDK 的 Close 方法接受 context 讓呼叫端控制超時。

HTTP server 的 shutdown 順序

如果 Go 程式同時是 HTTP server 和 monitoring SDK 的使用者，shutdown 順序需要正確：

1. 停止接受新連線（server.Shutdown(ctx)）
2. 等待進行中的請求完成
3. flush 監控 buffer（monitor.Close(ctx)）
4. 關閉 log 和其他資源

如果先 close monitor 再 shutdown server，進行中的請求產生的事件會在 monitor 已關閉後嘗試送出，被靜默丟棄。

Signal handling

Go 的 signal.Notify 和 signal.NotifyContext 是接收 OS signal 的標準方式。SDK 在 init 時不應該自己註冊 signal handler — 這會和應用程式的 signal handling 衝突（Go 的 signal handler 是先到先得，後註冊的覆蓋先註冊的）。

SDK 端的適配方式是提供 Close 方法讓應用程式在自己的 signal handler 中呼叫，而非 SDK 內部攔截 signal。應用程式控制 shutdown 流程，SDK 只負責在被告知關閉時 flush 和清理。

panic recovery

Go 的 panic 會終止當前 goroutine。如果 panic 發生在 main goroutine 且沒有 recover，程式直接退出，SDK 的 buffer 中的事件遺失。

SDK 可以提供 monitor.RecoverAndReport() 讓開發者在 goroutine 的入口用 defer monitor.RecoverAndReport() 攔截 panic，記錄 error 事件後再 re-panic（保持原有的 crash 行為）。

HTTP handler 的 panic 可以用 middleware 攔截：

1func monitorMiddleware(next http.Handler) http.Handler {
2    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
3        defer monitor.RecoverAndReport()
4        next.ServeHTTP(w, r)
5    })
6}

HTTP server 自身監控

Go 常用來寫 collector 本身。Collector 需要監控自己的健康狀態 — 請求處理速率、錯誤率、goroutine 數量、記憶體使用量。

Collector 的自身監控和接收外部事件是兩個獨立的管線。自身監控的 metric 可以寫入獨立的 JSONL 檔案（和外部事件分開），或透過 Go 的 expvar / runtime.ReadMemStats 暴露為 HTTP endpoint。

自身監控的關鍵指標：

• collector.events.received：每秒收到的事件數
• collector.events.invalid：schema 驗證失敗的事件數
• collector.storage.write_duration_ms：寫入 JSONL 的耗時
• collector.goroutines：goroutine 數量（洩漏偵測）
• collector.memory.alloc_mb：記憶體使用量

下一步路由

• 跨平台 timestamp 一致性 → 跨平台 timestamp 一致性
• Collector 的架構設計 → 模組四 Collector 設計
• SDK 公開 API 的 Close 方法 → 模組三 SDK 公開 API

概念位置

RFM 位在行為資料累積到一定量之後。它需要每個使用者的 session 歷史（計算 Recency 和 Frequency）和交易歷史（計算 Monetary）。免費產品可以用替代指標取代 Monetary — 產生的內容數量、邀請的使用者數、完成的關鍵操作數。RFM 的前提和 cohort analysis 相同：去識別化（redaction）已完成。

可觀察訊號與例子

產品需要 RFM 的訊號是「需要對不同行為模式的使用者採取不同策略」。高 R 高 F 高 M 的忠實客戶需要維護關係，低 R 高 F 高 M 的潛在流失客戶需要挽留，高 R 低 F 低 M 的新使用者需要引導降低入門門檻。

設計責任

RFM 要定義每個維度的計算方式（Recency 用天數還是週數、Frequency 的時間窗口多長、Monetary 用什麼指標）、分位數（五等分還是三等分）、群組歸納（125 種 profile 歸納成幾個可操作群組）、以及重新計算的頻率（每週還是每月）。分群結果是動態的 — 使用者行為改變時群組會變。

三段式規則結構

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

條件

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

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

IP 截斷

IP 位址是最常見的個人識別欄位。完整的 IPv4 位址（192.168.1.50）可以定位到特定的網路和裝置；截斷後的 IP（192.168.1.0）保留網段資訊但無法定位到特定裝置。

截斷策略

IPv4 末八位清零：192.168.1.50 → 192.168.1.0。保留 /24 網段資訊，足以判斷「使用者在哪個網段」但無法定位到特定裝置。Google Analytics 採用這個策略。

IPv4 末十六位清零：192.168.1.50 → 192.168.0.0。更強的去識別化，但地理定位精度降低到城市級。

IPv6：截斷更多位元。IPv6 的後 80 位通常包含 MAC 位址衍生的 interface ID — 截斷到 /48 前綴保留 ISP 資訊，移除裝置識別。

實作位置

IP 截斷應在 collector 收到事件後、寫入儲存前執行。SDK 端不做 IP 截斷 — SDK 通常不知道自己的外部 IP（知道的是 NAT 後的內部 IP），外部 IP 是 collector 從 HTTP request 的 source IP 取得的。

User Agent 簡化

User agent 字串包含瀏覽器版本、OS 版本、裝置型號 — 組合起來可能形成唯一的 fingerprint。簡化 user agent 保留有用的分類資訊（「iOS 17 上的 Safari」），移除可用於 fingerprinting 的細節（「iPhone 15 Pro Max, Build/22A3354」）。

簡化規則

保留：平台（iOS / Android / Windows / macOS）、主要版本號（iOS 17、Android 14）、瀏覽器類型（Safari / Chrome / Firefox）。

移除：minor version、build number、裝置型號、CPU 架構、語言設定。

1原始：Mozilla/5.0 (iPhone; CPU iPhone OS 17_4_1 like Mac OS X)
2簡化：iOS/17 Safari

Stack Trace 路徑清理

Error 事件的 stack trace 包含檔案路徑。檔案路徑可能洩漏部署結構（/home/deploy_user/app/v2.3.1/src/...）或開發者的個人資訊（/Users/alice/projects/...）。

清理規則

移除使用者目錄前綴：/Users/alice/projects/app/src/main.dart:42 → src/main.dart:42。保留 source file 相對路徑和行號，移除使用者名稱。

移除部署路徑前綴：/opt/deploy/releases/20260619/app/lib/... → lib/...。保留程式碼結構，移除部署細節。

統一 path separator：Windows 路徑（C:\Users\...）和 Unix 路徑（/home/...）統一處理。

清理規則用正則表達式匹配常見的路徑前綴模式，替換為空字串。自訂的部署路徑格式需要在 collector 設定中額外註冊。

Session UUID

Session ID 用於關聯同一次使用中的多個事件。UUID v4（隨機產生）作為 session ID，沒有可預測性、沒有順序性、無法回推使用者身份。

Session ID 的生命週期

SDK 在初始化時產生一個 UUID v4 作為 session ID，所有事件附帶這個 ID。App 重新啟動時產生新的 session ID — 前後兩次使用的事件無法關聯。

這個設計讓分析粒度限制在「一次使用」而非「一個使用者」。如果需要跨 session 關聯（例如計算 DAU），需要另一個 persistent ID — 但 persistent ID 本身就是可識別資訊，需要使用者同意。

避免使用可識別的 ID

裝置 ID（IDFA / GAID）、安裝 ID、使用者帳號 — 這些可以關聯到特定個人，不適合作為監控系統的 session ID。使用 UUID v4 確保 session ID 的唯一性來自隨機性而非身份。

去識別化是資料保護的一環，另一環是在資料離開 client 之前就處理 — SDK Redaction API 設計從 SDK 端攔截敏感欄位。法規層面的具體要求見 GDPR 最小化原則的工程落地。去識別化完成後的資料才能用於行為分析 — 這是商業利用的入場條件。

四個需求方向

Debug 需求：問題發生時能定位根因

Debug 需求驅動的事件收集目標是「問題發生時，開發者能從事件記錄中重建問題的 context」。

需要的事件類型：

• Error：例外、非預期狀態、API 錯誤回應。包含 stack trace、error code、觸發條件。
• Lifecycle：問題發生時的系統狀態 — app 版本、OS 版本、網路狀態、前景/背景。
• Event（最近操作）：問題發生前使用者做了哪些操作。不需要完整的操作歷史，最近 10-20 個操作通常足夠。

推導方法：列出最近三個月遇到的 debug 困難場景，問「如果當時有哪些事件記錄，debug 時間能從 30 分鐘降到 5 分鐘？」。答案就是 debug 需求驅動的事件清單。

app_tunnel（透過 WebSocket 連接遠端終端機的 Flutter app）的 T.C4 案例是典型的 debug 需求缺口 — 六個元件中四個零 log，debug 只能靠實機反覆測試。如果在企劃階段就設計了連線生命週期的五步 log，auth token 問題在第一次連線就能從 log 定位（testing 模組二）。

具體的事件表和查詢場景見 動機驅動的事件設計。

行為分析需求：使用者如何使用產品

行為分析需求驅動的事件收集目標是「回答產品決策的問題」。

需要的事件類型：

• Event：使用者操作的完整記錄。需要足夠的粒度來回答「使用者在哪一步流失」（funnel）和「不同使用者群體的行為差異」（cohort）。
• Lifecycle：session 的開始和結束，用於計算使用時長和 session 頻率。

推導方法：列出產品團隊最常問的 3-5 個問題（「新功能有多少人用」「註冊流程在哪一步流失最多」「付費使用者和免費使用者的行為差異」），為每個問題列出需要的事件。

自用工具通常沒有行為分析需求 — 使用者就是開發者本人。這個方向的事件可以跳過。

具體的事件表和查詢場景見 動機驅動的事件設計。

效能需求：系統是否在可接受的範圍內運作

效能需求驅動的事件收集目標是「發現效能退化和容量瓶頸」。

需要的事件類型：

• Metric：回應時間、frame rate、記憶體使用量、佇列長度。定期取樣或事件觸發。

推導方法：列出使用者會感知到的效能指標（頁面載入時間、動畫流暢度、操作回應延遲），為每個指標定義可接受的範圍和取樣頻率。

具體的事件表和查詢場景見 動機驅動的事件設計。

合規需求：法規要求收集或禁止收集什麼

合規需求同時驅動「必須收集」和「禁止收集」。

必須收集：access log（誰在什麼時間存取了什麼資料）、audit trail（誰修改了什麼設定）。

禁止收集：未經同意的個人識別資訊、兒童資料（COPPA）、健康資料（HIPAA）。

推導方法：確認適用的法規（GDPR、CCPA、個資法），列出法規要求的最小收集項目和禁止項目。

具體的事件表和查詢場景見 動機驅動的事件設計。

從需求到事件清單的步驟

1. 列出需求方向：Debug / 行為分析 / 效能 / 合規，每個方向的消費者是誰（開發者 / 產品團隊 / 維運 / 法務）。
2. 每個方向列出問題：消費者最常需要回答的 3-5 個問題。
3. 每個問題列出需要的事件：回答這個問題需要哪些事件類型和哪些屬性。
4. 去重和分類：不同方向可能需要同一個事件（error 事件同時服務 debug 和效能監控）。去重後按四類事件分類。
5. 排優先順序：按「缺少這個事件的損失」排序。Debug 需求的 error 事件通常是最高優先。

下一步路由

• 四類事件的定義 → 四類事件的完整定義
• 事件的命名和結構化 → 事件命名規範
• 收集到的事件怎麼處理 → 模組四 Collector 設計
• 四個方向展開到具體事件名稱級 → 動機驅動的事件設計

設計目標差異

OTLP

OTLP 的設計目標是「跨語言、跨框架、跨 vendor 的統一可觀測性標準」。它支援分散式追蹤（trace context propagation）、多維度 metric（histogram、summary、exponential histogram）、結構化 log。

OTLP 的資料模型假設 server-side 的基礎設施：collector（如 OTel Collector）做資料路由和轉換，backend（如 Jaeger、Prometheus、Grafana）做儲存和視覺化。

自架 event schema

自架 schema 的設計目標是「client-side 監控的最小可用結構」。它假設的基礎設施是一個 HTTP endpoint + JSONL 檔案 + grep。不需要分散式追蹤（client 端通常是單一服務），不需要多維度 metric（counter 和 gauge 用 event 的 data 欄位表示即可）。

具體差異

自架 schema 簡化了什麼

不做分散式追蹤

OTLP 的 trace signal 用 TraceID 和 SpanID 把跨服務的請求關聯起來。Client-side 監控通常不需要這個能力 — app 是單一服務，不存在跨服務的請求鏈路。

自架 schema 用 session ID 關聯同一次使用中的事件，滿足「使用者在這次操作中做了什麼」的分析需求。

不用 Protobuf

OTLP 用 Protobuf 編碼資料，效率高（binary 格式、schema 驗證在編譯期）。但 Protobuf 需要 schema 檔案（.proto）、程式碼生成、和 SDK 語言的 Protobuf 套件。

自架 schema 用 JSON，人類可讀、grep 友好、不需要額外工具。JSON 的效率比 Protobuf 低（文字格式、體積較大），但在 client-side 監控的事件量下（每分鐘數十到數百筆），效率差異不構成瓶頸。

簡化 metric 模型

OTLP 的 metric signal 支援 histogram（分桶分佈）、summary（百分位）、exponential histogram（自適應分桶）。這些模型在 server-side 的高頻度 metric 收集中有意義。

自架 schema 把 metric 記錄為 event 的 data 欄位中的數值（{"type": "metric", "name": "connect.duration", "data": {"value_ms": 320}}）。統計分析在 collector 端用查詢完成，不在 schema 層做聚合。

什麼時候切換到 OTLP

以下訊號出現時，自架 schema 的簡化可能成為限制：

需要和 server-side 追蹤關聯：Client 端的操作要關聯到 server 端的 trace（「使用者點擊按鈕到 database query 的完整路徑」）。需要 OTLP 的 trace context propagation。

事件量超過 JSONL 的處理能力：每秒數千筆事件時，JSON 的解析和 JSONL 的 grep 查詢成為瓶頸。OTLP + OTel Collector + 時間序列 DB 的管線能處理更高的吞吐量。

需要接入多個 backend：同時送資料到 Prometheus（metric）、Jaeger（trace）、Elasticsearch（log）。OTel Collector 原生支援多 backend 路由，自架方案需要自己實作。

切換策略：SDK 層的 API 不變（init / event / error / metric），只改底層的傳輸和編碼。從 JSON POST 改成 OTLP export，SDK 的使用者不需要改程式碼。

下一步路由

• 自架 schema 的完整定義 → event.schema.json 完整欄位解說
• Server-side 的可觀測性 → backend 04 可觀測性
• Collector 的設計 → 模組四 Collector 設計

待寫章節

• 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/（撞牆記錄）

三種策略

FIFO 丟棄（最簡單）

Buffer 滿時丟棄最舊的事件，保留最新的。整個 buffer 在記憶體中，不做本地 persistence。

優點：實作最簡單（array + 容量檢查），不需要檔案系統存取，不增加磁碟 I/O。

代價：離線超過 buffer 容量時，較舊的事件永久遺失。如果離線 30 分鐘、buffer 容量 200 筆、事件產生速率每分鐘 10 筆，前 100 筆（前 10 分鐘）的事件被丟棄。

適合場景：自用工具（離線場景少、遺失部分事件影響低）、SDK 初期版本（先用最簡單的策略上線）。

本地 persistence（最完整）

Buffer 滿時把事件寫入本地檔案（SQLite、JSONL 檔案、SharedPreferences / UserDefaults）。網路恢復後從本地檔案讀取並補發。

優點：離線期間的事件不會遺失（在本地儲存容量內）。

代價：實作複雜度高 — 需要處理檔案讀寫、並發存取（多執行緒安全）、本地儲存容量管理（磁碟空間上限）、補發時的去重（同一筆事件可能已在記憶體 buffer 中被 flush 過）。

適合場景：商業產品（使用者在地鐵、電梯、飛航模式下使用）、離線時間長且事件不可遺失的需求。

混合策略

記憶體 buffer 處理正常情況和短暫離線。離線超過記憶體 buffer 容量時，溢出的事件寫入本地檔案。網路恢復後先 flush 記憶體 buffer（最新事件），再補發本地檔案中的事件（較舊事件）。

混合策略的實作複雜度介於兩者之間。本地檔案只在溢出時使用，正常情況下不產生磁碟 I/O。

恢復後補發

網路恢復後補發離線期間累積的事件，需要處理三個問題：

補發順序

離線事件按 timestamp 順序補發，保持事件的時間順序。Collector 端收到的事件 timestamp 可能比當前時間早數小時 — 這是正常的離線補發，collector 應該根據事件的 timestamp 處理，不依賴收到時間。

補發速率

一次送出大量離線事件可能讓 collector 過載。分批補發（每批 50-100 筆，間隔 1-2 秒），讓 collector 有時間處理。

去重

同一筆事件可能同時存在於記憶體 buffer 和本地檔案中（寫入本地檔案時 buffer 中也有一份）。Collector 端用事件的唯一識別（timestamp + session_id + name 的組合，或 SDK 產生的 event_id UUID）做去重。

本地儲存容量管理

本地 persistence 需要設定磁碟使用上限。上限取決於事件大小和保留時間。

以平均每筆事件 500 bytes 估算：

自用工具 1 MB 足夠（離線場景少）。行動 app 10-50 MB 合理（使用者可能整天離線）。超過上限時用 FIFO 丟棄最舊的本地檔案。

各平台的本地儲存路徑

本地 persistence 的檔案路徑和格式因平台而異。MVP 階段全用記憶體 FIFO（最簡單策略），本地 persistence 標為第二階段。

App 被強制終止時（iOS 的 kill、Android 的 process death），記憶體 buffer 中未 flush 的事件會遺失。Flutter 的 AppLifecycleState.detached 不保證有時間執行 flush。接受這個遺失 — 強制終止是極端情境，下次啟動時 SDK 重新開始收集。

下一步路由

• 攢批送出策略 → 攢批送出策略
• SDK 端的資料脫敏 → SDK redaction helper
• Collector 端如何處理補發事件 → 模組四 Collector 設計
• 從 SDK 到 storage 的端到端資料損失地圖 → 端到端資料完整性

理解這個框架後，監控就不是「裝一套很重的東西」，而是分層選擇：從 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）→ 程序、服務與狀態怎麼判。
• 機器完全不回應、心跳斷掉之後從外面怎麼查 → 機器連不到或起不來。
• 底層那套「讀權威狀態、不靠肉眼猜」的判讀紀律 → 診斷心法。

概念位置

Error fingerprint 位在 collector 收到 error 事件之後、寫入 storage 之前。它的輸入是通過 schema validation 的 error 事件，輸出是附加了 _fingerprint 欄位的事件和更新後的 error_groups 摘要表。Fingerprint 只作用於 type: "error" 的事件 — 其他三類事件（event / metric / lifecycle）不需要去重分群。

可觀察訊號與例子

需要 fingerprint 的訊號是「dashboard 的 error 列表中，同一個 bug 因為 error message 包含動態值（user ID、timestamp、IP）而分裂成多個不同的行」。例如 "User 12345 not found" 和 "User 67890 not found" 是同一個 bug，但 name-based grouping（GROUP BY name）把它們歸為同一行時，丟失了 message 中的動態值資訊；而沒有 normalization 的 message-based grouping 會把它們分裂成兩行。

設計責任

Fingerprint 承擔的設計責任是「在 error 的精確識別和分群粒度之間找到平衡」。過粗的 fingerprint（只用 error type）把不同 bug 混在同一組；過細的 fingerprint（用完整 message 含動態值）把同因 error 分裂成多組。

自架 vs 商業方案

自架方案用規則做 fingerprint — regex normalize message（替換數字 / UUID / email / IP 等動態值）+ stack trace top N frames 做 hash。Sentry 在規則之上加了 in-app frame 過濾（忽略 framework / library frame）、source map 反解（minified JS → 原始碼位置）、和 ML-based grouping（語意相同但結構不同的 error 歸組）。差距主要在 minified / obfuscated 環境和 ML — 明文 stack trace 的場景下兩者效果相當。

完整章節

Fingerprint 演算法（基礎 / 進階 / Sentry / 自定義）、message normalization 的替換規則和風險、error_groups 表的 DDL 和 UPSERT 流程、dashboard 整合、自架方案的務實邊界 → Error Fingerprint 與去重分群。

從操作盤點推導事件

每個使用者操作（BDD 操作盤點的產物）至少對應一個 event 類型的事件。操作的失敗路徑對應 error 類型。操作涉及的效能測量對應 metric 類型。操作觸發的系統狀態轉換對應 lifecycle 類型。

推導鏈：操作 → 四類事件候選 → 命名 → data schema。

以一個透過 WebSocket 連接遠端終端機的 app 為例，「連線到終端機」這個操作推導出的事件：

一個操作推導出六個事件 — 因為這個操作跨越了使用者行為（event）、可能失敗（error）、有效能測量（metric）、涉及系統狀態轉換（lifecycle）四個面向。其中 connect.done 和 connect.duration 記錄的是同一事實的兩個面向（見下方邊界案例段），自用場景合併成 connect.done 帶 duration_ms 欄位更簡潔。

四類補齊檢查

列完所有操作的事件後，對每個功能區域跑一次四類補齊檢查 — 逐列確認每一類是否都有對應的事件。

空格是候選遺漏。每個空格問一個問題：

• event 空：「這個功能區域有使用者操作嗎？」有 → 補事件；沒有（純系統內部）→ 合理的空格
• error 空：「這個功能區域能失敗嗎？」能 → 補事件；不能失敗的功能極少 → 再想一次
• metric 空：「這個功能區域有值得量測的效能指標嗎？」有 → 補事件；操作瞬間完成且不涉及外部依賴 → 合理的空格
• lifecycle 空：「這個功能區域涉及系統狀態轉換嗎？」有 → 補事件；純資料操作不改系統狀態 → 合理的空格

上表中「輸入」的 metric 和 lifecycle 空格是合理的 — 文字輸入送出不涉及效能量測和系統狀態轉換。「配對」的 lifecycle 空格也合理 — 配對完成後不改變系統的執行狀態。

粒度判準

事件粒度的判斷用一個 SRP 判準：一個事件記一個事實。

拆分訊號

一個事件記了兩個獨立的事實 → 拆成兩個事件。

terminal.connect_and_auth 同時記錄「連線建立」和「認證通過」。這兩個事實的失敗模式不同（連線失敗是網路問題、認證失敗是帳密問題）、觸發時機不同、消費者不同。拆成 terminal.connect.done 和 auth.token.sent。

合併訊號

兩個事件永遠同時觸發且消費者相同 → 合併成一個事件。

terminal.input.keystroke 和 terminal.input.keystroke_logged 永遠同時觸發（每個按鍵一次），data schema 相同。合併成一個 terminal.input.keystroke。

邊界案例

connect.done 同時記 event 和 metric（成功事件 + duration）。這是一個事實（連線完成）的兩個面向，可以合併成一個事件帶 duration_ms 欄位，也可以拆成 event 和 metric 兩筆。判斷依據是查詢需求 — 如果 funnel 分析和效能分析會分開查，拆開讓各自的查詢更簡單；如果都在同一個 dashboard 看，合併減少事件量。

data schema 設計

每個事件的 data 欄位回答「發生了什麼的 context」。設計原則：

帶足 debug context：error 事件的 data 至少包含 error message、發生的步驟、當時的關鍵狀態值。看到這筆 error 事件時、開發者不需要再去查其他來源就能判斷問題方向。

避免過度收集：data 只帶回答具體問題需要的欄位。terminal.connect.start 帶 URL 和觸發方式就夠了；不需要帶使用者的全部設定。

敏感欄位標記 redaction：URL 可能含 IP、error message 可能含路徑中的使用者名稱。在事件設計階段標記需要 redaction 的欄位，SDK 實作時自動處理。

事件表的產出格式

完整的事件表每列七欄：

保留層級欄對應分層保留策略 — 哪些事件需要保留原始逐筆資料（debug 用）、哪些只需要聚合摘要（趨勢用）。

事件表是 SDK 埋點的 spec — 開發者照表實作，code review 時逐行勾選。和功能規格中的 log 點定義互補 — log 點是開發期的 debug 設計，事件表是監控期的收集設計。

下一步路由

• 四類事件的定義 → 四類事件的完整定義
• 事件命名規範 → 事件命名規範
• 行為事件的 funnel 設計 → 行為事件設計
• 事件 schema 的欄位定義 → event.schema.json 完整欄位解說
• 動機驅動的具體事件對應 → 動機驅動的事件設計

假設檢定

虛無假設和對立假設

虛無假設（H0）：兩組沒有差異，觀察到的差異來自隨機波動。對立假設（H1）：兩組有真實差異。

A/B test 的邏輯是：假設 H0 成立（兩組沒有差異），計算「在 H0 成立的前提下，觀察到目前這麼大的差異的機率」。如果這個機率（p-value）很小（通常 < 0.05），拒絕 H0，接受 H1。

p-value 的意義

p-value = 0.03 代表「假設兩組沒有差異，觀察到目前差異的機率是 3%」。這個機率足夠小，合理推斷差異是真實的。

p-value 不代表「改版比原版好的機率是 97%」。p-value 是在 H0 成立的條件下計算的，不是改版效果的機率。

兩類錯誤

Type I error（偽陽性）：實際上沒有差異，但統計結果判定有差異。機率由顯著性水準 α 控制，通常設 0.05。

Type II error（偽陰性）：實際上有差異，但統計結果判定沒有差異。機率由統計檢定力（power = 1 - β）控制，通常要求 power ≥ 0.8。

樣本量計算

樣本量決定了 A/B test 能偵測到多小的差異。樣本量太小，即使改版有效果，test 也沒有足夠的統計檢定力偵測到。

樣本量計算需要四個參數：

• 基準轉換率：control 組目前的轉換率（例如 5%）
• 最小可偵測效果（MDE）：想偵測到的最小差異（例如 5% → 6%，相對提升 20%）
• 顯著性水準 α：通常 0.05
• 統計檢定力 1 - β：通常 0.8

以基準轉換率 5%、MDE 相對提升 20%（5% → 6%）、α = 0.05、power = 0.8 為例，每組需要約 14,500 個樣本。如果每天有 1,000 個使用者，需要跑 29 天。

樣本量不足時的常見錯誤是「提早看結果」— 跑了 3 天看到 p < 0.05 就停止。提早停止會膨脹 Type I error 率，因為隨機波動在小樣本中更容易產生看似顯著的差異。

多重比較

同時跑多個 A/B test 或測試多個變體（A/B/C/D）時，整體的 Type I error 率會膨脹。

跑 20 個 test，即使所有 test 的 H0 都成立（沒有真實差異），預期有 1 個 test（20 × 0.05）會出現 p < 0.05 的偽陽性。

Bonferroni 校正

最簡單的校正方式：把顯著性水準除以測試數量。跑 5 個 test，每個 test 的顯著性水準改為 0.05 / 5 = 0.01。

Bonferroni 校正很保守 — 降低了偽陽性但也降低了統計檢定力，可能錯過真實的差異。

False Discovery Rate（FDR）

Benjamini-Hochberg 方法控制的是「被判為顯著的結果中偽陽性的比例」，比 Bonferroni 更寬鬆。適合探索性分析（同時測試多個指標，容許一些偽陽性）。

A/B test 在自架方案的可行性

自架 collector 可以做基礎的 A/B test 分析 — 在行為事件中記錄使用者的分組（variant: "control" / variant: "treatment"），計算每組的轉換率，用統計檢定比較差異。

統計計算（p-value、信賴區間）可以用 Python（scipy.stats）或 R 完成。不需要商業 A/B test 平台。

商業 A/B test 平台（Optimizely、LaunchDarkly、Firebase Remote Config）額外提供的是：隨機分組管理、提早停止的統計保護（sequential testing）、多變體管理的 UI、和其他分析工具的整合。

下一步路由

• 推薦系統概論 → 推薦系統概論
• 使用者分群 → RFM 分群
• 行為事件設計 → 行為事件設計

資料最小化：只收集需要的欄位

資料最小化的工程落地是「每個收集的欄位都要能回答：這個欄位用來做什麼決策？」。如果一個欄位只是「可能有用」但沒有明確的消費場景，就不應該收集。

正面表列 vs 負面排除

正面表列（allowlist）是列出「收集哪些欄位」— 只收集清單上的欄位，其他全部不收。

負面排除（denylist）是列出「不收集哪些欄位」— 預設收集所有欄位，排除清單上的。

GDPR 的精神更接近正面表列 — 每個收集行為需要有正當理由（lawful basis）。工程上的實作方式是：事件 schema 定義哪些欄位是允許的，不在 schema 中的欄位在 collector 端丟棄。

SDK 端的最小化

SDK 端的最小化更主動 — 在事件產生時就只包含必要的欄位，而非送到 collector 再過濾。

設計 SDK 的 event API 時，不提供「送任意 key-value」的 free-form API，而是提供結構化的 API：

1// free-form（難以控制收集了什麼）
2monitor.event('login', data: {'email': email, 'ip': ip, 'device': device, ...})
3
4// 結構化（schema 控制收集範圍）
5monitor.event('login', loginMethod: 'biometric', success: true)

結構化 API 的參數在 SDK 設計時就決定了收集範圍，code review 時可以檢查「為什麼這個 event 需要這個參數」。

目的限制：收集的資料只用於聲明的目的

目的限制要求資料只用於收集時聲明的目的。監控系統收集事件的目的通常是 debug 和效能監控 — 如果之後要用同一份資料做行為分析或廣告投放，需要額外的法律基礎（通常是使用者同意）。

工程落地

目的限制在工程上的實作是「不同目的的資料分開儲存、分開授權」。

Debug 用的 error 事件和行為分析用的 event 事件存在不同的儲存位置（不同的 JSONL 檔案或不同的資料庫 table）。Debug 用途的 access 不需要使用者同意（legitimate interest）；行為分析用途的 access 需要使用者同意。

分開儲存讓「使用者撤回行為分析同意」的工程操作變簡單 — 刪除行為分析的儲存，不影響 debug 儲存。

儲存限制：不保留超過必要期間的資料

儲存限制要求資料只保留達成目的所需的最短期間。監控資料的合理保留期間依用途不同：

自動清理

Collector 的儲存清理應該自動化 — 手動清理依賴人記得執行，最終會被遺忘。

JSONL 儲存用「一天一檔」的命名（events-2026-06-19.jsonl），清理腳本每天刪除超過保留期限的檔案。Cron job 或 systemd timer 定期執行。

下一步路由

• 去識別化技術 → 去識別化策略
• 監控資料洩漏的威脅分析 → 監控資料洩漏的 threat model
• Collector 的儲存設計 → 模組四 Collector 設計

行為分析 vs 通用監控

通用監控方案（Sentry、Crashlytics、Datadog）的主要產出是 error 報告和 performance 數據 — 工程團隊用來修復 bug 和優化效能。

行為分析方案的主要產出是 funnel 和 cohort 數據 — 產品團隊用來決定功能優先順序、評估改版效果、優化使用者體驗。

兩類需求可以共存。工程團隊需要 error tracking，產品團隊需要行為分析。一些團隊同時使用 Sentry + Mixpanel，各自服務不同的消費者。

核心功能

Funnel analysis

定義使用者操作的步驟序列，計算每步的轉換率和流失率。Mixpanel 和 Amplitude 的 funnel 分析支援：步驟之間的時間窗口限制（步驟 1 到步驟 2 在 24 小時內完成才算轉換）、按使用者屬性分群（新使用者 vs 老使用者的轉換率差異）、步驟之間的路徑分析（流失的使用者去了哪裡）。

自架方案能做基礎的 funnel 計數（模組八 自架 funnel），但不支援時間窗口、分群和路徑分析。

Cohort analysis

按使用者屬性或行為把使用者分成群組，比較不同群組的行為差異。例：「從 Google 廣告來的使用者」vs「從社群分享來的使用者」，兩組的留存率和付費率差異。

Retention analysis

追蹤使用者在初次使用後的回訪率。Day 1 / Day 7 / Day 30 retention — 多少使用者在首次使用後 1 天 / 7 天 / 30 天內回來。

Retention 是產品健康度的核心指標。行為分析方案提供 retention curve（留存曲線）和 retention by cohort（不同群組的留存差異），這些在自架方案中需要大量的 SQL 查詢和手動計算。

Mixpanel vs Amplitude 的差異

兩者的功能高度重疊，差異主要在定價和資料模型：

選擇依據通常是團隊的既有工具鏈和定價模型偏好。

什麼時候需要行為分析方案

行為分析方案的投資在以下條件下有回報：

有產品團隊消費數據：如果只有工程團隊，error tracking + 自架 log 通常足夠。行為分析方案的 dashboard 需要產品團隊定期查看和基於數據做決策。

使用者數量足夠產生統計意義：Funnel 和 cohort 分析需要足夠的樣本量。DAU < 100 的產品，分析結果的統計信度低。

有明確的優化目標：「提高註冊轉換率」「降低 Day 7 流失率」— 有具體的 metric 目標，行為分析方案能提供追蹤和歸因。

自用工具場景下不需要行為分析方案 — 使用者就是開發者本人，行為數據沒有分析價值。

下一步路由

• 自架 vs 商業的判斷 → 自架 vs 商業的判斷決策表
• 行為分析的方法論 → 模組八 行為資料的商業利用
• 四類事件在商業方案中的對應 → 模組一 商業方案事件類型對應

預設 redaction rule

SDK 內建一組預設 rule，處理常見的敏感資訊 pattern：

密碼欄位

匹配 data 物件中 key 包含 password、passwd、secret、token、api_key、apiKey、authorization 的欄位。匹配方式是 key 名稱的子字串比對（case-insensitive）。

URL 中的認證資訊

匹配 https://user:password@host 格式的 URL，把 user:password 部分替換為 [REDACTED]。

Stack trace 中的檔案路徑

匹配 stack trace 字串中的使用者目錄路徑（/Users/username/、/home/username/、C:\Users\username\），替換為 [USER_HOME]/。避免使用者名稱從 stack trace 洩漏。

自訂 redaction rule

業務特定的敏感資訊（信用卡號、身分證字號、醫療資料）不在預設 rule 的範圍內。SDK 提供 API 讓開發者在 init 時註冊自訂 rule。

1Monitor.init({
2  redactionRules: [
3    { pattern: /\b\d{4}[-\s]?\d{4}[-\s]?\d{4}[-\s]?\d{4}\b/, replace: '[CARD]' },
4    { keyPattern: /^ssn$/i, replace: '[REDACTED]' },
5  ],
6})

自訂 rule 和預設 rule 一起執行。如果同一個值被多個 rule 匹配，第一個匹配的 rule 生效（rule 的執行順序：預設 rule 先，自訂 rule 後）。

Redaction 的執行時機

Redaction 在事件進入 flush payload 的那一刻執行 — buffer 中的事件保持原始內容，flush 時複製一份並在複製上執行 redaction。

在 buffer 中保持原始內容的理由是 debug：開發者在本地 console 看到的 log 應該包含完整資訊（開發環境不需要脫敏），只有離開 SDK 時才脫敏。SDK 可以提供 debugMode flag — debugMode 開啟時 console log 印出原始內容，HTTP POST 仍送出脫敏後的內容。

Redaction 和模組七的關係

SDK redaction helper 是模組七 資安與隱私中 redaction 策略的實作層。模組七定義「什麼資訊需要被保護」（策略），本章定義「SDK 如何在程式碼中實現這個保護」（實作）。

兩者的分工：

Collector 端可以做第二道檢查（re-scan 收到的事件是否仍包含敏感 pattern），作為 SDK 端 redaction 的備援。但主要的脫敏責任在 SDK 端 — 資料離開 SDK 後經過網路，已經暴露在傳輸風險中。

下一步路由

• SDK 公開 API → SDK 公開 API 設計
• 資安與隱私的完整策略 → 模組七 資安與隱私
• 自動攔截的 error 也需要 redaction → 自動攔截機制

 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 與去重分群

統一格式：ISO 8601 + 時區偏移

所有平台的 SDK 統一使用 ISO 8601 格式，包含毫秒精度和時區偏移：

12026-06-19T14:30:00.123+08:00

避免使用 Unix timestamp（秒或毫秒）作為僅有的時間表示 — Unix timestamp 沒有時區資訊，如果 SDK 端和 collector 端在不同時區，需要額外的 metadata 才能正確轉換。

避免使用「本地時間不帶時區」的格式（2026-06-19T14:30:00）— 無法區分 UTC+8 的 14:30 和 UTC+0 的 14:30。

各平台的 timestamp 來源

JavaScript

Date.now() 回傳毫秒精度的 Unix timestamp。new Date().toISOString() 回傳 UTC 時間的 ISO 8601 字串。

SDK 應該用 Intl.DateTimeFormat 或手動計算時區偏移，產生帶本地時區的 ISO 8601 字串 — collector 端需要知道事件的本地時間，以便做使用者時區的分析。

performance.now() 提供微秒精度的高解析度時間，但起點是頁面載入時間，無法用來產生絕對 timestamp。用於計算 duration（兩個時間點的差值），不用於記錄事件時間。

Flutter / Dart

DateTime.now() 回傳本地時間的 DateTime 物件。DateTime.now().toUtc() 轉成 UTC。DateTime.now().toIso8601String() 產生 ISO 8601 字串，但不包含時區偏移（Dart 的 ISO 8601 格式不包含 offset）。

SDK 需要手動附加時區偏移：DateTime.now().timeZoneOffset 取得偏移量，手動格式化為 +08:00 格式附加到 ISO 8601 字串後面。

Python

datetime.now(timezone.utc) 取得 UTC 時間。datetime.now().astimezone() 取得本地時間帶時區。.isoformat() 產生帶時區偏移的 ISO 8601 字串。

Python 3.2+ 的 datetime 原生支援 timezone-aware 的 ISO 8601 輸出，是各平台中最完整的。

Go

time.Now() 回傳帶時區的 Time 值。time.Now().Format(time.RFC3339Milli) 產生帶毫秒和時區偏移的字串。

Go 的 time.RFC3339Nano 提供奈秒精度，但監控事件不需要這個精度 — 毫秒足夠。

Clock drift

不同裝置的系統時鐘可能有偏差（clock drift）。使用者手機的時鐘比 collector server 快 5 分鐘，SDK 產生的 timestamp 會比 collector 收到時間早 5 分鐘。

Clock drift 的影響：

• 排序錯亂：裝置 A（時鐘快）和裝置 B（時鐘慢）的事件混合排序時，時間順序可能和真實發生順序不一致
• 告警延遲計算錯誤：collector 用「事件 timestamp 到收到時間的差值」計算延遲，clock drift 讓延遲值不準確

處理策略：

Collector 記錄 receive_timestamp：每筆事件除了 SDK 端的 timestamp，collector 在收到時附加 receive_timestamp。兩者的差值用於估算 clock drift 和網路延遲。

容忍而非修正：在數秒到數分鐘級的 drift 範圍內，容忍 drift 帶來的排序不精確。跨裝置的事件排序本身就不需要毫秒精度 — 分析的粒度通常是秒或分鐘。

異常值偵測：timestamp 比 receive_timestamp 早超過 1 小時，或晚超過 5 分鐘，標記為可疑的 clock drift — 可能是使用者手動調整了系統時鐘。

下一步路由

• JS 平台適配 → JS/TS 平台適配
• Flutter 平台適配 → Flutter 平台適配
• Log schema 中的 timestamp 欄位 → 模組二 event.schema.json 欄位解說
• 各平台的 error 攔截差異影響 test 設計 → testing 模組五 測試設計判斷

待寫章節

• JS/TS 平台：CORS 限制、Service Worker 攔截、SPA 路由變換偵測
• Flutter 平台：isolate 安全、Platform channel 攔截、app lifecycle
• Python 平台：GIL 與 threading、atexit 可靠性、subprocess 監控
• Go 平台：graceful shutdown、signal handling、HTTP server 自身監控
• 跨平台 timestamp 一致性（時區、精度、clock drift）

跨分類引用

• → testing 模組五 測試設計判斷：各平台 error 攔截差異影響 test 設計

概念位置

背壓位在 SDK 和 collector 之間的 HTTP 通訊層。觸發順序：collector 的寫入 channel 容量耗盡 → HTTP handler 無法送入事件 → 回 429 → SDK 收到 429 → SDK 降低取樣率（從 1.0 → 0.5 → 0.1）。背壓是全域的容量訊號 — 所有 SDK 同時收到，所有 SDK 同時降速。

可觀察訊號與例子

需要關注背壓的訊號是 collector 端的 collector.events.backpressure 計數器持續上升、或 SDK 端的 sdk.sampling.rate 低於 1.0。典型場景：行銷活動導致同時在線使用者暴增 → 所有 SDK 同時 flush → collector channel 瞬間填滿 → 全域 429 → 所有 SDK 動態降採樣。

和 DevOps 背壓的關係

DevOps 流量管控討論通用的背壓概念（TCP flow control、message queue consumer lag、circuit breaker）。本系列聚焦 SDK ↔ collector 之間的具體實作 — HTTP 429 是訊號、動態取樣是回應、Go channel 容量是觸發條件。通用概念在 DevOps 模組，監控場景的具體機制在本系列。

完整章節

背壓在四層防線中的位置（第二層 collector 單機防護）→ Ingestion Scaling。背壓造成的資料損失和控制策略 → 端到端資料完整性。

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
• 查詢消費模式（各場景需要什麼事件）→ 查詢消費模式

點擊/觸碰感測器

點擊感測器偵測使用者和 UI 元素的互動 — 按鈕點擊、連結觸碰、選單選擇。每次互動產生一個 event 類型的事件。

哪些元素值得追蹤

追蹤粒度的判斷依據是「這個互動是否對應一個有意義的使用者意圖」。

有意義的互動（值得追蹤）：提交表單、點擊導航按鈕、觸發功能操作（連線、配對、匯出）。這些互動對應使用者的明確意圖，是 funnel 分析 的步驟候選。

低價值的互動（通常不追蹤）：滾動、hover、重複的相同操作（每秒多次的按鈕連按）。這些互動要麼太頻繁（滾動每秒觸發數十次），要麼不代表新的使用者意圖。

實作方式

Web（JS/TS）：在 document 層級用 event delegation 攔截 click 事件，過濾出帶 data-track attribute 的元素。開發者在需要追蹤的元素上加 data-track="connect-button"，感測器自動收集。不追蹤所有 click — 只追蹤被標記的。

Flutter：用 NavigatorObserver 或 custom GestureDetector wrapper。GestureDetector 包裝在需要追蹤的 widget 外層，onTap 觸發時送出事件。

效能影響

Event delegation 在 document 層級只有一個 listener，效能影響接近零。瓶頸在事件產生頻率 — 如果追蹤了高頻操作（每秒多次的滑動），事件進入 buffer 的速度可能超過 flush 的速度。用取樣控制（見本章末段）。

導航/路由感測器

導航感測器偵測使用者在不同畫面之間的切換 — page view、screen view、route change。每次切換產生一個 lifecycle 類型的事件。

平台差異

Web SPA：SPA 的 route 變換不觸發頁面載入，需要主動偵測 URL 變化。兩種偵測方式：

• History API 攔截：覆寫 pushState / replaceState，攔截 popstate 事件
• 框架層級 Hook：React Router 的 useLocation、Vue Router 的 afterEach guard

History API 攔截是 SDK 層的通用做法（不依賴框架）；框架 Hook 更精確但需要使用者整合（見 JS/TS 平台 的 SPA 路由段）。

Flutter：用 NavigatorObserver 的 didPush / didPop / didReplace 回呼。每次路由變化自動觸發，不需要使用者在每個頁面手動埋點。

Python CLI/Hook：沒有「畫面切換」的概念。對應的 lifecycle 事件是 hook.start / hook.complete — 每個 Hook 執行視為一個「畫面」。

事件 schema

1{
2  "type": "lifecycle",
3  "name": "screen.view",
4  "data": {
5    "screen_name": "TerminalScreen",
6    "previous_screen": "HomeScreen",
7    "navigation_method": "push"
8  }
9}

navigation_method（push / pop / replace / go）記錄導航方式，和 go vs push 的 UX 語意 對應。

錯誤邊界感測器

錯誤邊界感測器攔截元件級的 error — 和 auto-intercept 的全域 error 攔截互補。

和 auto-intercept 的職責分工

全域攔截捕獲「逃逸到頂層的 error」，錯誤邊界捕獲「在元件層級就被攔住的 error」。如果一個 error 被元件的 ErrorBoundary 捕獲，它不會觸發 window.onerror — auto-intercept 看不到它。錯誤邊界感測器填補這個缺口。

實作方式

React：ErrorBoundary 元件的 componentDidCatch 回呼中呼叫 monitor.error()。

Flutter：在 Widget 層用 ErrorWidget.builder 或自訂的 error handling widget。

額外 context

錯誤邊界感測器比全域攔截多一個 context — 知道 error 發生在哪個元件（component name / widget name）。這個資訊在 error 的 data schema 中記錄為 component 欄位。

效能標記感測器

效能標記感測器量測操作的延遲和系統的渲染表現。產生 metric 類型的事件。

Web Core Vitals

Web 平台用 PerformanceObserver API 自動收集三個核心指標：

• LCP（Largest Contentful Paint）：最大內容元素的載入時間
• FID（First Input Delay）：首次互動的延遲
• CLS（Cumulative Layout Shift）：累計佈局位移分數

1new PerformanceObserver((list) => {
2  for (const entry of list.getEntries()) {
3    monitor.metric(`web.vitals.${entry.entryType}`, {
4      value: entry.startTime || entry.value,
5      url: location.pathname
6    });
7  }
8}).observe({ type: 'largest-contentful-paint', buffered: true });

實務上依 entryType 分別取值（LCP 用 startTime、CLS 用 value、FID 用 processingStart - startTime），上述範例簡化示意。

Flutter frame timing

Flutter 用 SchedulerBinding.addTimingsCallback 偵測掉幀：

 1SchedulerBinding.instance.addTimingsCallback((timings) {
 2  for (final t in timings) {
 3    if (t.totalSpan > const Duration(milliseconds: 16)) {
 4      monitor.metric('render.frame_drop', {
 5        'build_ms': t.buildDuration.inMilliseconds,
 6        'raster_ms': t.rasterDuration.inMilliseconds,
 7      });
 8    }
 9  }
10});

16ms 是 60fps 的單幀預算。超過代表掉幀。

自訂 duration 量測

業務操作的延遲用手動標記量測：

1final stopwatch = Stopwatch()..start();
2await connectToTerminal();
3stopwatch.stop();
4monitor.metric('terminal.connect.duration', {
5  'duration_ms': stopwatch.elapsedMilliseconds,
6});

輸入敏感度感測器

輸入敏感度感測器偵測使用者正在輸入敏感資料 — 密碼欄位、API key 輸入、信用卡號碼。這個感測器的責任是觸發 redaction，而非記錄輸入內容。

偵測邏輯

Web：偵測 <input type="password">、帶有 autocomplete="cc-number" 或 data-sensitive attribute 的欄位。當使用者 focus 這些欄位時，標記當前 session 進入「敏感輸入模式」— 後續的事件自動加嚴 redaction 規則（例如暫停記錄按鍵事件）。

Flutter：偵測 TextField 的 obscureText: true 或 enableIMEPersonalizedLearning: false（見 安全敏感輸入框的 IME 控制）。

不記錄的原則

輸入敏感度感測器偵測「使用者正在輸入敏感內容」這個事實，但不記錄輸入的內容本身。送出的事件只包含：

1{
2  "type": "lifecycle",
3  "name": "input.sensitive_mode.entered",
4  "data": { "field_type": "password" }
5}

取樣策略設計