核心欄位

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

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

下一步路由

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

概念位置

Event Source 位在 queue、topic、HTTP gateway、object storage、scheduler 與 function / worker 之間，負責把外部事件轉成執行請求。

可觀察訊號

• 函式部署成功，但 invocation 因 trigger 設定失敗。
• Queue event 重試造成同一筆資料被重複處理。
• 事件 schema 漂移導致 subscriber 解析失敗。

接近真實服務的例子

Queue 觸發的 function 以 batch 方式處理訊息。新版本解析失敗時，訊息進入 dead-letter queue；團隊先停用 trigger，再修復 function 或重放事件。

設計責任

Event Source 要定義 trigger 條件、batch size、retry、dead-letter、replay、權限與 schema 契約，讓事件驅動發布具備可觀測回復路徑。