預設 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 模組三 協議整合測試

各平台的攔截點

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 → 攢批送出策略
• 主動感測器設計（和被動攔截互補）→ 前端感測器設計

待寫章節

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

三種策略

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 的端到端資料損失地圖 → 端到端資料完整性

預設 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 → 自動攔截機制

兩種取樣

靜態取樣：SDK config 中設定固定比例（例如 metric 類 0.1 = 每 10 筆只收 1 筆），在 SDK 整個生命週期保持不變。適合已知高頻但單筆 debug 價值低的事件（render.frame_time、scroll.position）。

動態取樣：SDK 在收到 collector 的 HTTP 429 後自動降低取樣率，collector 恢復正常後逐步回升。動態取樣在正常情況下不生效（取樣率 = 1.0），只在 collector 過載時啟用。和靜態取樣互補 — 靜態控制基線負載，動態應對突發。

取樣校正

分析時用取樣率還原原始量級。取樣率 0.1 時收到 100 筆事件，推估原始量為 100 / 0.1 = 1000 筆。SDK 端的 sdk.sampling.rate 指標記錄當前取樣率，讓下游分析知道如何校正。取樣校正對 funnel 和 cohort 分析有效（趨勢和比例不變），對個別事件追蹤無效（被丟棄的事件無法回復）。

設計責任

取樣承擔的設計責任是「在可觀測性覆蓋率和系統負載之間找到平衡」。Error 類事件不做取樣（每筆都可能是需要修的 bug），metric 類事件適合高比例取樣（丟幾筆不影響趨勢），event 類和 lifecycle 類取決於分析需求。

完整章節

靜態取樣率的設定 → 感測器生命週期管理。動態取樣在四層防線中的位置 → Ingestion Scaling。取樣造成的損失量化和控制 → 端到端資料完整性。

這個限制來自 architecture，和 implementation 無關。混淆 JS、ProGuard 混淆 APK、編譯 Python 成 .pyc，都只增加提取成本，不改變「credential 在 client 端」的事實。

Collector Access Control 討論了 API key 和 mTLS 的認證機制，Transport 安全 討論了傳輸層加密。兩者的前提是 credential 被妥善保管。本章處理的是那個前提不成立時 — credential 已被提取或必然可被提取 — 的緩解策略。

商業方案的處理方式

所有主流的 client-side telemetry 方案都面對同樣的限制。它們的共同策略是：承認 client credential 會暴露，把防線從「保護 credential」轉移到「限制 credential 被濫用的影響」。

Google Analytics 4：Measurement ID（G-XXXXXXXXXX）直接寫在網頁的 JS snippet 中，任何人檢視網頁原始碼都能取得。GA4 的防護在 server-side — Google 用 domain 白名單過濾來源，加上自動的 bot traffic 偵測剔除機器流量。Measurement Protocol（server-to-server）需要額外的 API secret，但 client-side 的 gtag.js 不需要。

Sentry：DSN（Data Source Name）包含 project ID 和 public key，直接嵌在 SDK init 的程式碼中。Sentry 官方文件明確標示 DSN 是 public 的 — 攻擊者取得 DSN 只能送事件，不能讀取已收集的資料。防護靠 rate limit（每個 project 的 events/sec 上限）、allowed domains（只接受來自白名單 domain 的事件）、和 server-side 的 event 去重。

Firebase：整個 google-services.json / GoogleService-Info.plist 的內容 — 包含 apiKey、projectId、appId — 都視為公開資訊。Firebase 的安全模型不依賴這些 key 的保密性；它們的功能是識別（identify）而非授權（authorize）。需要保護的資源靠 Firebase Security Rules 和 App Check（device attestation）處理。

Datadog RUM：Client token 是獨立於 API key 的 credential。API key 可以讀寫所有 Datadog 資料，必須保護在 server-side；client token 只能寫入 RUM 事件，設計上可以暴露在 client 端。Datadog 建議搭配 intake proxy（collector 前面加一層自己的 server），讓 client token 不直接出現在瀏覽器中。

這些方案的共同模式：client-side credential 的角色是「識別來源」而非「授權存取」。即使被提取，攻擊者能做的事被限縮在「寫入事件」— 影響可控。

認證天花板：識別 vs 授權

Collector Access Control 的 API key 同時承擔識別和授權 — 有 key 就能寫入，沒 key 就被拒絕。在 server-side 場景下這沒有問題，因為 key 不會暴露。

Client-side 場景需要拆開這兩個功能：

識別（identification）：這個 request 來自哪個 app、哪個 SDK、哪個部署版本。識別資訊可以公開 — 它的價值是讓 collector 知道事件來自哪裡，用於 access log、per-app rate limit、和事件標記。

授權（authorization）：這個 request 有沒有權限執行寫入操作。授權依賴 credential 的保密性 — 在 client-side 場景下，credential 保密性的天花板很低。

