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。

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 一致性
• 自動攔截機制 → 模組三 自動攔截

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 與重試

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

統一格式：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 模組五 測試設計判斷