核心欄位

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

原則一：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 差異對照

不需要改版的變更

新增選填欄位

在 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 差異對照

設計目標差異

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 設計