CORS 限制

瀏覽器的同源政策限制網頁讀取不同 origin 的回應；collector 和網頁不在同一個 origin（protocol、domain、port 有任一不同）時，SDK 送出的請求受 CORS 規則約束。跨域請求要不要先送 preflight OPTIONS，由請求的方法與標頭決定：POST 的 Content-Type 是 CORS 安全清單內的值（text/plain、application/x-www-form-urlencoded、multipart/form-data）、而且沒有加自訂標頭時，不送 preflight；Content-Type 是 application/json 這類清單外的值時，瀏覽器先送 preflight，collector 回應允許之後才送出正式的請求。

SDK 端有兩種送法：

navigator.sendBeacon(url, data) 的用途是頁面進入背景或關閉時仍要送出的資料：Beacon 規範要求瀏覽器在頁面的 visibilityState 變成 hidden 時立即送出排隊中的 beacon，所以 flush 的程式註冊在 visibilitychange 事件上，比註冊在 unload 事件上可靠。它的 CORS 行為照上一段的規則：傳入資料的型別是安全清單內的 Content-Type 時以 no-cors 模式送出、不送 preflight；傳入 application/json 型別的 Blob 時要先 preflight。beacon 一律帶 credentials（Cookie），所以要 preflight 的那一種情形，collector 的 Access-Control-Allow-Origin 要寫出網頁的 origin、不能用 *，並回 Access-Control-Allow-Credentials: true，否則瀏覽器的 CORS 檢查判定失敗。

sendBeacon 的限制：一律用 POST 送出，不能指定請求方法與其他標頭（Content-Type 由傳入資料的型別決定）；payload 與 fetch 的 keepalive 請求共用同一份在途上限（Fetch 規範定為 64 KiB），超過時 sendBeacon 回傳 false、不送出；沒有回應 — 送出後無法知道 server 是否收到。

fetch 用在需要讀取回應、或送出超過 keepalive 上限的大 payload 時。以 JSON 送出時 collector 要回 Access-Control-Allow-Origin、Access-Control-Allow-Methods: POST、Access-Control-Allow-Headers: Content-Type；請求另外帶 Cookie（credentials: 'include'）時，Access-Control-Allow-Origin 同樣要寫出網頁的 origin，並加 Access-Control-Allow-Credentials: true。fetch 加上 keepalive: true 也能在頁面關閉時繼續送出，與 sendBeacon 共用 64 KiB 的上限。

Service Worker 攔截

依 Fetch 規範，頁面送出的 fetch、XHR 與 sendBeacon 請求，都會觸發控制這個頁面的 Service Worker 的 fetch 事件（請求預設的 service-workers mode 是 all，Beacon 規範沒有改它）；瀏覽器實作是否對 sendBeacon 這類 keepalive 請求派送事件，以各瀏覽器的文件為準。監控請求在這一層會遇到什麼問題，取決於 SDK 用哪一種請求方法送資料：HTTP 快取與 Service Worker 的 Cache API，規則都按請求方法區分，而方法是由要送的資料形狀決定的。

GET 像素：把事件欄位放進網址的查詢參數，用 new Image().src 或 GET 請求送出。選它的需求是相容性，以及跨網域不必 preflight（沒有 crossorigin 屬性的圖片請求以 no-cors 模式送出），代價是只能帶少量欄位、受網址長度限制。GET 依 HTTP 語意可以被快取（12.2 新鮮度期限的計算：max-age、s-maxage、Expires 與啟發式期限），同一個網址的事件可能在三個位置被直接回應、沒有送到 collector，三個位置各有自己的處置：

• 瀏覽器的 HTTP 快取與轉送代理：collector 對這個路徑回 Cache-Control: no-store；用 fetch 送時另加 cache: 'no-store'，讓瀏覽器的 HTTP 快取不讀也不存（快取模式見 12.7 瀏覽器端的快取行為：重新整理、強制重新整理與上一頁 的〈Fetch 規範的快取模式〉）。
• Service Worker 用 Cache API 存下的回應：Cache API 不看 Cache-Control 標頭，也不看 fetch 的 cache 選項，要由 Service Worker 對 collector 的路徑不呼叫 event.respondWith()，讓請求照常送往網路。
• 三個位置一起避開：每次請求帶唯一的查詢參數（例如 ?_t=<時間戳>），讓網址不同、對不上任何保存的副本。Service Worker 用 cache.match 比對時若設了 ignoreSearch，查詢參數不參與比對，這個方法在那裡無效。用 Image 送時沒有 cache 選項可設，唯一的查詢參數是 SDK 端能控制的方法。

POST（sendBeacon、fetch、XHR）：把錯誤堆疊、操作紀錄、效能數據這類結構化資料放在請求的 body。選它的需求是資料量與結構，以及頁面關閉時仍要送出。RFC 9110 §9.3.3 寫明 POST 請求不會由快取裡保存的 POST 回應回答（「a POST request cannot be satisfied by a cached POST response」）；Service Worker 規範的 Cache API 也只接受 GET：cache.put 對 POST 回傳以 TypeError 拒絕的 promise，cache.match 在沒有設 ignoreMethod 時對不到任何副本。所以「監控請求被快取、沒有送到 collector」不會發生在這種送法上，no-store 與唯一查詢參數對它沒有作用。

POST 的風險在 Service Worker 的程式本身：fetch 事件仍然會收到這個請求。常見的寫法是先 fetch(event.request)，再把回應用 cache.put 存進快取；遇到 POST 時，put 被拒絕的 promise 若接在 respondWith() 的鏈上，頁面拿到網路錯誤，而這時請求通常已經送到 collector，SDK 若因此重送，collector 會收到重複的事件。離線優先的處理程式若在網路失敗時回一個預設的回應，SDK 拿到的是假的成功。處置與 GET 的那一條相同：Service Worker 對非 GET 的請求、或 collector 的路徑不呼叫 respondWith()。

兩種送法的差別在於：POST 不需要防快取的處置，GET 除了防快取的處置，也要 Service Worker 放行。檢查時先確認 SDK 實際送出的請求方法：在瀏覽器開發者工具的 Network 面板點開那一筆請求，Headers 分頁的 Request Method 寫著方法。

如果 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 模組五 測試設計判斷