接受這個區分後，client-side SDK 的 API key 更接近「識別 token」。它的洩漏不是安全事件（像 server-side API key 洩漏那樣），而是預期中的狀態。防護的重點從「防止 key 洩漏」轉移到「限制 key 被濫用時的影響」。

多層緩解策略

以下各層按實作成本遞增排列。前面的層在多數場景下足夠，後面的層在 endpoint 暴露在公開網路且面對主動攻擊時才需要。

第一層：寫入限制（collector 已有）

Collector Access Control 的寫入限制 — rate limit、payload size limit、schema validation — 是第一層防護。這些機制不區分「合法 SDK」和「偽造 client」，對所有寫入請求一視同仁地施加約束。

Rate limit 限制每個 API key 的事件速率。Schema validation 拒絕不符合 event.schema.json 結構的 payload。兩者合起來把偽造流量的影響限制在「每秒 N 筆符合 schema 的事件」— 這個量級的資料汙染對 error tracking 的影響有限（error 事件靠 stack trace fingerprint 去重），對 funnel 分析的影響較大（行為事件的計數會被灌水）。

第二層：Origin 驗證

Web SDK 的 HTTP request 帶有瀏覽器自動附加的 Origin header。Collector 可以檢查 Origin 是否在白名單中。

 1func originCheck(next http.Handler, allowed []string) http.Handler {
 2    allowedSet := make(map[string]bool)
 3    for _, o := range allowed {
 4        allowedSet[o] = true
 5    }
 6    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 7        origin := r.Header.Get("Origin")
 8        if origin != "" && !allowedSet[origin] {
 9            http.Error(w, "forbidden origin", http.StatusForbidden)
10            return
11        }
12        next.ServeHTTP(w, r)
13    })
14}

Origin 驗證擋住的是「從瀏覽器中跨域呼叫」的場景 — 攻擊者在自己的網站用 JS 向你的 collector 發 request，瀏覽器會帶上攻擊者網站的 Origin，被 collector 拒絕。

天花板：Origin header 只有瀏覽器會自動附加。用 curl、Postman、或任何非瀏覽器 HTTP client 發 request 時，可以自行設定任意 Origin 值。Origin 驗證擋得住瀏覽器中的跨域呼叫，擋不住直接用 HTTP client 偽造的 request。

Mobile SDK（Flutter / native app）的 request 不帶 Origin header。Origin 驗證只對 Web SDK 有效。

第三層：Request signing

SDK 用 HMAC 對每個 request 簽章，collector 驗證簽章有效性。簽章的輸入包含 timestamp 和 payload hash，防止 replay attack 和 payload 竄改。

1X-Signature: a3f8c2e1b7d94f06...  (HMAC-SHA256 結果的 hex 編碼)
2X-Timestamp: 1719216000

SDK 計算方式：HMAC-SHA256(secret, timestamp + "." + SHA256(body))，結果轉 hex 字串放入 X-Signature header。

Collector 端的驗證邏輯：

 1func verifySignature(r *http.Request, secret string) bool {
 2    ts := r.Header.Get("X-Timestamp")
 3    sig := r.Header.Get("X-Signature")
 4
 5    // 拒絕超過 5 分鐘的 request timestamp（防 replay）
 6    // 5 分鐘容忍 client-server 時鐘漂移和網路延遲；行動裝置偏差大的環境可放寬到 10 分鐘
 7    // 此處的 timestamp 是 HTTP request 發出時間，和事件的 timestamp 欄位（事件產生時間）無關
 8    tsInt, err := strconv.ParseInt(ts, 10, 64)
 9    if err != nil || abs(time.Now().Unix()-tsInt) > 300 {
10        return false
11    }
12
13    body, _ := io.ReadAll(r.Body)
14    bodyHash := sha256.Sum256(body)
15    expected := hmac.New(sha256.New, []byte(secret))
16    expected.Write([]byte(ts + "." + hex.EncodeToString(bodyHash[:])))
17
18    sigBytes, err := hex.DecodeString(sig)
19    if err != nil {
20        return false
21    }
22    return hmac.Equal(sigBytes, expected.Sum(nil))
23}

Request signing 增加偽造成本 — 攻擊者需要提取 HMAC secret 並實作簽章邏輯，而非直接複製一個 API key 貼到 curl 指令。

HMAC secret 和 API key 一樣嵌在 client 端程式碼中，反編譯 APK 或閱讀 JS bundle 可以提取。Signing 增加的是攻擊者的工程投入（需要理解簽章算法並正確實作），而非理論上的安全性。對 casual attacker（看到 API key 就想試試的人）有效，對 motivated attacker（願意花時間逆向工程的人）無效。

第四層：行為分析異常偵測

Collector 端統計每個 API key（或 source.app）的事件模式，建立 baseline 後偵測偏離。

正常 SDK 的行為有可預測的特徵：

Collector 可以用 rule engine 偵測異常模式：

• 單一 API key 的事件量在 10 分鐘內超過過去 24 小時平均值的 10 倍
• 連續 N 個 request 的事件全是同一個 type
• source.sdk 欄位的值不在已知的 SDK 版本清單中

