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 模組二 客戶端可觀測性

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，商業方案的名稱是它的映射。在自架方案中改名後，映射層跟著改；不要讓商業方案的命名反過來影響自架的命名結構。

下一步路由

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

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 出現。

下一步路由

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

四個需求方向

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 設計
• 四個方向展開到具體事件名稱級 → 動機驅動的事件設計

從操作盤點推導事件

每個使用者操作（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 完整欄位解說
• 動機驅動的具體事件對應 → 動機驅動的事件設計

Debug 動機

Debug 動機驅動的事件收集目標是「問題發生時、開發者能從事件記錄中重建 context 並定位根因」。

要偵測的行為

• 多步驟流程的每一步完成或失敗（連線 → 認證 → 資料交換）
• 系統狀態轉換（前景/背景、連線/斷線、登入/登出）
• 非預期例外（uncaught exception、network error、timeout）
• 使用者最近的操作序列（問題發生前做了什麼）

事件表

查詢場景

Session 回放：按 session_id 過濾、按時間排序，還原「使用者做了什麼 → 系統發生了什麼 → 問題在哪裡出現」。

Error 根因定位：按 error name GROUP BY，找出最常出現的錯誤。單筆 error 的 stack_trace + 同 session 的 lifecycle 事件組合，判斷失敗發生在流程的哪一步。

最近 N 個操作：error 發生前的 10-20 個 event/lifecycle 事件，等同 Sentry 的 breadcrumb trail。

生命週期階段

開發期起全開。Debug 事件是最早需要的 — 實機測試階段就依賴這些事件定位問題。error 類和 lifecycle 類不做取樣（量低且每筆都可能是線索）。

商業動機

商業動機驅動的事件收集目標是「回答產品決策的問題 — 使用者在哪裡流失、不同群組行為有什麼差異、哪些功能被使用」。

要偵測的行為

• 漏斗步驟完成（註冊 → 啟用 → 付費 → 續約的每一步）
• 功能使用頻率（哪些功能被頻繁使用、哪些從未被觸發）
• Session 長度和頻率（使用者多常用、每次用多久）
• 關鍵轉換事件（首次付費、邀請好友、升級方案）

事件表

查詢場景

Funnel 轉換率：每步的完成數 / 上一步的完成數。SQLite 層做每步計數，PostgreSQL 層做 session 級 JOIN 的精確轉換率（見 功能分層與 Backend 選擇）。

Cohort 留存：按「首次使用週」分群，計算每週的回訪率。需要 session.start 事件 + 使用者首次出現的時間戳。

功能使用率：feature.*.used 事件按 name GROUP BY COUNT，排序找出最常/最少使用的功能。

生命週期階段

上線後啟用。開發期不需要商業事件（沒有真實使用者）。測試期可以用模擬流量驗證 funnel 事件的觸發正確性，但不做分析。

資安動機

資安動機驅動的事件收集目標是「偵測非預期的存取模式、追蹤敏感操作、提供事後稽核的 audit trail」。

要偵測的行為

• 認證失敗（密碼錯誤、biometric 失敗、token 過期）
• 權限越界嘗試（嘗試存取非自己的資源、呼叫無權限的 API）
• 敏感資料存取（查看個資、匯出資料、修改權限設定）
• 異常存取模式（短時間大量請求、非常規時段存取、來源 IP 變化）

事件表

查詢場景

認證失敗監控：auth.*.failed 事件的 count by session_id，短時間內同一 session 多次失敗 → 暴力破解嫌疑。Rule engine 設閾值告警。

Audit trail：sensitive.* 和 admin.* 事件按時間排列，回答「誰在什麼時候存取/修改了什麼」。合規審計的必要紀錄。

異常 pattern 偵測：auth 成功後的操作事件頻率和模式分析。正常使用者每 session 操作 10-50 次；自動化腳本可能操作數千次。

生命週期階段

開發期起全開。安全事件不能延後 — 「先不收安全事件、上線後再加」等於安全審計的空白期。認證相關事件是 auto-intercept 的一部分（見 自動攔截機制），不需要手動埋點。

和 redaction 的關係

資安事件本身可能包含敏感資訊（失敗的密碼、被存取的個資欄位名稱）。事件的 data schema 設計時標記需要 redaction 的欄位 — auth.failed 記錄失敗原因但不記錄輸入的密碼、sensitive.accessed 記錄資源類型但不記錄資源內容。

效能動機

效能動機驅動的事件收集目標是「發現效能退化趨勢、定位效能瓶頸、為容量規劃提供數據」。

要偵測的行為

• 操作回應時間（API 呼叫、頁面載入、動畫轉場）
• 渲染效能（frame rate、長任務、佈局重排）
• 資源使用（記憶體、CPU、網路流量）
• 外部依賴延遲（第三方 API、CDN、資料庫查詢）

事件表

查詢場景

P95 趨勢：{operation}.duration 事件按天聚合、計算 percentile_cont(0.95)，觀察回應時間是否隨版本增加。

容量規劃：resource.memory 事件的趨勢圖，判斷記憶體是否隨使用時間穩定增長（memory leak 訊號）。

依賴健康度：dependency.*.latency 事件按 dependency_name GROUP BY，比較各依賴的平均延遲和失敗率。

生命週期階段

測試期起啟用。開發期不需要效能事件（本地環境的效能數據不代表 production）。測試期啟用用於建立效能 baseline。上線後持續收集用於趨勢監控。

效能事件量通常最大（每 30 秒一筆 resource.memory × 活躍使用者數），取樣率需要控制 — 自用場景全收、商業產品取樣 10-50%（見 前端感測器設計 的取樣策略段）。

A/B 測試動機

A/B 測試動機驅動的事件是商業動機的延伸 — 實驗期間收集實驗分組和轉換事件，實驗結束後關閉。

事件表

生命週期階段

實驗期間啟用，實驗結束後關閉（從 SDK config 或 feature flag 移除）。實驗事件的保留期限跟著實驗週期走 — 實驗結束 + 分析完成後可清除。A/B test 的統計分析見 A/B test 的統計基礎。

完整對照總表

下一步路由

• 四類事件的基礎定義 → 四類事件的完整定義
• 事件枚舉的方法論 → 事件枚舉與補齊檢查
• 前端感測器的具體設計 → 前端感測器設計
• 感測器的生命週期控制 → 感測器生命週期管理
• 查詢消費模式的完整展開 → 查詢消費模式