偵測到異常後的處理方式是標記而非丟棄 — 在事件中加入 _flags.suspicious = true flag，讓 dashboard 和分析查詢可以過濾。直接丟棄有誤殺正常流量的風險（例如行銷活動導致的真實流量暴增）。

攻擊者如果研究過正常 SDK 的行為模式（事件類型分布、送出間隔、payload 結構），可以模擬出相似的流量。行為分析依賴「偽造流量和正常流量有可偵測的差異」這個前提 — 對低投入的攻擊者成立，對高投入的攻擊者不一定。

第五層：Device attestation

由作業系統或平台層驗證 client 的合法性，提供 SDK 自身無法產生的證明。

Firebase App Check：整合 DeviceCheck（iOS）、Play Integrity（Android）、reCAPTCHA Enterprise（Web），由裝置平台出具 attestation token。Collector 向 Firebase 驗證 token 的有效性。

Apple DeviceCheck / App Attest：iOS 裝置向 Apple server 請求 attestation，證明 request 來自一台真實的、未被篡改的 iOS 裝置上的合法 app。

Google Play Integrity：驗證 request 來自 Google Play 安裝的 app、在未 root 的裝置上、由合法使用者操作。

Device attestation 提供的保證比前四層都強 — 它依賴裝置硬體和平台服務（難以偽造），而非 SDK 嵌入的 secret（可提取）。

天花板：

• 平台綁定 — 每個平台（iOS / Android / Web）需要各自整合不同的 attestation 服務，跨平台 SDK 的實作成本高
• Root / 越獄裝置上 attestation 可能失敗或被繞過
• Web 端的 reCAPTCHA 驗證依賴 Google 服務，有隱私和可用性的考量
• 自架 collector 需要額外整合 Firebase Admin SDK 或各平台的驗證 API

Device attestation 適合商業產品級的 mobile app，對自架監控工具而言實作成本通常超出收益。

自架方案的規模對應

不同部署規模下，需要做到哪一層取決於 endpoint 的暴露程度和偽造流量的影響大小。

Intake proxy 架構：在公開 endpoint 和商業產品場景下，可以在 collector 前面加一層自己的 server（proxy），SDK 送事件到 proxy，proxy 用 server-side API key 轉發到 collector。Client 端的 credential 只指向 proxy，proxy 的 API key 指向 collector — credential 分層，client 端的 key 洩漏不影響 collector 的認證。

1SDK ──(client token)──→ Intake Proxy ──(server API key)──→ Collector

Proxy 的額外成本是多一個 server 和網路跳躍。自用場景下不需要；endpoint 公開時值得考慮。

偽造流量的影響分析

偽造流量進入 collector 後，對不同類型的分析影響不同。

Error tracking 影響較低：error 事件的價值在 stack trace 和 error message。偽造的 error 事件缺少真實的 stack trace — 即使格式正確，內容是編造的。Error 去重靠 fingerprint（error type + message + stack trace top frame），偽造事件產生的 fingerprint 不會和真實 error 碰撞，在 dashboard 上是獨立的 error group，容易識別和過濾。

行為分析影響較高：funnel 和 cohort 分析依賴事件計數的準確性。偽造的 page.view 和 button.click 事件直接灌水計數，導致轉換率失真。偽造事件越接近真實事件的結構（正確的 event name、合理的 timestamp），影響越大。

資源消耗是固定成本：無論事件內容是否真實，每筆事件都消耗 collector 的寫入 I/O、儲存空間、和查詢時間。Rate limit 把這個成本限制在可控範圍 — 每秒 N 筆是上限，無論來源是否合法。

事後標記策略

偵測到可疑流量後，collector 在事件中加入標記欄位而非直接丟棄。丟棄有誤殺風險 — 行銷活動的流量暴增、SDK 版本升級改變了事件模式、新平台的 SDK 上線 — 這些正常場景可能觸發異常偵測。

標記方式是在 collector 寫入時，對符合異常條件的事件附加 metadata：

1{
2  "v": 1,
3  "type": "event",
4  "name": "button.click",
5  "source": { "sdk": "js", "platform": "web", "app": "main-site" },
6  "_flags": { "suspicious": true, "reason": "rate_anomaly" }
7}

Dashboard 查詢預設排除 _flags.suspicious = true 的事件。需要調查時可以包含 — 看可疑事件的模式有助於判斷是攻擊還是誤判。

下一步路由

• Collector 端的認證和授權機制 → Collector Access Control 實作
• Transport 層的加密保護 → Transport 安全
• Endpoint 濫用的威脅分析 → 監控資料洩漏的 Threat Model
• SDK 端的寫入速率控制 → Ingestion Scaling
• 行為分析和 rule engine → Rule Engine 設計
• 偽造流量對資料完整性的影響 → 端到端資料完整性
• Error fingerprint 讓偽造 error 容易辨識 → Error Fingerprint 與去重分群